Add basic transactions usage example

docs/peewee_async/api.rst

@@ -16,7 +16,10 @@ Select, update, delete
 Transactions
 ------------
 
-**Warning** For some reason doesn't work with pooled connection yet! This is bug, of course.
+Transactions required Python 3.5+ to work, because their syntax is based on async context managers.
+
+**Important note** transactions rely on data isolation on `asyncio` per-task basis.
+That means, all queries for single transaction should be performed **within same task**.
 
 .. autofunction:: peewee_async.atomic
 .. autofunction:: peewee_async.savepoint

docs/peewee_async/examples.rst

@@ -102,3 +102,31 @@ Using both sync and async calls
 
     loop.run_until_complete(database.connect_async(loop=loop))
     loop.run_until_complete(my_handler())
+
+
+Using transactions
+------------------
+
+.. code-block:: python
+
+    import asyncio
+    import peewee
+    import peewee_async
+
+    # ... some init code ...
+
+    async def test():
+        obj = await create_object(TestModel, text='FOO')
+        obj_id = obj.id
+
+        try:
+            async with database.atomic_async():
+                obj.text = 'BAR'
+                await update_object(obj)
+                raise Exception('Fake error')
+        except:
+            res = await get_object(TestModel, TestModel.id == obj_id)
+
+        print(res.text) # Should print 'FOO', not 'BAR'
+
+    loop.run_until_complete(test())

docs/requirements.txt

@@ -1,2 +1,3 @@
-peewee>=2.6.1
-aiopg>=0.7.0
+peewee>=2.8.0
+aiopg>=0.9.2
+tasklocals>=0.2

peewee_async.py

@@ -42,9 +42,14 @@
     'sync_unwanted',
     'UnwantedSyncQueryError',
 
-    # Aggregation:
+    # Aggregation
     'count',
     'scalar',
+
+    # Transactions
+    'atomic',
+    'transaction',
+    'savepoint',
 ]
 
 

setup.py

@@ -17,7 +17,7 @@
     zip_safe=False,
     install_requires=(
         'peewee>=2.8.0',
-        'aiopg>=0.7.0',
+        'aiopg>=0.9.2',
         'tasklocals>=0.2',
     ),
     py_modules=[