Provider API¶

Providers are the adapter layer between NextORM and DBAPI drivers.

Built-in database providers for nextorm.

Importing this package triggers registration of all built-in providers. Currently registered providers:

"sqlite" — sync: SQLiteSyncProvider, async: SQLiteAsyncProvider
"postgres" — sync: PostgresSyncProvider, async: PostgresAsyncProvider
"mariadb" — sync: MariaDBSyncProvider, async: MariaDBAsyncProvider

Public ABC re-exports¶

The following names are re-exported here for convenience so that library consumers only need to import from nextorm.providers:

ProviderBase
SyncProvider, SyncConnection, SyncCursor
AsyncProvider, AsyncConnection, AsyncCursor
DbRow
register_provider(), get_sync_provider(), get_async_provider(), registered_providers()

class nextorm.providers.ProviderBase[source]¶

Bases: ABC

Common metadata shared by sync and async providers.

name: str¶: Short name used in Database.bind("sqlite", …).

param_style: str¶

"qmark", "format", "numeric", "named", or "pyformat".

Type:: DBAPI-2 param-style

abstractmethod placeholder(param_name=None)[source]¶

Return the SQL placeholder string for a single parameter.

Parameters¶

param_name:: The logical name of the parameter (used by named-style drivers). Ignored by positional-style drivers.

Parameters:: param_name (str | None)
Return type:: str

class nextorm.providers.SyncProvider[source]¶

Bases: ProviderBase

Abstract base for synchronous (DBAPI-2) database providers.

Concrete subclasses must implement connect() and the abstract methods inherited from ProviderBase.

abstractmethod connect(*args, **kwargs)[source]¶

Open a new synchronous connection.

The returned object must implement SyncConnection.

Parameters¶

*args / **kwargs:: Driver-specific connection arguments (forwarded from Database.bind(provider, *args, **kwargs)).

Parameters:

args (Any)
kwargs (Any)

Return type:

SyncConnection

abstractmethod execute_ddl(connection, statements)[source]¶

Execute a list of DDL statements on connection.

Provides a hook for providers that need special handling (e.g. SQLite’s executescript disables autocommit).

Parameters:

connection (SyncConnection)
statements (list[str])

Return type:

None

abstractmethod introspect(connection)[source]¶

Read and return the current schema from connection.

Returns a {table_name: Table} mapping reflecting the tables, columns, and indexes that currently exist in the database. Used by migrate() to compute the diff between the live schema and the entity-derived target schema.

Parameters:: connection (SyncConnection)
Return type:: dict[str, Table]

class nextorm.providers.SyncConnection[source]¶

Bases: ABC

Minimal sync connection interface (DBAPI-2 subset).

abstractmethod cursor()[source]¶

Return a new cursor for this connection.

Return type:: SyncCursor

abstractmethod commit()[source]¶

Commit the current transaction.

Return type:: None

abstractmethod rollback()[source]¶

Roll back the current transaction.

Return type:: None

abstractmethod close()[source]¶

Close the connection.

Return type:: None

abstractmethod executescript(sql)[source]¶

Execute a multi-statement SQL script (used for DDL).

Parameters:: sql (str)
Return type:: None

class nextorm.providers.SyncCursor[source]¶

Bases: ABC

Minimal sync cursor interface (DBAPI-2 subset).

abstract property description: Sequence[tuple[str, Any, Any, Any, Any, Any, Any]] | None¶: Column descriptions from the last executed query.

abstract property rowcount: int¶: Number of rows affected / returned by the last statement.

abstract property lastrowid: int | None¶: Row-id of the last INSERT (None if not applicable).

abstractmethod execute(sql, parameters=())[source]¶

Execute a single SQL statement.

Parameters:

sql (str)
parameters (Sequence[Any] | Mapping[str, Any])

Return type:

None

abstractmethod executemany(sql, seq_of_parameters)[source]¶

