Adapters API

Adapters are wrappers around SQL Providers, which translate internal module syntax into the proper Provider syntax

pgmob.adapters.ADAPTERS = [('.psycopg2', 'Psycopg2Adapter')]

Use the following variable to register adapters for autodiscovery. Should contain a tuple of module import path: “module.sub” or “.module” - and the Adapter class name.

Example

Add a custom adapter MyAdapter from module mymodule

>>> import pgmob.adapters
>>> pgmob.adapters.ADAPTERS.extend(("mymodule", "MyAdapter"))
pgmob.adapters.detect_adapter() → BaseAdapter

Detect adapter based on installed modules. You can change the order and add your own adapters by modifying the ADAPTERS module variable.

Returns:

initialized adapter object

Return type:

BaseAdapter

Adapter abstract classes

class pgmob.adapters.base.BaseAdapter

Abstract SQL Provider adapter. Defines required properties and methods to be overriden by adapter implementations.

abstractmethod close_connection() → None

Close the connection

abstractmethod commit() → None

Commit the open transaction

abstractmethod connect(*args, **kwargs) → Any

Retrieve a connection object

abstractmethod cursor() → BaseCursor

Retrieve a cursor object

abstractmethod get_autocommit() → bool

Get autocommit status

get_connection() → Any

Retrieve current connection

property has_connection: bool

Whether the connection is defined

abstract property is_connected: bool

Defines whether the connection is open or closed

abstract property is_in_transaction: bool

Defines whether the transaction is currently open

abstractmethod lobject(oid: int, mode: str) → BaseLargeObject

Retrieve a large object handler object

abstractmethod rollback() → None

Rollback the open transaction

abstractmethod set_autocommit(state: bool) → None

Set autocommit status

set_connection(connection: Any) → None

Set current connection

class pgmob.adapters.base.BaseCursor

Base Cursor adapter. Abstract class that defines the necessary methods to be overridden by the child class that implements Cursor interactions specific to the chosen module.

abstractmethod close() → None

Close the cursor. The cursor should not be used after this method is called.

abstract property closed: bool

Specifies if the cursor is closed

abstractmethod execute(query: Composable | str, params: tuple | None = None) → None

Execute a query with parameters. Should be overridden by the adapter, which should provide support for one of the two potential inputs:

  • a query string

  • a Composable object that represent one or more query parts: SQL, Literal,

    Identifier. Adapter should call the .compose() method of the query object to retrieve the parts and reprocess them as needed.

Parameters:

  • query (Union[Composable, str]) – query object or string

  • params (tuple) – query parameters as a tuple

Raises:
abstractmethod executemany(query: Composable, params: Sequence[tuple] | None = None) → None

Execute a query with multiple parameter sets. Should be overridden by the adapter, which should provide support for all possible Composable objects that represent query parts: SQL, Literal, Identifier. Adapter should call the .compose() method of the query object to retrieve the parts and reprocess them as needed.

abstractmethod fetchall() → list

Fetch all rows

Returns:

a ResultSet with the with the query results, if any.

Return type:

list

Raises:
abstractmethod fetchone() → Any

Fetch one row

Returns:

a single row of the ResultSet

Return type:

Any

Raises:
abstractmethod mogrify(query: Composable, params: tuple | None = None) → bytes

Returns a parsed SQL query based on the parameters provided. Should be overridden by the adapter, which should provide support for all possible Composable objects that represent query parts: SQL, Literal, Identifier. Adapter should call the .compose() method of the query object to retrieve the parts and reprocess them as needed.

Returns:

a bytes query string

Return type:

bytes

abstract property rowcount: int

Row count of the most recent execute

scalar(query: Composable, params: tuple | None = None) → Any

Same as execute, but returns only the first item of the first row.

Parameters:

  • query (Any) – query object or string

  • params (tuple) – query parameters as a tuple

Returns:

first item of the first row. None if no results have been returned.

Return type:

Any

Raises:
abstract property statusmessage: str

Cursor status message

class pgmob.adapters.base.BaseLargeObject

Base Large Object adapter. Abstract class that defines the necessary methods to be overridden by the child class that implements Large Object interactions specific to the chosen module.

abstractmethod close()

Close and deallocate large object

abstract property closed: bool

Specifies if the large object is closed

abstractmethod read() → str | bytes

Read large object

Returns:

string or bytes depending on the large object open mode

Return type:

Union[str, bytes]

abstractmethod truncate(length: int = 0)

Truncate large object

Parameters:

length (int) – size to truncate. 0 to remove

Remove large object

abstractmethod write(data: bytes) → int

Write large object

Returns:

number of bytes written

Return type:

int

psycopg2 adapter