improving engine docs

Author: dantownsend

docs/src/piccolo/engines/index.rst

@@ -10,6 +10,8 @@ It's important that each ``Table`` class knows which engine to use. There are
 two ways of doing this - setting it explicitly via the ``db`` argument, or
 letting Piccolo find it using ``engine_finder``.
 
+-------------------------------------------------------------------------------
+
 Explicit
 --------
 
@@ -30,6 +32,7 @@ connect to a database.
     class MyTable(Table, db=DB):
         name = Varchar()
 
+-------------------------------------------------------------------------------
 
 engine_finder
 -------------
@@ -94,6 +97,8 @@ variable accordingly.
 
 .. hint:: You can also specify sub modules, like `my_module.piccolo_conf`.
 
+-------------------------------------------------------------------------------
+
 .. _EngineTypes:
 
 Engine types
@@ -103,83 +108,8 @@ Engine types
  production. It is the most feature complete.
 
 
-SQLiteEngine
-~~~~~~~~~~~~
-
-.. code-block:: python
-
-    # piccolo_conf.py
-    from piccolo.engine.sqlite import SQLiteEngine
-
-
-    DB = SQLiteEngine(path='my_app.sqlite')
-
-
-PostgresEngine
-~~~~~~~~~~~~~~
-
-.. code-block:: python
-
-    # piccolo_conf.py
-    from piccolo.engine.postgres import PostgresEngine
-
-
-    DB = PostgresEngine({
-        'host': 'localhost',
-        'database': 'my_app',
-        'user': 'postgres',
-        'password': ''
-    })
-
-Connection pool
----------------
-
-.. warning:: This is currently only available for Postgres.
-
-
-To use a connection pool, you need to first initialise it. The best place to do
-this is in the startup event handler of whichever web framework you are using.
-
-Here's an example using Starlette. Notice that we also close the connection
-pool in the shutdown event handler.
-
-.. code-block:: python
-
-    from piccolo.engine import from starlette.applications import Starlette
-    from starlette.applications import Starlette
-
-
-    app = Starlette()
-
-
-    @app.on_event('startup')
-    async def open_database_connection_pool():
-        engine = engine_finder()
-        await engine.start_connnection_pool()
-
-
-    @app.on_event('shutdown')
-    async def close_database_connection_pool():
-        engine = engine_finder()
-        await engine.close_connnection_pool()
-
-.. hint:: Using a connection pool helps with performance, since connections
-    are reused instead of being created for each query.
-
-Once a connection pool has been started, the engine will use it for making
-queries.
-
-.. hint:: If you're running several instances of an app on the same server,
-    you may prefer an external connection pooler - like pgbouncer.
-
-Configuration
-~~~~~~~~~~~~~
-
-The connection pool uses the same configuration as your engine. You can also
-pass in additional parameters, which are passed to the underlying database
-adapter. Here's an example:
-
-.. code-block:: python
+.. toctree::
+    :maxdepth: 1
 
-    # To increase the number of connections available:
-    await engine.start_connnection_pool(max_size=20)
+    ./sqlite_engine
+    ./postgres_engine

docs/src/piccolo/engines/postgres_engine.rst

