Add documentation

README.rst

@@ -1,6 +1,7 @@
 Sprockets Postgres
 ==================
-An asynchronous Postgres client mixin for Tornado applications
+An set of mixins and classes for interacting with PostgreSQL using asyncio in
+Tornado / sprockets.http applications using aiopg.
 
 |Version| |Status| |Coverage| |License|
 
@@ -20,28 +21,28 @@ Configuration
 -------------
 The following table details the environment variable configuration options:
 
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| Variable                        | Definition                                       | Default                         |
+| Variable                        | Definition                                       | Default           |
-+=================================+==================================================+=================================+
++=================================+==================================================+===================+
-| ``PGSQL_URL``                   | The PostgreSQL URL to connect to                 | ``postgresql://localhost:5432`` |
+| ``POSTGRES_URL``                | The PostgreSQL URL to connect to                 |                   |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_MAX_POOL_SIZE``      | Maximum connection count to Postgres per backend | ``0`` (Unlimited)               |
+| ``POSTGRES_MAX_POOL_SIZE``      | Maximum connection count to Postgres per backend | ``0`` (Unlimited) |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_MIN_POOL_SIZE``      | Minimum or starting pool size.                   | ``1``                           |
+| ``POSTGRES_MIN_POOL_SIZE``      | Minimum or starting pool size.                   | ``1``             |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_CONNECTION_TIMEOUT`` | The maximum time in seconds to spend attempting  | ``10``                          |
+| ``POSTGRES_CONNECTION_TIMEOUT`` | The maximum time in seconds to spend attempting  | ``10``            |
-|                                 | to create a new connection.                      |                                 |
+|                                 | to create a new connection.                      |                   |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_CONNECTION_TTL``     | Time-to-life in seconds for a pooled connection. | ``300``                         |
+| ``POSTGRES_CONNECTION_TTL``     | Time-to-life in seconds for a pooled connection. | ``300``           |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_QUERY_TIMEOUT``      | Maximum execution time for a query in seconds.   | ``60``                          |
+| ``POSTGRES_QUERY_TIMEOUT``      | Maximum execution time for a query in seconds.   | ``60``            |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_HSTORE``             | Enable HSTORE support in the client.             | ``FALSE``                       |
+| ``POSTGRES_HSTORE``             | Enable HSTORE support in the client.             | ``FALSE``         |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_JSON``               | Enable JSON support in the client.               | ``FALSE``                       |
+| ``POSTGRES_JSON``               | Enable JSON support in the client.               | ``FALSE``         |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
-| ``POSTGRES_UUID``               | Enable UUID support in the client.               | ``TRUE``                        |
+| ``POSTGRES_UUID``               | Enable UUID support in the client.               | ``TRUE``          |
-+---------------------------------+--------------------------------------------------+---------------------------------+
++---------------------------------+--------------------------------------------------+-------------------+
 
 Requirements
 ------------

docs/application.rst

@@ -0,0 +1,6 @@
+Application Mixin
+=================
+
+.. autoclass:: sprockets_postgres.ApplicationMixin
+    :members:
+    :member-order: bysource

docs/conf.py

@@ -0,0 +1,41 @@
+import datetime
+
+import pkg_resources
+
+master_doc = 'index'
+project = 'sprockets-postgres'
+release = version = pkg_resources.get_distribution(project).version
+copyright = '{}, AWeber Communications'.format(datetime.date.today().year)
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = ['_themes']
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx_autodoc_typehints',
+    'sphinx.ext.viewcode'
+]
+
+set_type_checking_flag = True
+typehints_fully_qualified = True
+always_document_param_types = True
+typehints_document_rtype = True
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+intersphinx_mapping = {
+    'aiopg': ('https://aiopg.readthedocs.io/en/stable/', None),
+    'psycopg2': ('http://initd.org/psycopg/docs/', None),
+    'python': ('https://docs.python.org/3', None),
+    'sprockets-http': (
+        'https://sprocketshttp.readthedocs.io/en/master/', None),
+    'sprockets-influxdb': (
+        'https://sprockets-influxdb.readthedocs.io/en/latest/', None),
+    'sprockets.mixins.metrics': (
+        'https://sprocketsmixinsmetrics.readthedocs.io/en/latest/', None),
+    'tornado': ('http://tornadoweb.org/en/latest/', None)
+}
+
+autodoc_default_options = {'autodoc_typehints': 'description'}
+

docs/configuration.rst

