docs

CHANGELOG.md

@@ -1,6 +1,17 @@
 Change Log
 ==========
 
+v2.0.0
+------
+- Dropped support for Python 2.x
+- New flexible syntax for database expressions and functions
+- Expressions as default values for model fields
+- Support for IPv4 and IPv6 fields
+- Automatic generation of models by inspecting existing tables
+- Convenient ways to import ORM classes
+
+See [What's new in version 2](docs/whats_new_in_version_2.md) for details.
+
 v1.4.0
 ------
 - Added primary_key parameter to MergeTree engines (M1hacka)

docs/expressions.md

@@ -13,7 +13,7 @@ Using Expressions
 
 Expressions usually include ClickHouse database functions, which are made available by the `F` class. Here's a simple function:
 ```python
-from infi.clickhouse_orm.models import F
+from infi.clickhouse_orm import F
 expr = F.today()
 ```
 
@@ -22,9 +22,9 @@ Functions that accept arguments can be composed, just like when using SQL:
 expr = F.toDayOfWeek(F.today())
 ```
 
-You can see the SQL expression that is represented by an ORM expression by calling its `to_sql` or `repr` methods:
+You can see the SQL expression that is represented by an ORM expression by calling its `to_sql` method or converting it to a string:
 ```python
->>> print(expr.to_sql())
+>>> print(expr)
 toDayOfWeek(today())
 ```
 
@@ -42,6 +42,8 @@ There is also support for comparison operators (`<`, `<=`, `==`, `>=`, `>`, `!=`
 (F.toDayOfWeek(F.today()) == 6) & (F.toDayOfMonth(F.today()) == 13)
 ```
 
+Note that Python's bitwise operators (`&`, `|`, `~`, `^`) have higher precedence than comparison operators, so always use parentheses when combining these two types of operators in an expression. Otherwise the resulting SQL might be different than what you would expect.
+
 ### Referring to model fields
 
 To refer to a model field inside an expression, use `<class>.<field>` syntax, for example:

docs/importing_orm_classes.md

@@ -41,7 +41,7 @@ Importing Everything into a Namespace
 To prevent potential name clashes and to make the code more readable, you can import the ORM's classes into a namespace of your choosing, e.g. `orm`. For brevity, it is recommended to import the `F` class explicitly:
 ```python
 import infi.clickhouse_orm as orm
-from infi.clickhouse_orm.funcs import F
+from infi.clickhouse_orm import F
 
 class Event(orm.Model):
 

docs/models_and_databases.md

@@ -152,7 +152,7 @@ When running a query, specifying a model class is not required. In case you do n
 
 This is a very convenient feature that saves you the need to define a model for each query, while still letting you work with Pythonic column values and an elegant syntax.
 
-It is also possible to generate a model class on the fly for an existing table in the database using `get_model_for_table`. This is particulary useful for querying system tables, for example:
+It is also possible to generate a model class on the fly for an existing table in the database using `get_model_for_table`. This is particularly useful for querying system tables, for example:
 
     QueryLog = db.get_model_for_table('query_log', system_table=True)
     for row in QueryLog.objects_in(db).filter(QueryLog.query_duration_ms > 10000):