TRIVIAL pypi documentation

This commit is contained in:
Itai Shirav 2016-06-28 11:49:43 +03:00
parent 8a7560b9ef
commit 553ebf0151
3 changed files with 21 additions and 53 deletions

View File

@ -17,9 +17,7 @@ Usage
Defining Models Defining Models
--------------- ---------------
Models are defined in a way reminiscent of Django's ORM: Models are defined in a way reminiscent of Django's ORM::
.. code:: python
from infi.clickhouse_orm import models, fields, engines from infi.clickhouse_orm import models, fields, engines
@ -39,9 +37,7 @@ See below for the supported field types and table engines.
Using Models Using Models
------------ ------------
Once you have a model, you can create model instances: Once you have a model, you can create model instances::
.. code:: python
>>> dan = Person(first_name='Dan', last_name='Schwartz') >>> dan = Person(first_name='Dan', last_name='Schwartz')
>>> suzy = Person(first_name='Suzy', last_name='Jones') >>> suzy = Person(first_name='Suzy', last_name='Jones')
@ -49,9 +45,7 @@ Once you have a model, you can create model instances:
u'Dan' u'Dan'
When values are assigned to model fields, they are immediately converted to their Pythonic data type. When values are assigned to model fields, they are immediately converted to their Pythonic data type.
In case the value is invalid, a ``ValueError`` is raised: In case the value is invalid, a ``ValueError`` is raised::
.. code:: python
>>> suzy.birthday = '1980-01-17' >>> suzy.birthday = '1980-01-17'
>>> suzy.birthday >>> suzy.birthday
@ -64,24 +58,18 @@ In case the value is invalid, a ``ValueError`` is raised:
Inserting to the Database Inserting to the Database
------------------------- -------------------------
To write your instances to ClickHouse, you need a ``Database`` instance: To write your instances to ClickHouse, you need a ``Database`` instance::
.. code:: python
from infi.clickhouse_orm.database import Database from infi.clickhouse_orm.database import Database
db = Database('my_test_db') db = Database('my_test_db')
This automatically connects to http://localhost:8123 and creates a database called my_test_db, unless it already exists. This automatically connects to http://localhost:8123 and creates a database called my_test_db, unless it already exists.
If necessary, you can specify a different database URL and optional credentials: If necessary, you can specify a different database URL and optional credentials::
.. code:: python
db = Database('my_test_db', db_url='http://192.168.1.1:8050', username='scott', password='tiger') db = Database('my_test_db', db_url='http://192.168.1.1:8050', username='scott', password='tiger')
Using the ``Database`` instance you can create a table for your model, and insert instances to it: Using the ``Database`` instance you can create a table for your model, and insert instances to it::
.. code:: python
db.create_table(Person) db.create_table(Person)
db.insert([dan, suzy]) db.insert([dan, suzy])
@ -91,18 +79,14 @@ The ``insert`` method can take any iterable of model instances, but they all mus
Reading from the Database Reading from the Database
------------------------- -------------------------
Loading model instances from the database is simple: Loading model instances from the database is simple::
.. code:: python
for person in db.select("SELECT * FROM my_test_db.person", model_class=Person): for person in db.select("SELECT * FROM my_test_db.person", model_class=Person):
print person.first_name, person.last_name print person.first_name, person.last_name
Do not include a ``FORMAT`` clause in the query, since the ORM automatically sets the format to ``TabSeparatedWithNamesAndTypes``. Do not include a ``FORMAT`` clause in the query, since the ORM automatically sets the format to ``TabSeparatedWithNamesAndTypes``.
It is possible to select only a subset of the columns, and the rest will receive their default values: It is possible to select only a subset of the columns, and the rest will receive their default values::
.. code:: python
for person in db.select("SELECT first_name FROM my_test_db.person WHERE last_name='Smith'", model_class=Person): for person in db.select("SELECT first_name FROM my_test_db.person WHERE last_name='Smith'", model_class=Person):
print person.first_name print person.first_name
@ -111,9 +95,7 @@ Ad-Hoc Models
************* *************
Specifying a model class is not required. In case you do not provide a model class, an ad-hoc class will Specifying a model class is not required. In case you do not provide a model class, an ad-hoc class will
be defined based on the column names and types returned by the query: be defined based on the column names and types returned by the query::
.. code:: python
for row in db.select("SELECT max(height) as max_height FROM my_test_db.person"): for row in db.select("SELECT max(height) as max_height FROM my_test_db.person"):
print row.max_height print row.max_height
@ -124,9 +106,7 @@ you work with Pythonic column values and an elegant syntax.
Counting Counting
-------- --------
The ``Database`` class also supports counting records easily: The ``Database`` class also supports counting records easily::
.. code:: python
>>> db.count(Person) >>> db.count(Person)
117 117
@ -161,27 +141,19 @@ Table Engines
Each model must have an engine instance, used when creating the table in ClickHouse. Each model must have an engine instance, used when creating the table in ClickHouse.
To define a ``MergeTree`` engine, supply the date column name and the names (or expressions) for the key columns: To define a ``MergeTree`` engine, supply the date column name and the names (or expressions) for the key columns::
.. code:: python
engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate')) engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate'))
You may also provide a sampling expression: You may also provide a sampling expression::
.. code:: python
engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate'), sampling_expr='intHash32(UserID)') engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate'), sampling_expr='intHash32(UserID)')
A ``CollapsingMergeTree`` engine is defined in a similar manner, but requires also a sign column: A ``CollapsingMergeTree`` engine is defined in a similar manner, but requires also a sign column::
.. code:: python
engine = engines.CollapsingMergeTree('EventDate', ('CounterID', 'EventDate'), 'Sign') engine = engines.CollapsingMergeTree('EventDate', ('CounterID', 'EventDate'), 'Sign')
For a ``SummingMergeTree`` you can optionally specify the summing columns: For a ``SummingMergeTree`` you can optionally specify the summing columns::
.. code:: python
engine = engines.SummingMergeTree('EventDate', ('OrderID', 'EventDate', 'BannerID'), engine = engines.SummingMergeTree('EventDate', ('OrderID', 'EventDate', 'BannerID'),
summing_cols=('Shows', 'Clicks', 'Cost')) summing_cols=('Shows', 'Clicks', 'Cost'))
@ -189,9 +161,7 @@ For a ``SummingMergeTree`` you can optionally specify the summing columns:
Data Replication Data Replication
**************** ****************
Any of the above engines can be converted to a replicated engine (e.g. ``ReplicatedMergeTree``) by adding two parameters, ``replica_table_path`` and ``replica_name``: Any of the above engines can be converted to a replicated engine (e.g. ``ReplicatedMergeTree``) by adding two parameters, ``replica_table_path`` and ``replica_name``::
.. code:: python
engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate'), engine = engines.MergeTree('EventDate', ('CounterID', 'EventDate'),
replica_table_path='/clickhouse/tables/{layer}-{shard}/hits', replica_table_path='/clickhouse/tables/{layer}-{shard}/hits',

