Psycaio Module¶

async psycaio.connect(dsn=None, connection_factory=None, cursor_factory=None, **kwargs)¶

Open a connection to the database server and return a connection object.

The parameters are the same as for the psycopg2.connect() function with a few exceptions:

The async or async_ argument will have no effect. A connection will always be in asynchronous mode.
If set, the connection_factory must return an instance of both an AioConnMixin and a psycopg2 connection. The default is the AioConnection class which just inherits from both. The AioConnMixin type must be located before the psycopg2 connection type in the class hierarchy when performing a method lookup.
If set, the cursor_factory must return an instance of both an AioCursorMixin and a psycopg2 cursor. The default is the AioCursor class which just inherits from both. The AioConnMixin type must be located before the psycopg2 cursor type in the class hierarchy when performing a method lookup.

For example, to create an asynchronous version of the psycopg2 DictCursor type, the following code can be used:
```
from psycopg2.extras import DictCursor
from psycaio import AioCursorMixin

class AioDictCursor(AioCursorMixin, DictCursor):
   pass
```
The AioDictCursor can then be used as the cursor_factory argument for the connect function or the AioConnMixin.cursor method.
The connect_timeout is ignored in asynchronous mode by psycopg2 (or actually libpq). Therefore timeout functionality is implemented in this function. When multiple hosts are provided, or a host resolves to multiple IP addresses, it will apply the timeout per single host, just like libpq in synchronous/blocking mode.

Asynchronous DNS lookups are performed by this function as well, if necessary, because that part of the functionality is always blocking in libpq.

class psycaio.AioConnMixin(*args, **kwargs)¶

Mixin class to add asyncio behavior to the psycopg2 connection class.

This class should be not be instantiated directly. It should be used as a base class when implementing a custom connection.

async cancel()¶

Cancel the current database operation.

This is the coroutine version of the psycopg2 connection.cancel() method.

close()¶

Close the connection.

Coroutines that are still waiting for a Notify message with get_notify will be interrupted by a psycopg2 InterfaceError.

cursor(name=None, cursor_factory=None, scrollable=None, withhold=False)¶

Create and return a new cursor to perform database operations.

The only supported argument is cursor_factory, because named cursors are not available in asynchronous mode.

If set, the cursor_factory is used to instantiate the cursor. It must return an instance of both an AioCursorMixin and a psycopg2 cursor. The default is the AioCursor class which just inherits from both. The AioCursorMixin type must be located before the psycopg2 cursor type in the class hierarchy when performing a method lookup.

async get_notify()¶

Remove and return a psycopg2 Notify object from the Notify queue. If the queue is empty, wait until an item is available.

The connection.notifies attribute is replaced by the psycaio.AioConnMixin with a custom version that plays nicely with asyncio. Do not set it to anything else or this method will probably break.

Example:

async def test_notify(cn1, cn2):
    cr1 = cn1.cursor()
    await cr1.execute("LISTEN queue")

    cr2 = cn2.cursor()
    await cr2.execute("NOTIFY queue, 'hi'")

    notify = await cn1.get_notify()
    print(notify.payload)

For more information see the PostgreSQL docs on LISTEN.

get_notify_nowait()¶: Remove and return a psycopg2 Notify object from the Notify queue if one is immediately available, else raise asyncio.QueueEmpty.

class psycaio.AioConnection(*args, **kwargs)¶

Bases: psycaio.AioConnMixin, psycopg2.extensions.connection

The default connection class used by psycaio.

It just inherits from both AioConnMixin for the asyncio behavior and the standard psycopg2 connection, and contains no additional implementation.

This class should not be instantiated directly. Use the connect function instead.

class psycaio.AioCursorMixin¶

Mixin class to add asyncio behavior to the psycopg2 cursor class.

This class should be not be instantiated directly. It should be used as a base class when implementing a custom cursor.

When an operation is cancelled by asyncio (asyncio.Task.cancel(), asyncio.wait_for(), …), i.e. when a asyncio.CancelledError is raised during the operation, then psycaio will try to cancel the operation server side as well.

The execute and callproc methods can be called concurrently, but psycaio will make sure that all operations for one database connection are actually executed serially, because the underlying libraries can not handle multiple operations concurrently. If you want more concurrency make sure to use multiple database connections.

async callproc(procname, parameters=None)¶

Calls a PostgreSQL function using SELECT.

This is the coroutine version of the psycopg2 cursor.callproc() method.

async execute(query, vars=None)¶

Execute a database query.

This is the coroutine version of the psycopg2 cursor.execute() method.

async executemany(query, vars_list)¶

Execute a database query against multiple sequences or mappings of parameters.

This is the coroutine version of the psycopg2 cursor.executemany() method.

class psycaio.AioCursor¶

Bases: psycaio.AioCursorMixin, psycopg2.extensions.cursor

The default cursor class used by psycaio.

It just inherits from both AioCursorMixin for the asyncio behavior and the standard psycopg2 cursor, and contains no additional implementation.

This class should not be instantiated directly. Use the AioConnMixin.cursor method instead.