@@ -0,0 +1,27 @@
+Configuration
+=============
+:py:mod:`sprockets-postgres <sprockets_postgres>` is configured via environment variables. The following table
+details the configuration options and their defaults.
+
++---------------------------------+--------------------------------------------------+-------------------+
+| Variable                        | Definition                                       | Default           |
++=================================+==================================================+===================+
+| ``POSTGRES_URL``                | The PostgreSQL URL to connect to                 |                   |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_MAX_POOL_SIZE``      | Maximum connection count to Postgres per backend | ``0`` (Unlimited) |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_MIN_POOL_SIZE``      | Minimum or starting pool size.                   | ``1``             |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_CONNECTION_TIMEOUT`` | The maximum time in seconds to spend attempting  | ``10``            |
+|                                 | to create a new connection.                      |                   |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_CONNECTION_TTL``     | Time-to-life in seconds for a pooled connection. | ``300``           |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_QUERY_TIMEOUT``      | Maximum execution time for a query in seconds.   | ``60``            |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_HSTORE``             | Enable HSTORE support in the client.             | ``FALSE``         |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_JSON``               | Enable JSON support in the client.               | ``FALSE``         |
++---------------------------------+--------------------------------------------------+-------------------+
+| ``POSTGRES_UUID``               | Enable UUID support in the client.               | ``TRUE``          |
++---------------------------------+--------------------------------------------------+-------------------+

docs/connector.rst

@@ -0,0 +1,9 @@
+PostgresConnector
+=================
+A :class:`~sprockets_postgres.PostgresConnector` instance contains a cursor for
+a Postgres connection and methods to execute queries.
+
+.. autoclass:: sprockets_postgres.PostgresConnector
+    :members:
+    :undoc-members:
+    :member-order: bysource

docs/example.rst

@@ -0,0 +1,42 @@
+Example Web Application
+=======================
+The following code provides a simple example for using the
+
+.. code-block:: python
+    
+    import sprockets.http
+    import sprockets_postgres as postgres
+    from sprockets.http import app
+
+
+    class RequestHandler(postgres.RequestHandlerMixin,
+                         web.RequestHandler):
+
+        GET_SQL = """\
+        SELECT foo_id, bar, baz, qux
+          FROM public.foo
+         WHERE foo_id = %(foo_id)s;"""
+
+        async def get(self, foo_id: str) -> None:
+            result = await self.postgres_execute(self.GET_SQL, {'foo_id': foo_id})
+            await self.finish(result.row)
+
+
+    class Application(postgres.ApplicationMixin, app.Application):
+        """
+        The ``ApplicationMixin`` provides the foundation for the
+        ``RequestHandlerMixin`` to properly function and will automatically
+        setup the pool to connect to PostgreSQL and will shutdown the connections
+        cleanly when the application stops.
+
+        """
+
+
+    def make_app(**settings):
+        return Application([
+           web.url(r'/foo/(?P<foo_id>.*)', FooRequestHandler)
+        ], **settings)
+
+
+    if __name__ == '__main__':
+        sprockets.http.run(make_app)

docs/exceptions.rst

@@ -0,0 +1,4 @@
+Exceptions
+==========
+
+.. autoclass:: sprockets_postgres.ConnectionException

docs/genindex.rst

@@ -0,0 +1,2 @@
+Index
+=====

docs/index.rst

@@ -0,0 +1,31 @@
+Sprockets Postgres
+==================
+An set of mixins and classes for interacting with PostgreSQL using :mod:`asyncio`
+in :class:`Tornado <tornado.web.Application>` /
+:class:`sprockets.http <sprockets.http.app.Application>` applications using
+:py:mod:`aiopg`.
+
+Installation
+------------
+``sprockets-postgres`` is available on the Python package index and is installable via pip:
+
+.. code:: bash
+
+    pip install sprockets-postgres
+
+
+Documentation
+-------------
+
+.. toctree::
+   :maxdepth: 1
+
+   configuration
+   application
+   request_handler
+   query_result
+   connector
+   typing
+   exceptions
+   example
+   genindex

docs/query_result.rst

@@ -0,0 +1,9 @@
+QueryResult
+===========
+A :class:`~sprockets_postgres.QueryResult` instance is created for every query
+and contains the count of rows effected by the query and either the ``row`` as
+a :class:`dict` or ``rows`` as a list of :class:`dict`.  For queries that do
+not return any data, both ``row`` and ``rows`` will be :const:`None`.
+
+.. autoclass:: sprockets_postgres.QueryResult
+    :members:

docs/request_handler.rst

@@ -0,0 +1,11 @@
+RequestHandler Mixin
+====================
+The :class:`~sprockets_postgres.RequestHandlerMixin` is a Tornado
+:class:`tornado.web.RequestHandler` mixin that provides easy to use
+functionality for interacting with PostgreSQL.
+
+.. autoclass:: sprockets_postgres.RequestHandlerMixin
+    :members:
+    :undoc-members:
+    :private-members:
+    :member-order: bysource

docs/requirements.txt

@@ -0,0 +1,5 @@
+Sphinx==2.4.4
+sphinx-autodoc-typehints
+sphinx_rtd_theme
+typed_ast
+typing_extensions

docs/typing.rst

@@ -0,0 +1,6 @@
+Type Annotations
+================
+
+.. autodata:: sprockets_postgres.QueryParameters
+
+.. autodata:: sprockets_postgres.Timeout