Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Added API documentation.

  • Loading branch information...
commit d1a30b92ab18decffed194c97ef82582e94d143f 1 parent 4f1f404
Frank Smit authored
2  README.rst
View
@@ -1,7 +1,7 @@
Momoko
======
-A Tornado_ wrapper for Psycopg2_.
+Wraps (asynchronous) Psycopg2_ for Tornado_
.. _Psycopg2: http://www.initd.org/psycopg/
.. _Tornado: http://www.tornadoweb.org/
4 changelog.rst
View
@@ -1,5 +1,5 @@
-News/Changelog
-==============
+Changelog
+=========
1.0.0b1 (2012-12-16)
------------------
2  momoko/__init__.py
View
@@ -3,7 +3,7 @@
momoko
======
-Asynchronous Psycopg wrapper for Tornado.
+Wraps (asynchronous) Psycopg2 for Tornado.
Copyright 2011-2012 by Frank Smit.
MIT, see LICENSE for more details.
222 momoko/connection.py
View
@@ -26,12 +26,32 @@
# The dummy callback is used to keep the asynchronous cursor alive in case no
# callback has been specified. This will prevent the cursor from being garbage
-# collected once, for example, ``ConnectionPool.execute`` has finished.
+# collected once, for example, ``Pool.execute`` has finished.
def _dummy_callback(cursor, error):
pass
class Pool:
+ """
+ Asynchronous connection pool.
+
+ The pool manages database connections and passes operations to connections.
+
+ See :py:class:`momoko.Connection` for documentation about the ``dsn`` and
+ ``connection_factory`` parameters. These are used by the connection pool when
+ a new connection is created.
+
+ :param integer minconn: Amount of connections created upon initialization. Defaults to ``1``.
+ :param integer maxconn: Maximum amount of connections allowed by the pool. Defaults to ``5``.
+ :param integer cleanup_timeout:
+ Time in seconds between pool cleanups. Unused connections are closed and
+ removed from the pool until only ``minconn`` are left. When an integer
+ below ``1``, like ``-1`` is used the pool cleaner will be disabled.
+ Defaults to ``10``.
+ :param callable callback:
+ A callable that's called after all the connections are created. Defaults to ``None``.
+ :param ioloop: An instance of Tornado's IOLoop. Defaults to ``None``.
+ """
def __init__(self,
dsn,
connection_factory=None,
@@ -73,6 +93,13 @@ def after_connect(_):
self._cleaner.start()
def new(self, callback=None):
+ """
+ Create a new connection and add it to the pool.
+
+ :param callable callback:
+ A callable that's called after the connection is created. It accepts
+ one paramater: an instance of :py:class:`momoko.Connection`. Defaults to ``None``.
+ """
if len(self._pool) > self.maxconn:
raise PoolError('connection pool exausted')
@@ -107,9 +134,15 @@ def _clean_pool(self):
def transaction(self,
statements,
cursor_factory=None,
- callback=_dummy_callback,
+ callback=None,
connection=None
):
+ """
+ Run a sequence of SQL queries in a database transaction.
+
+ See :py:meth:`momoko.Connection.transaction` for documentation about the
+ parameters. The ``connection`` parameter is for internal use.
+ """
connection = connection or self._get_connection()
if not connection:
return self.new(lambda connection: self.transaction(
@@ -121,9 +154,15 @@ def execute(self,
operation,
parameters=(),
cursor_factory=None,
- callback=_dummy_callback,
+ callback=None,
connection=None
):
+ """
+ Prepare and execute a database operation (query or command).
+
+ See :py:meth:`momoko.Connection.execute` for documentation about the
+ parameters. The ``connection`` parameter is for internal use.
+ """
connection = connection or self._get_connection()
if not connection:
return self.new(lambda connection: self.execute(operation,
@@ -135,9 +174,15 @@ def callproc(self,
procname,
parameters=(),
cursor_factory=None,
- callback=_dummy_callback,
+ callback=None,
connection=None
):
+ """
+ Call a stored database procedure with the given name.
+
+ See :py:meth:`momoko.Connection.callproc` for documentation about the
+ parameters. The ``connection`` parameter is for internal use.
+ """
connection = connection or self._get_connection()
if not connection:
return self.new(lambda connection: self.callproc(procname,
@@ -148,9 +193,15 @@ def callproc(self,
def mogrify(self,
operation,
parameters=(),
- callback=_dummy_callback,
+ callback=None,
connection=None
):
+ """
+ Return a query string after arguments binding.
+
+ See :py:meth:`momoko.Connection.mogrify` for documentation about the
+ parameters. The ``connection`` parameter is for internal use.
+ """
connection = connection or self._get_connection()
if not connection:
return self.new(lambda connection: self.mogrify(operation,
@@ -159,6 +210,9 @@ def mogrify(self,
connection.mogrify(operation, parameters, callback)
def close(self):
+ """
+ Close the connection pool.
+ """
if self.closed:
raise PoolError('connection pool is already closed')
@@ -173,6 +227,36 @@ def close(self):
class Connection:
+ """
+ Create an asynchronous connection.
+
+ :param string dsn:
+ A `Data Source Name`_ string containing one of the following values:
+
+ * **dbname** - the database name
+ * **user** - user name used to authenticate
+ * **password** - password used to authenticate
+ * **host** - database host address (defaults to UNIX socket if not provided)
+ * **port** - connection port number (defaults to 5432 if not provided)
+
+ Or any other parameter supported by PostgreSQL. See the PostgreSQL
+ documentation for a complete list of supported parameters_.
+
+ :param connection_factory:
+ The ``connection_factory`` argument can be used to create non-standard
+ connections. The class returned should be a subclass of `psycopg2.extensions.connection`_.
+ See `Connection and cursor factories`_ for details. Defaults to ``None``.
+
+ :param callable callback:
+ A callable that's called after the connection is created. It accepts one
+ paramater: an instance of :py:class:`momoko.Connection`. Defaults to ``None``.
+ :param ioloop: An instance of Tornado's IOLoop. Defaults to ``None``.
+
+ .. _Data Source Name: http://en.wikipedia.org/wiki/Data_Source_Name
+ .. _parameters: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNECTDBPARAMS
+ .. _psycopg2.extensions.connection: http://initd.org/psycopg/docs/connection.html#connection
+ .. _Connection and cursor factories: http://initd.org/psycopg/docs/advanced.html#subclassing-cursor
+ """
def __init__(self,
dsn,
connection_factory=None,
@@ -218,39 +302,139 @@ def execute(self,
operation,
parameters=(),
cursor_factory=None,
- callback=_dummy_callback
+ callback=None
):
+ """
+ Prepare and execute a database operation (query or command).
+
+ :param string operation: An SQL query.
+ :param tuple/list parameters:
+ A list or tuple with query parameters. See `Passing parameters to SQL queries`_
+ for more information. Defaults to an empty tuple.
+ :param cursor_factory:
+ The ``cursor_factory`` argument can be used to create non-standard cursors.
+ The class returned must be a subclass of `psycopg2.extensions.cursor`_.
+ See `Connection and cursor factories`_ for details. Defaults to ``None``.
+ :param callable callback:
+ A callable that is executed when the query has finished. It must accept
+ two positional parameters. The first one being the cursor and the second
+ one ``None`` or an instance of an exception if an error has occurred,
+ in that case the first parameter will be ``None``. Defaults to ``None``.
+
+ .. _Passing parameters to SQL queries: http://initd.org/psycopg/docs/usage.html#query-parameters
+ .. _psycopg2.extensions.cursor: http://initd.org/psycopg/docs/extensions.html#psycopg2.extensions.cursor
+ .. _Connection and cursor factories: http://initd.org/psycopg/docs/advanced.html#subclassing-cursor
+ """
cursor = self.connection.cursor(cursor_factory=cursor_factory or base_cursor)
cursor.execute(operation, parameters)
- self.callback = partial(callback, cursor)
+ self.callback = partial(callback or _dummy_callback, cursor)
self.ioloop.update_handler(self.fileno, IOLoop.WRITE)
def callproc(self,
procname,
parameters=(),
cursor_factory=None,
- callback=_dummy_callback
+ callback=None
):
+ """
+ Call a stored database procedure with the given name.
+
+ The sequence of parameters must contain one entry for each argument that
+ the procedure expects. The result of the call is returned as modified copy
+ of the input sequence. Input parameters are left untouched, output and
+ input/output parameters replaced with possibly new values.
+
+ The procedure may also provide a result set as output. This must then be
+ made available through the standard `fetch*()`_ methods.
+
+ :param string operation: The name of the database procedure.
+ :param tuple/list parameters:
+ A list or tuple with query parameters. See `Passing parameters to SQL queries`_
+ for more information. Defaults to an empty tuple.
+ :param cursor_factory:
+ The ``cursor_factory`` argument can be used to create non-standard cursors.
+ The class returned must be a subclass of `psycopg2.extensions.cursor`_.
+ See `Connection and cursor factories`_ for details. Defaults to ``None``.
+ :param callable callback:
+ A callable that is executed when the query has finished. It must accept
+ two positional parameters. The first one being the cursor and the second
+ one ``None`` or an instance of an exception if an error has occurred,
+ in that case the first parameter will be ``None``. Defaults to ``None``.
+
+ .. _fetch*(): http://initd.org/psycopg/docs/cursor.html#fetch
+ .. _Passing parameters to SQL queries: http://initd.org/psycopg/docs/usage.html#query-parameters
+ .. _psycopg2.extensions.cursor: http://initd.org/psycopg/docs/extensions.html#psycopg2.extensions.cursor
+ .. _Connection and cursor factories: http://initd.org/psycopg/docs/advanced.html#subclassing-cursor
+ """
cursor = self.connection.cursor(cursor_factory=cursor_factory or base_cursor)
cursor.callproc(procname, parameters)
- self.callback = partial(callback, cursor)
+ self.callback = partial(callback or _dummy_callback, cursor)
self.ioloop.update_handler(self.fileno, IOLoop.WRITE)
- def mogrify(self, operation, parameters=(), callback=_dummy_callback):
+ def mogrify(self, operation, parameters=(), callback=None):
+ """
+ Return a query string after arguments binding.
+
+ The string returned is exactly the one that would be sent to the database
+ running the execute() method or similar.
+
+ :param string operation: An SQL query.
+ :param tuple/list parameters:
+ A list or tuple with query parameters. See `Passing parameters to SQL queries`_
+ for more information. Defaults to an empty tuple.
+ :param callable callback:
+ A callable that is executed when the query has finished. It must accept
+ two positional parameters. The first one being the resulting query as
+ a byte string and the second one ``None`` or an instance of an exception
+ if an error has occurred. Defaults to ``None``.
+
+ .. _Passing parameters to SQL queries: http://initd.org/psycopg/docs/usage.html#query-parameters
+ .. _Connection and cursor factories: http://initd.org/psycopg/docs/advanced.html#subclassing-cursor
+ """
cursor = self.connection.cursor()
try:
result = cursor.mogrify(operation, parameters)
- self.ioloop.add_callback(partial(callback, result, None))
+ self.ioloop.add_callback(partial(callback or _dummy_callback, result, None))
except (psycopg2.Warning, psycopg2.Error) as error:
- self.ioloop.add_callback(partial(callback, b'', error))
+ self.ioloop.add_callback(partial(callback or _dummy_callback, b'', error))
def transaction(self,
statements,
cursor_factory=None,
- callback=_dummy_callback
+ callback=None
):
+ """
+ Run a sequence of SQL queries in a database transaction.
+
+ :param tuple/list statements:
+ List or tuple containing SQL queries with or without parameters. An item
+ can be a string (SQL query without parameters) or a tuple/list with two items,
+ an SQL query and a tuple/list wuth parameters. An example::
+
+ (
+ 'SELECT 1, 2, 3;', # Without parameters
+ ('SELECT 4, %s, 6, %s;', (5, 7)), # With parameters
+ )
+
+ See `Passing parameters to SQL queries`_ for more information.
+ :param cursor_factory:
+ The ``cursor_factory`` argument can be used to create non-standard cursors.
+ The class returned must be a subclass of `psycopg2.extensions.cursor`_.
+ See `Connection and cursor factories`_ for details. Defaults to ``None``.
+ :param callable callback:
+ A callable that is executed when the transaction has finished. It must accept
+ two positional parameters. The first one being a list of cursors in the same
+ order as the given statements and the second one ``None`` or an instance of
+ an exception if an error has occurred, in that case the first parameter is
+ an empty list. Defaults to ``None``.
+
+ .. _Passing parameters to SQL queries: http://initd.org/psycopg/docs/usage.html#query-parameters
+ .. _psycopg2.extensions.cursor: http://initd.org/psycopg/docs/extensions.html#psycopg2.extensions.cursor
+ .. _Connection and cursor factories: http://initd.org/psycopg/docs/advanced.html#subclassing-cursor
+ """
cursors = []
queue = deque()
+ callback = callback or _dummy_callback
for statement in statements:
if isinstance(statement, str):
@@ -263,8 +447,7 @@ def transaction(self,
def exec_statement(cursor=None, error=None):
if error:
- self.execute('ROLLBACK;',
- callback=partial(error_callback, error))
+ self.execute('ROLLBACK;', callback=partial(error_callback, error))
return
if cursor:
cursors.append(cursor)
@@ -281,14 +464,23 @@ def error_callback(statement_error, cursor, rollback_error):
self.ioloop.add_callback(exec_statement)
def busy(self):
+ """
+ Check if the connection is busy or not.
+ """
return self.connection.isexecuting() or (self.connection.closed == 0 and
self._transaction_status() != TRANSACTION_STATUS_IDLE)
@property
def closed(self):
+ """
+ Indicates whether the connection is closed or not.
+ """
# 0 = open, 1 = closed, 2 = 'something horrible happened'
return self.connection.closed > 0
def close(self):
+ """
+ Remove the connection from the IO loop and close it.
+ """
self.ioloop.remove_handler(self.fileno)
self.connection.close()
4 momoko/exceptions.py
View
@@ -11,4 +11,8 @@
class PoolError(Exception):
+ """
+ The ``PoolError`` exception is raised when something goes wrong in the connection
+ pool. When the maximum amount is exceeded for example.
+ """
pass
4 momoko/tests.py
View
@@ -44,8 +44,6 @@ def set_up(self):
def tear_down(self):
pass
-
-class MomokoTest(BaseTest):
def stop_callback(self, result, error):
self.stop((result, error))
@@ -59,6 +57,8 @@ def wait_for_result(self):
raise error
return cursor
+
+class MomokoTest(BaseTest):
def clean_db(self):
self.db.execute('DROP TABLE IF EXISTS unit_test_large_query;',
callback=self.stop_callback)
29 momoko/utils.py
View
@@ -22,6 +22,15 @@
class Op(gen.Task):
+ """
+ Run a single asynchronous operation.
+
+ Behaves like `tornado.gen.Task`_, but raises an exception (one of Psycop2's
+ exceptions_) when an error occurs related to Psycopg2 or PostgreSQL.
+
+ .. _exceptions: http://initd.org/psycopg/docs/module.html#exceptions
+ .. _tornado.gen.Task: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Task
+ """
def get_result(self):
(result, error), _ = super(Op, self).get_result()
if error:
@@ -30,6 +39,16 @@ def get_result(self):
class WaitOp(gen.Wait):
+ """
+ Return the argument passed to the result of a previous `tornado.gen.Callback`_.
+
+ Behaves like `tornado.gen.Wait`_, but raises an exception (one of Psycop2's
+ exceptions_) when an error occurs related to Psycopg2 or PostgreSQL.
+
+ .. _exceptions: http://initd.org/psycopg/docs/module.html#exceptions
+ .. _tornado.gen.Callback: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Callback
+ .. _tornado.gen.Wait: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Wait
+ """
def get_result(self):
(result, error), _ = super(WaitOp, self).get_result()
if error:
@@ -38,6 +57,16 @@ def get_result(self):
class WaitAllOps(gen.WaitAll):
+ """
+ Return the results of multiple previous `tornado.gen.Callback`_.
+
+ Behaves like `tornado.gen.WaitAll`_, but raises an exception (one of Psycop2's
+ exceptions_) when an error occurs related to Psycopg2 or PostgreSQL.
+
+ .. _exceptions: http://initd.org/psycopg/docs/module.html#exceptions
+ .. _tornado.gen.Callback: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.Callback
+ .. _tornado.gen.WaitAll: http://www.tornadoweb.org/documentation/gen.html#tornado.gen.WaitAll
+ """
def get_result(self):
super_results = super(WaitAllOps, self).get_result()
4 setup.py
View
@@ -18,8 +18,8 @@
setup(
name='Momoko',
- version='1.0.0b1',
- description='An asynchronous Psycopg2 wrapper for Tornado.',
+ version='1.0.0b2',
+ description='Wraps (asynchronous) Psycopg2 for Tornado.',
long_description=open('README.rst').read(),
author='Frank Smit',
author_email='frank@61924.nl',
Please sign in to comment.
Something went wrong with that request. Please try again.