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.

abstract close_connection() → None

Close the connection

abstract commit() → None

Commit the open transaction

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

Retrieve a connection object

abstract cursor() → BaseCursor

Retrieve a cursor object

abstract 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

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

Retrieve a large object handler object

abstract rollback() → None

Rollback the open transaction

abstract 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.

abstract 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

abstract 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:
abstract 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.

abstract fetchall() → list

Fetch all rows

Returns:

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

Return type:

list

Raises:
abstract fetchone() → Any

Fetch one row

Returns:

a single row of the ResultSet

Return type:

Any

Raises:
abstract 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.

abstract close()

Close and deallocate large object

abstract property closed: bool

Specifies if the large object is closed

abstract read() → str | bytes

Read large object

Returns:

string or bytes depending on the large object open mode

Return type:

Union[str, bytes]

abstract truncate(length: int = 0)

Truncate large object

Parameters:

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

Remove large object

abstract write(data: bytes) → int

Write large object

Returns:

number of bytes written

Return type:

int

psycopg2 adapter

class pgmob.adapters.psycopg2.Psycopg2Adapter(cursor_factory: DictCursorBase | None = None)

Psycopg2 adapter for PGMob. Implements all necessary protocols to communicate with Postgres using psycopg2 module.

close_connection() → None

Close the connection immediately. The connection will be unusable from this point forward.

commit() → None

Commit the open transaction

connect(*args, **kwargs) → Any

Establish connection to the Postgres server.

cursor() → Psycopg2Cursor

Retrieve the cursor object using the current connection

get_autocommit() → bool

Get autocommit status

property is_connected: bool

Defines whether the connection is open or closed

property is_in_transaction: bool

Defines whether the transaction is currently open

lobject(oid: int, mode: str) → Psycopg2LargeObject

Retrieve the large object handler using the current connection

Parameters:

  • oid (int) – large object oid

  • mode (str) –

    connection mode:

    • r: Open for read only

    • w: Open for write only

    • rw: Open for read/write

    • n: Don’t open the file

    • b: Return data as bytes

    • t: Decode data as string

rollback() → None

Rollback the open transaction

set_autocommit(state: bool) → None

Set autocommit status

class pgmob.adapters.psycopg2.Psycopg2Cursor(connection: Any, *args, **kwargs)

Psycopg2 Cursor Adapter. Defines the cursor behaviour when working with psycopg2 module.

Parameters:

  • connection (Any) – psycopg2 connection object

  • *args – any other parameters to be passed on to the cursor

  • **kwargs – any other parameters to be passed on to the cursor

close() → None

Close the currently open cursor

property closed: bool

Specifies if the cursor is closed

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

Execute a query with parameters

Parameters:

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

  • params (tuple) – query parameters as a tuple

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

Execute a query with multiple parameter sets

fetchall() → list

Fetch all rows

Returns:

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

Return type:

list

fetchone() → Any

Fetch one row

Returns:

a single row of the ResultSet

Return type:

Any

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

Returns a parsed SQL query based on the parameters provided

Returns:

a bytes query string

Return type:

bytes

property rowcount: int

Row count of the most recent execute

property statusmessage: str

Cursor status message

class pgmob.adapters.psycopg2.Psycopg2LargeObject(connection: Any, oid: int, mode: str, *args, **kwargs)

Large Object adapter. Implements Large Object interactions when working with psycopg2 module.

Parameters:

  • connection (Any) – connection object

  • oid (int) – large object oid

  • mode (str) –

    connection mode

    • r: Open for read only

    • w: Open for write only

    • rw: Open for read/write

    • n: Don’t open the file

    • b: Return data as bytes

    • t: Decode data as string

close()

Close and deallocate large object

property closed: bool

Specifies if the large object is closed

read() → str | bytes

Read large object

Returns:

string or bytes depending on the large object open mode

Return type:

Union[str, bytes]

truncate(length: int = 0)

Truncate large object

Parameters:

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

Remove large object

write(data: bytes) → int

Write large object

Returns:

number of bytes written

Return type:

int