API — Momoko 0.5.0 documentation

### Navigation

- Momoko 0.5.0 documentation »
- index
- / modules
- / previous

# API

All public methods included in the module. See the Examples pages for some usage examples.

## BlockingClient Object

class `momoko.` `BlockingClient`(settings)

  The `BlockingClient` class is a wrapper around the `psycopg2` module and provides some extra functionality.

  Parameters: | settings – A dictionary that is passed to the `BlockingPool` object.

  `connection`

    Create a context for a connection and commit changes on exit.

    For example:

        with self.db.connection() as conn:
            cursor = conn.cursor()
            cursor.execute('SELECT 42, 12, 40, 11;')

## AsyncClient Object

class `momoko.` `AsyncClient`(settings)
  The `AsyncClient` class is a wrapper for `AsyncPool`, `BatchQuery`
    and `QueryChain`. It also provides the `execute` and `callproc` functions.

  Parameters: | settings – A dictionary that is passed to the `AsyncPool` object.

  `batch`(queries, callback=None, cursor_kwargs={})

    Run a batch of queries all at once.

    Note: Every query needs a free connection. So if three queries are are executed, three free connections are used.

    A dictionary with queries looks like this:

        {
            'query1': ['SELECT 42, 12, %s, %s;', (23, 56)],
            'query2': 'SELECT 1, 2, 3, 4, 5;',
            'query3': 'SELECT 465767, 4567, 3454;'
        }

    A query with paramaters is contained in a list: `['some sql here %s, %s', ('and some', 'paramaters here')]`. A query without paramaters doesn’t need to be in a list.

    Parameters: | queries – A dictionary with all the queries. callback – The function that needs to be executed once all the queries are finished. Optional. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.
    Returns: | A dictionary with the same keys as the given queries with the resulting cursors as values.

  `callproc`(procname, parameters=None, callback=None, cursor_kwargs={})

    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.

    Parameters: | procname – The name of the procedure. parameters – A sequence with parameters. This is `None` by default. callback – A callable that is executed once the procedure is finished. Optional. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.

  `chain`(queries, callback=None, cursor_kwargs={})

    Run a chain of queries in the given order.

    A list/tuple with queries looks like this:

        (
            ['SELECT 42, 12, %s, 11;', (23,)],
            'SELECT 1, 2, 3, 4, 5;'
        )

    A query with paramaters is contained in a list: `['some sql here %s, %s', ('and some', 'paramaters here')]`. A query without paramaters doesn’t need to be in a list.

    Parameters: | queries – A tuple or list with all the queries. callback – The function that needs to be executed once all the queries are finished. Optional. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.
    Returns: | A list with the resulting cursors.

  `close`()

    Close all connections in the connection pool.

  `execute`(operation, parameters=(), callback=None, cursor_kwargs={})

    Prepare and execute a database operation (query or command).

    Parameters may be provided as sequence or mapping and will be bound to variables in the operation. Variables are specified either with positional (`%s`) or named (`%(name)s`) placeholders. See Passing parameters to SQL queries [1] in the Psycopg2 documentation.

    Parameters: | operation – The database operation (an SQL query or command). parameters – A tuple, list or dictionary with parameters. This is an empty tuple by default. callback – A callable that is executed once the operation is finished. Optional. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.

## BlockingPool Object

class `momoko.` `BlockingPool`(min_conn=1, max_conn=20, cleanup_timeout=10, *args, **kwargs)

  A connection pool that manages blocking PostgreSQL connections and cursors.

  Parameters: | min_conn – The minimum amount of connections that is created when a connection pool is created. max_conn – The maximum amount of connections the connection pool can have. If the amount of connections exceeds the limit a `PoolError` exception is raised. cleanup_timeout – Time in seconds between pool cleanups. Connections will be closed until there are `min_conn` left. host – The database host address (defaults to UNIX socket if not provided) port – The database host port (defaults to 5432 if not provided) database – The database name user – User name used to authenticate password – Password used to authenticate connection_factory – Using the connection_factory parameter a different class or connections factory can be specified. It should be a callable object taking a dsn argument.

  `close`()

    Close all open connections in the pool.

  `get_connection`()

    Get a connection from the pool.

    If there’s no free connection available, a new connection will be created.

