feat: update docs (#310)

Author: kalombos

docs/index.rst

@@ -24,66 +24,17 @@ The source code is hosted on `GitHub`_.
 
 .. _GitHub: https://github.com/05bit/peewee-async
 
-Quickstart
-----------
-
-.. literalinclude:: ./samples/quickstart.py
-
-
-Install
--------
-
-Install latest version from PyPI.
-
-For PostgreSQL:
-
-.. code-block:: console
-
-    pip install peewee-async[postgresql]
-
-For MySQL:
-
-.. code-block:: console
-
-    pip install peewee-async[mysql]
-
-Install from sources
-++++++++++++++++++++
-
-.. code-block:: console
-
-    git clone https://github.com/05bit/peewee-async.git
-    cd peewee-async
-    pip install .
-
-Running tests
-+++++++++++++
-
-Prepare environment for tests:
-
-* Clone source code from GitHub as shown above
-* Run docker environment with PostgreSQL database for testing
-
-Then run tests:
-
-.. code-block:: console
-
-    pytest -s -v
-
-Report bugs and discuss
------------------------
-
-You are welcome to add discussion topics or bug reports to `tracker on GitHub`_!
-
-.. _tracker on GitHub: https://github.com/05bit/peewee-async/issues
 
 Contents
 --------
 
 .. toctree::
    :maxdepth: 2
 
+   peewee_async/installing
+   peewee_async/quickstart
    peewee_async/api
+   peewee_async/connection
    peewee_async/examples
 
 Indices and tables

docs/peewee_async/api.rst

@@ -1,64 +1,9 @@
 API Documentation
 ====================
 
-Let's provide an example::
-
-    import asyncio
-    import peewee
-    import logging
-    from peewee_async import PostgresqlDatabase
-
-    database = PostgresqlDatabase('test')
-
-    # Disable sync queries
-    database.set_allow_sync(False)
-
-    # Let's define a simple model:
-    class PageBlock(peewee_async.AioModel):
-        key = peewee.CharField(max_length=40, unique=True)
-        text = peewee.TextField(default='')
-
-        class Meta:
-            database = database
-
--- as you can see, nothing special in this code, just plain ``peewee_async.AioModel`` definition and disabling sync queries.
-
-Now we need to create a table for model::
-
-    with database.allow_sync():
-       PageBlock.create_table(True)
-
--- this code is **sync**, and will do **absolutely the same thing** as would do code with regular ``peewee.PostgresqlDatabase``. This is intentional, I believe there's just no need to run database initialization code asynchronously! *Less code, less errors*.
-
-Finally, let's do something async::
-
-    async def my_async_func():
-        # Add new page block
-        await PageBlock.aio_create(
-            key='title',
-            text="Peewee is AWESOME with async!"
-        )
-
-        # Get one by key
-        title = await PageBlock.aio_get(PageBlock, key='title')
-        print("Was:", title.text)
-
-        # Save with new text using manager
-        title.text = "Peewee is SUPER awesome with async!"
-        await title.aio_save()
-        print("New:", title.text)
-
-    loop.run_until_complete(my_async_func())
-    loop.close()
-
-**That's it!** As you may notice there's no need to connect and re-connect before executing async queries! It's all automatic. But you can run ``AioDatabase.aio_connect()`` or ``AioDatabase.aio_close()`` when you need it.
-
-And you can use methods from from **AioModel** for operations like selecting, deleting etc.
-All of them are listed below.
-
 
 Databases
----------
+++++++++++
 
 .. autoclass:: peewee_async.databases.AioDatabase
 
@@ -89,7 +34,7 @@ Databases
     :members: init
 
 AioModel
---------
+++++++++++
 
 .. autoclass:: peewee_async.AioModel
 
@@ -108,7 +53,7 @@ AioModel
 .. autofunction:: peewee_async.aio_prefetch
 
 AioModelSelect
---------------
+++++++++++++++
 
 .. autoclass:: peewee_async.aio_model.AioModelSelect
 

docs/peewee_async/connection.rst

@@ -0,0 +1,59 @@
+Working with connections
+========================
+
+Every time some query is executed, for example, like this:
+
+.. code-block:: python
+
+    await MyModel.aio_get(id=1)
+
+
+under the hood the execution runs under special async context manager:
+
+.. code-block:: python
+
+    async with database.aio_connection() as connection:
+        await execute_your_query()
+
+which takes a connection from the ``connection_context`` contextvar if it is not ``None`` or acquire from the pool otherwise. 
+It releases the connection at the exit and set the ``connection_context`` to ``None``.
+
+
+.. code-block:: python
+
+    # acquire a connection and put it to connection_context context variable
+    await MyModel.aio_get(id=1)
+    # release the connection and set the connection_context to None
+
+    # acquire a connection and put it to connection_context context variable
+    await MyModel.aio_get(id=2)
+    # release the connection and set the connection_context to None
+
+    # acquire a connection and put it to connection_context context variable
+    await MyModel.aio_get(id=3)
+    # release the connection and set the connection_context to None
+
+Connections manual management
+++++++++++++++++++++++++++++
+
+If you want to manage connections manually or you want to use one connection for a batch of queries you 
+can run ``database.aio_connection`` by yourself and run the queries under the context manager.
+
+.. code-block:: python
+
+    # acquire a connection and put it to connection_context context variable
+    async with database.aio_connection() as connection:
+        
+        # using the connection from the contextvar
+        await MyModel.aio_get(id=1)
+
+        # using the connection from the contextvar
+        await MyModel.aio_get(id=2)
+
+        # using the connection from the contextvar
+        await MyModel.aio_get(id=3)
+    # release the connection set connection_context to None at the exit of the async contextmanager
+
+You can even run nested ``aio_connection`` context managers. 
+In this case you will use one connection for the all managers from the highest context manager of the stack of calls 
+and it will be closed when the highest manager is exited.

docs/peewee_async/examples.rst

@@ -3,7 +3,7 @@ Examples
 
 
 Using both sync and async calls
--------------------------------
++++++++++++++++++++++++++++++++
 
 .. code-block:: python
 
@@ -40,7 +40,7 @@ Using both sync and async calls
 
 
 Using transactions
-------------------
+++++++++++++++++++
 
 .. code-block:: python
 
@@ -66,7 +66,7 @@ Using transactions
     loop.run_until_complete(test())
 
 Using async peewee with Tornado
--------------------------------
++++++++++++++++++++++++++++++++
 
 `Tornado`_ is a mature and powerful asynchronous web framework. It provides its own event loop, but there's an option to run Tornado on asyncio event loop. And that's exactly what we need!
 

docs/peewee_async/installing.rst

@@ -0,0 +1,71 @@
+Installing
+====================
+
+Install latest version from PyPI.
+
+For PostgreSQL aiopg backend:
+
+.. code-block:: console
+
+    pip install peewee-async[postgresql]
+
+For PostgreSQL psycopg3 backend:
+
+.. code-block:: console
+
+    pip install peewee-async[psycopg]
+
+For MySQL:
+
+.. code-block:: console
+
+    pip install peewee-async[mysql]
+
+Installing and developing
++++++++++++++++++++++++++
+
+Clone source code from GitHub:
+
+.. code-block:: console
+
+    git clone https://github.com/05bit/peewee-async.git
+    cd peewee-async
+
+Install dependencies using pip:
+
+.. code-block:: console
+
+    pip install -e .[develop]
+
+
+Or using `poetry`_:
+
+.. _poetry: https://python-poetry.org/docs/
+
+.. code-block:: console
+
+    poetry install -E develop
+
+
+Running tests
++++++++++++++
+
+* Clone source code from GitHub as shown above
+* Run docker environment with PostgreSQL database for testing
+
+.. code-block:: console
+
+    docker-compose up -d
+
+Then run tests:
+
+.. code-block:: console
+
+    pytest -s -v
+
+Report bugs and discuss
++++++++++++++++++++++++
+
+You are welcome to add discussion topics or bug reports to `tracker on GitHub`_!
+
+.. _tracker on GitHub: https://github.com/05bit/peewee-async/issues

docs/peewee_async/quickstart.rst

@@ -0,0 +1,57 @@
+Quickstart
+====================
+
+Let's provide an example::
+
+    import asyncio
+    import peewee
+    import logging
+    from peewee_async import PooledPostgresqlDatabase
+
+    database = PooledPostgresqlDatabase('test')
+
+    # Disable sync queries
+    database.set_allow_sync(False)
+
+    # Let's define a simple model:
+    class PageBlock(peewee_async.AioModel):
+        key = peewee.CharField(max_length=40, unique=True)
+        text = peewee.TextField(default='')
+
+        class Meta:
+            database = database
+
+-- as you can see, nothing special in this code, just plain ``peewee_async.AioModel`` definition and disabling sync queries.
+
+Now we need to create a table for model::
+
+    with database.allow_sync():
+       PageBlock.create_table(True)
+
+-- this code is **sync**, and will do **absolutely the same thing** as would do code with regular ``peewee.PostgresqlDatabase``. This is intentional, I believe there's just no need to run database initialization code asynchronously! *Less code, less errors*.
+
+Finally, let's do something async::
+
+    async def my_async_func():
+        # Add new page block
+        await PageBlock.aio_create(
+            key='title',
+            text="Peewee is AWESOME with async!"
+        )
+
+        # Get one by key
+        title = await PageBlock.aio_get(key='title')
+        print("Was:", title.text)
+
+        # Save with new text using manager
+        title.text = "Peewee is SUPER awesome with async!"
+        await title.aio_save()
+        print("New:", title.text)
+
+    loop.run_until_complete(my_async_func())
+    loop.close()
+
+**That's it!** As you may notice there's no need to connect and re-connect before executing async queries! It's all automatic. But you can run ``AioDatabase.aio_connect()`` or ``AioDatabase.aio_close()`` when you need it.
+
+And you can use methods from from **AioModel** for operations like selecting, deleting etc.
+All of them you can find in the next section.