mirror of
https://github.com/sprockets/sprockets-postgres.git
synced 2024-11-13 03:00:19 +00:00
Add documentation
This commit is contained in:
parent
603eb4d6dd
commit
58d349e790
13 changed files with 217 additions and 23 deletions
47
README.rst
47
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
|
||||
------------
|
||||
|
|
6
docs/application.rst
Normal file
6
docs/application.rst
Normal file
|
@ -0,0 +1,6 @@
|
|||
Application Mixin
|
||||
=================
|
||||
|
||||
.. autoclass:: sprockets_postgres.ApplicationMixin
|
||||
:members:
|
||||
:member-order: bysource
|
41
docs/conf.py
Normal file
41
docs/conf.py
Normal 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
27
docs/configuration.rst
Normal 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
9
docs/connector.rst
Normal 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
42
docs/example.rst
Normal 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
4
docs/exceptions.rst
Normal file
|
@ -0,0 +1,4 @@
|
|||
Exceptions
|
||||
==========
|
||||
|
||||
.. autoclass:: sprockets_postgres.ConnectionException
|
2
docs/genindex.rst
Normal file
2
docs/genindex.rst
Normal file
|
@ -0,0 +1,2 @@
|
|||
Index
|
||||
=====
|
31
docs/index.rst
Normal file
31
docs/index.rst
Normal 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
9
docs/query_result.rst
Normal 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
11
docs/request_handler.rst
Normal 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
5
docs/requirements.txt
Normal 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
6
docs/typing.rst
Normal file
|
@ -0,0 +1,6 @@
|
|||
Type Annotations
|
||||
================
|
||||
|
||||
.. autodata:: sprockets_postgres.QueryParameters
|
||||
|
||||
.. autodata:: sprockets_postgres.Timeout
|
Loading…
Reference in a new issue