## AsyncPool Object

class `momoko.` `AsyncPool`(min_conn=1, max_conn=20, cleanup_timeout=10, ioloop=None, *args, **kwargs)

  A connection pool that manages asynchronous PostgreSQL connections and cursors.

  Parameters: | min_conn – The minimum amount of connections that is created when a connection pool is created. max_conn – The maximum amount of connections the connection pool can have. If the amount of connections exceeds the limit a `PoolError` exception is raised. cleanup_timeout – Time in seconds between pool cleanups. Connections will be closed until there are `min_conn` left. ioloop – An instance of Tornado’s IOLoop. host – The database host address (defaults to UNIX socket if not provided) port – The database host port (defaults to 5432 if not provided) database – The database name user – User name used to authenticate password – Password used to authenticate connection_factory – Using the connection_factory parameter a different class or connections factory can be specified. It should be a callable object taking a dsn argument.

  `close`()

    Close all open connections in the pool.

  `new_cursor`(function, function_args=(), callback=None, cursor_kwargs={}, connection=None)

    Create a new cursor.

    If there’s no connection available, a new connection will be created and new_cursor will be called again after the connection has been made.

    Parameters: | function – `execute`, `executemany` or `callproc`. function_args – A tuple with the arguments for the specified function. callback – A callable that is executed once the operation is done. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments. connection – An `AsyncConnection` connection. Optional.

## AsyncConnection Object

class `momoko.pools.` `AsyncConnection`(ioloop)

  An asynchronous connection object.

  Parameters: | ioloop – An instance of Tornado’s IOLoop.

  `close`()

    Close connection.

  `closed`

    Read-only attribute reporting whether the database connection is open (0) or closed (1).

  `cursor`(function, function_args, callback, cursor_kwargs={})

    Get a cursor and execute the requested function

    Parameters: | function – `execute`, `executemany` or `callproc`. function_args – A tuple with the arguments for the specified function. callback – A callable that is executed once the operation is done. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.

  `isexecuting`()

    Return True if the connection is executing an asynchronous operation.

  `open`(callbacks, *args, **kwargs)

    Open the connection to the database,

    Parameters: | host – The database host address (defaults to UNIX socket if not provided) port – The database host port (defaults to 5432 if not provided) database – The database name user – User name used to authenticate password – Password used to authenticate connection_factory – Using the connection_factory parameter a different class or connections factory can be specified. It should be a callable object taking a dsn argument.

## QueryChain Object

class `momoko.utils.` `QueryChain`(db, queries, callback, cursor_kwargs={})

  Run a chain of queries in the given order.

  A list/tuple with queries looks like this:

      (
          ['SELECT 42, 12, %s, 11;', (23,)],
          'SELECT 1, 2, 3, 4, 5;'
      )

  A query with paramaters is contained in a list: `['some sql here %s, %s', ('and some', 'paramaters here')]`. A query without paramaters doesn’t need to be in a list.

  Parameters: | db – A `momoko.Client` or `momoko.AdispClient` instance. queries – A tuple or with all the queries. callback – The function that needs to be executed once all the queries are finished. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.
  Returns: | A list with the resulting cursors is passed on to the callback.

## BatchQuery Object

class `momoko.utils.` `BatchQuery`(db, queries, callback, cursor_kwargs={})

  Run a batch of queries all at once.

  Note: Every query needs a free connection. So if three queries are are executed, three free connections are used.

  A dictionary with queries looks like this:

      {
          'query1': ['SELECT 42, 12, %s, %s;', (23, 56)],
          'query2': 'SELECT 1, 2, 3, 4, 5;',
          'query3': 'SELECT 465767, 4567, 3454;'
      }

  A query with paramaters is contained in a list: `['some sql here %s, %s', ('and some', 'paramaters here')]`. A query without paramaters doesn’t need to be in a list.

  Parameters: | db – A `momoko.Client` or `momoko.AdispClient` instance. queries – A dictionary with all the queries. callback – The function that needs to be executed once all the queries are finished. cursor_kwargs – A dictionary with Psycopg’s connection.cursor arguments.
  Returns: | A dictionary with the same keys as the given queries with the resulting cursors as values is passed on to the callback.

}