Execute a parameterised statement for each row in seq_of_parameters.

Parameters:

sql (str)
seq_of_parameters (Sequence[Sequence[Any]])

Return type:

None

abstractmethod fetchone()[source]¶

Return the next row, or None if no more rows.

Return type:: tuple[Any, …] | None

abstractmethod fetchmany(size=1)[source]¶

Return up to size rows.

Parameters:: size (int)
Return type:: Sequence[DbRow]

abstractmethod fetchall()[source]¶

Return all remaining rows.

Return type:: Sequence[DbRow]

abstractmethod close()[source]¶

Release cursor resources.

Return type:: None

class nextorm.providers.AsyncProvider[source]¶

Bases: ProviderBase

Abstract base for async database providers.

Concrete subclasses must implement connect() and the abstract methods inherited from ProviderBase.

abstractmethod async connect(*args, **kwargs)[source]¶

Open a new async connection.

Parameters:

args (Any)
kwargs (Any)

Return type:

AsyncConnection

abstractmethod async execute_ddl(connection, statements)[source]¶

Execute a list of DDL statements asynchronously.

Parameters:

connection (AsyncConnection)
statements (list[str])

Return type:

None

class nextorm.providers.AsyncConnection[source]¶

Bases: ABC

Minimal async connection interface.

abstractmethod async cursor()[source]¶

Return a new async cursor.

Return type:: AsyncCursor

abstractmethod async commit()[source]¶

Commit the current transaction asynchronously.

Return type:: None

abstractmethod async rollback()[source]¶

Roll back the current transaction asynchronously.

Return type:: None

abstractmethod async close()[source]¶

Close the connection asynchronously.

Return type:: None

abstractmethod async executescript(sql)[source]¶

Execute a multi-statement SQL script asynchronously.

Parameters:: sql (str)
Return type:: None

class nextorm.providers.AsyncCursor[source]¶

Bases: ABC

Minimal async cursor interface (mirrors DBAPI-2 but with await).

abstract property description: Sequence[tuple[str, Any, Any, Any, Any, Any, Any]] | None¶: Column descriptions from the last executed query.

abstract property rowcount: int¶: Number of rows affected / returned by the last statement.

abstract property lastrowid: int | None¶: Row-id of the last INSERT (None if not applicable).

abstractmethod async execute(sql, parameters=())[source]¶

Execute a single SQL statement asynchronously.

Parameters:

sql (str)
parameters (Sequence[Any] | Mapping[str, Any])

Return type:

None

abstractmethod async executemany(sql, seq_of_parameters)[source]¶

Execute a parameterised statement for each row asynchronously.

Parameters:

sql (str)
seq_of_parameters (Sequence[Sequence[Any]])

Return type:

None

abstractmethod async fetchone()[source]¶

Return the next row asynchronously.

Return type:: tuple[Any, …] | None

abstractmethod async fetchmany(size=1)[source]¶

Return up to size rows asynchronously.

Parameters:: size (int)
Return type:: Sequence[DbRow]

abstractmethod async fetchall()[source]¶

Return all remaining rows asynchronously.

Return type:: Sequence[DbRow]

abstractmethod async close()[source]¶

Release cursor resources asynchronously.

Return type:: None

nextorm.providers.register_provider(name, *, sync=None, async_=None)[source]¶

Called at module import time by each provider module.

Parameters:

name (str)
sync (type[SyncProvider] | None)
async_ (type[AsyncProvider] | None)

Return type:

None

nextorm.providers.get_sync_provider(name)[source]¶

Return the sync provider class for name, or raise ValueError.

Parameters:: name (str)
Return type:: type[SyncProvider]

nextorm.providers.get_async_provider(name)[source]¶

Return the async provider class for name, or raise ValueError.

Parameters:: name (str)
Return type:: type[AsyncProvider]

nextorm.providers.registered_providers()[source]¶

Return a sorted list of all registered provider names.

Return type:: list[str]