From 58d349e7900ecbe71f0b872bc5b8c9edb7463482 Mon Sep 17 00:00:00 2001 From: "Gavin M. Roy" Date: Wed, 8 Apr 2020 18:15:50 -0400 Subject: [PATCH] Add documentation --- README.rst | 47 ++++++++++++++++++++-------------------- docs/application.rst | 6 +++++ docs/conf.py | 41 +++++++++++++++++++++++++++++++++++ docs/configuration.rst | 27 +++++++++++++++++++++++ docs/connector.rst | 9 ++++++++ docs/example.rst | 42 +++++++++++++++++++++++++++++++++++ docs/exceptions.rst | 4 ++++ docs/genindex.rst | 2 ++ docs/index.rst | 31 ++++++++++++++++++++++++++ docs/query_result.rst | 9 ++++++++ docs/request_handler.rst | 11 ++++++++++ docs/requirements.txt | 5 +++++ docs/typing.rst | 6 +++++ 13 files changed, 217 insertions(+), 23 deletions(-) create mode 100644 docs/application.rst create mode 100644 docs/conf.py create mode 100644 docs/configuration.rst create mode 100644 docs/connector.rst create mode 100644 docs/example.rst create mode 100644 docs/exceptions.rst create mode 100644 docs/genindex.rst create mode 100644 docs/index.rst create mode 100644 docs/query_result.rst create mode 100644 docs/request_handler.rst create mode 100644 docs/requirements.txt create mode 100644 docs/typing.rst diff --git a/README.rst b/README.rst index db62a24..8d92f5a 100644 --- a/README.rst +++ b/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 | -+=================================+==================================================+=================================+ -| ``PGSQL_URL`` | The PostgreSQL URL to connect to | ``postgresql://localhost:5432`` | -+---------------------------------+--------------------------------------------------+---------------------------------+ -| ``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`` | -+---------------------------------+--------------------------------------------------+---------------------------------+ ++---------------------------------+--------------------------------------------------+-------------------+ +| 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`` | ++---------------------------------+--------------------------------------------------+-------------------+ Requirements ------------ diff --git a/docs/application.rst b/docs/application.rst new file mode 100644 index 0000000..2f71fdc --- /dev/null +++ b/docs/application.rst @@ -0,0 +1,6 @@ +Application Mixin +================= + +.. autoclass:: sprockets_postgres.ApplicationMixin + :members: + :member-order: bysource diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a2f4e60 --- /dev/null +++ b/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'} + diff --git a/docs/configuration.rst b/docs/configuration.rst new file mode 100644 index 0000000..15a47ac --- /dev/null +++ b/docs/configuration.rst @@ -0,0 +1,27 @@ +Configuration +============= +:py:mod:`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`` | ++---------------------------------+--------------------------------------------------+-------------------+ diff --git a/docs/connector.rst b/docs/connector.rst new file mode 100644 index 0000000..40d4811 --- /dev/null +++ b/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 diff --git a/docs/example.rst b/docs/example.rst new file mode 100644 index 0000000..c6bbfe1 --- /dev/null +++ b/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.*)', FooRequestHandler) + ], **settings) + + + if __name__ == '__main__': + sprockets.http.run(make_app) diff --git a/docs/exceptions.rst b/docs/exceptions.rst new file mode 100644 index 0000000..e3d9324 --- /dev/null +++ b/docs/exceptions.rst @@ -0,0 +1,4 @@ +Exceptions +========== + +.. autoclass:: sprockets_postgres.ConnectionException diff --git a/docs/genindex.rst b/docs/genindex.rst new file mode 100644 index 0000000..9e530fa --- /dev/null +++ b/docs/genindex.rst @@ -0,0 +1,2 @@ +Index +===== diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..9a503c3 --- /dev/null +++ b/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 ` / +:class:`sprockets.http ` 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 diff --git a/docs/query_result.rst b/docs/query_result.rst new file mode 100644 index 0000000..623dcc2 --- /dev/null +++ b/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: diff --git a/docs/request_handler.rst b/docs/request_handler.rst new file mode 100644 index 0000000..4d9f19c --- /dev/null +++ b/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 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..7a7ed02 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +Sphinx==2.4.4 +sphinx-autodoc-typehints +sphinx_rtd_theme +typed_ast +typing_extensions diff --git a/docs/typing.rst b/docs/typing.rst new file mode 100644 index 0000000..0765676 --- /dev/null +++ b/docs/typing.rst @@ -0,0 +1,6 @@ +Type Annotations +================ + +.. autodata:: sprockets_postgres.QueryParameters + +.. autodata:: sprockets_postgres.Timeout