Add documentation

This commit is contained in:
Gavin M. Roy 2020-04-08 18:15:50 -04:00
parent 603eb4d6dd
commit 58d349e790
13 changed files with 217 additions and 23 deletions

View file

@ -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 |
+=================================+==================================================+=================================+
| ``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_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`` |
+---------------------------------+--------------------------------------------------+---------------------------------+
+---------------------------------+--------------------------------------------------+-------------------+
Requirements
------------

6
docs/application.rst Normal file
View file

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

41
docs/conf.py Normal file
View file

@ -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'}

27
docs/configuration.rst Normal file
View file

@ -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`` |
+---------------------------------+--------------------------------------------------+-------------------+

9
docs/connector.rst Normal file
View file

@ -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

42
docs/example.rst Normal file
View file

@ -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)

4
docs/exceptions.rst Normal file
View file

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

2
docs/genindex.rst Normal file
View file

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

31
docs/index.rst Normal file
View file

@ -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

9
docs/query_result.rst Normal file
View file

@ -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:

11
docs/request_handler.rst Normal file
View file

@ -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

5
docs/requirements.txt Normal file
View file

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

6
docs/typing.rst Normal file
View file

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