@@ -0,0 +1,86 @@
+PostgresEngine
+==============
+
+Configuration
+-------------
+
+.. code-block:: python
+
+    # piccolo_conf.py
+    from piccolo.engine.postgres import PostgresEngine
+
+
+    DB = PostgresEngine(config={
+        'host': 'localhost',
+        'database': 'my_app',
+        'user': 'postgres',
+        'password': ''
+    })
+
+config
+~~~~~~
+
+The config dictionary is passed directly to the underlying database adapter,
+asyncpg. See the `asyncpg docs <https://magicstack.github.io/asyncpg/current/api/index.html#connection>`_
+to learn more.
+
+-------------------------------------------------------------------------------
+
+Connection pool
+---------------
+
+To use a connection pool, you need to first initialise it. The best place to do
+this is in the startup event handler of whichever web framework you are using.
+
+Here's an example using Starlette. Notice that we also close the connection
+pool in the shutdown event handler.
+
+.. code-block:: python
+
+    from piccolo.engine import from starlette.applications import Starlette
+    from starlette.applications import Starlette
+
+
+    app = Starlette()
+
+
+    @app.on_event('startup')
+    async def open_database_connection_pool():
+        engine = engine_finder()
+        await engine.start_connnection_pool()
+
+
+    @app.on_event('shutdown')
+    async def close_database_connection_pool():
+        engine = engine_finder()
+        await engine.close_connnection_pool()
+
+.. hint:: Using a connection pool helps with performance, since connections
+    are reused instead of being created for each query.
+
+Once a connection pool has been started, the engine will use it for making
+queries.
+
+.. hint:: If you're running several instances of an app on the same server,
+    you may prefer an external connection pooler - like pgbouncer.
+
+Configuration
+~~~~~~~~~~~~~
+
+The connection pool uses the same configuration as your engine. You can also
+pass in additional parameters, which are passed to the underlying database
+adapter. Here's an example:
+
+.. code-block:: python
+
+    # To increase the number of connections available:
+    await engine.start_connnection_pool(max_size=20)
+
+-------------------------------------------------------------------------------
+
+Source
+------
+
+.. currentmodule:: piccolo.engine.postgres
+
+.. autoclass:: PostgresEngine

docs/src/piccolo/engines/sqlite_engine.rst

@@ -0,0 +1,25 @@
+SQLiteEngine
+============
+
+Configuration
+-------------
+
+The ``SQLiteEngine`` is very simple - just specify a file path. The database
+file will be created automatically if it doesn't exist.
+
+.. code-block:: python
+
+    # piccolo_conf.py
+    from piccolo.engine.sqlite import SQLiteEngine
+
+
+    DB = SQLiteEngine(path='my_app.sqlite')
+
+-------------------------------------------------------------------------------
+
+Source
+------
+
+.. currentmodule:: piccolo.engine.sqlite
+
+.. autoclass:: SQLiteEngine

piccolo/engine/postgres.py

@@ -193,8 +193,32 @@ async def __aexit__(self, exception_type, exception, traceback):
 
 
 class PostgresEngine(Engine):
+    """
+    Used to connect to Postgresql.
+
+    :param config:
+        The config dictionary is passed to the underlying database adapter,
+        asyncpg. Common arguments you're likely to need are:
+
+            * host
+            * port
+            * user
+            * password
+            * database
+
+        For example, ``{'host': 'localhost', 'port': 5432}``.
+
+        To see all available options:
+
+            * https://magicstack.github.io/asyncpg/current/api/index.html#connection
+
+    :param extensions:
+        When the engine starts, it will try and create these extensions
+        in Postgres.
+
+    """  # noqa: E501
 
-    __slots__ = ("config", "pool")
+    __slots__ = ("config", "extensions", "pool", "transaction_connection")
 
     engine_type = "postgres"
     min_version_number = 9.6
@@ -204,28 +228,6 @@ def __init__(
         config: t.Dict[str, t.Any],
         extensions: t.Sequence[str] = ["uuid-ossp"],
     ) -> None:
-        """
-        :param config:
-            The config dictionary is passed to the underlying database adapter,
-            asyncpg. Common arguments you're likely to need are:
-
-                * host
-                * port
-                * user
-                * password
-                * database
-
-            For example, ``{'host': 'localhost', 'port': 5432}``.
-
-            To see all available options:
-
-                * https://magicstack.github.io/asyncpg/current/api/index.html#connection
-
-        :param extensions:
-            When the engine starts, it will try and create these extensions
-            in Postgres.
-
-        """  # noqa: E501
         self.config = config
         self.extensions = extensions
         self.pool: t.Optional[Pool] = None

piccolo/engine/sqlite.py

@@ -294,6 +294,13 @@ def dict_factory(cursor, row) -> t.Dict:
 
 
 class SQLiteEngine(Engine):
+    """
+    Any connection kwargs are passed into the database adapter.
+
+    See here for more info:
+    https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
+
+    """
 
     __slots__ = ("connection_kwargs",)
 
@@ -307,13 +314,6 @@ def __init__(
         isolation_level=None,
         **connection_kwargs,
     ) -> None:
-        """
-        Any connection kwargs are passed into the database adapter.
-
-        See here for more info:
-        https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
-
-        """
         connection_kwargs.update(
             {
                 "database": path,