View File

@ -3,20 +3,19 @@ prefer-final = false
newest = false newest = false
download-cache = .cache download-cache = .cache
develop = . develop = .
parts = parts =
[project] [project]
name = infi.clickhouse_orm name = infi.clickhouse_orm
company = Infinidat company = Infinidat
namespace_packages = ['infi'] namespace_packages = ['infi']
install_requires = [ install_requires = [
'pytz', 'pytz',
'requests', 'requests',
'setuptools' 'setuptools'
] ]
version_file = src/infi/clickhouse_orm/__version__.py version_file = src/infi/clickhouse_orm/__version__.py
description = A Python library for working with the ClickHouse database description = A Python library for working with the ClickHouse database
long_description = A Python library for working with the ClickHouse database
console_scripts = [] console_scripts = []
gui_scripts = [] gui_scripts = []
package_data = [] package_data = []
@ -49,7 +48,7 @@ eggs = ${project:name}
infi.traceback infi.traceback
zc.buildout zc.buildout
scripts = ipython scripts = ipython
nosetests nosetests
interpreter = python interpreter = python
[pack] [pack]

View File

@ -8,7 +8,6 @@ SETUP_INFO = dict(
url = ${infi.recipe.template.version:homepage}, url = ${infi.recipe.template.version:homepage},
license = 'PSF', license = 'PSF',
description = """${project:description}""", description = """${project:description}""",
long_description = """${project:long_description}""",
# http://pypi.python.org/pypi?%3Aaction=list_classifiers # http://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers = [ classifiers = [