THE ORIONIS API
Build with clarity.
Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.
Provide database operations.
Includes resolve_driver, missing_dependency_error, build_engine_url, engine_options.
| Class | _ |
Native async client whose close operation must settle after cancellation. |
| Class | _ |
Collect a late native client before propagating caller cancellation. |
| Class | _ |
Escape binary parameters independently of aiomysql's removed converter. |
| Function | _begin |
Start a SQLite transaction using the requested write reservation. |
| Function | _config |
Extract a trimmed text value from a configuration mapping. |
| Function | _configure |
Protect native client creation while keeping pool waiters cancellable. |
| Function | _configure |
Install safe binary conversion on one adapted aiomysql connection. |
| Function | _enum |
Extract the primitive value from a possible enum member. |
| Function | _is |
Report whether a SQLite configuration targets an in-memory database. |
| Function | _mysql |
Build the MySQL session commands for a configuration. |
| Function | _normalize |
Normalize a boolean-like configuration value to ON or OFF. |
| Function | _oracle |
Build the URL query parameters for an Oracle connection. |
| Function | _oracle |
Build the engine URL for an Oracle connection. |
| Function | _pgsql |
Build asyncpg or libpq connect arguments for PostgreSQL. |
| Function | _pgsql |
Build libpq connection arguments with one escaped search-path option. |
| Function | _server |
Build the URL query parameters for host-based drivers. |
| Function | _server |
Build the engine URL for host-based drivers. |
| Function | _session |
Build the per-connection session statements for a configuration. |
| Function | _sqlite |
Build the PRAGMA statements for a SQLite configuration. |
| Function | _sqlite |
Build the engine URL for a SQLite connection. |
| Function | _yes |
Normalize a boolean-like configuration value to yes or no. |
| Function | build |
Build the engine URL for a connection configuration. |
| Function | configure |
Apply driver-specific session settings to a freshly built engine. |
| Function | engine |
Build keyword options for an engine factory. |
| Function | missing |
Build the exception raised when a DB driver package is absent. |
| Function | resolve |
Extract and validate the driver name from a connection configuration. |
| Constant | _ASYNC |
Map of Orionis driver names to SQLAlchemy async dialect names. |
| Constant | _ASYNC |
Map of Orionis driver names to (driver package, install extra) hints. |
| Constant | _DEFAULT |
Default ODBC driver used for SQL Server connections. |
| Constant | _IDENTIFIER |
Charset and collation identifiers accepted in session commands. |
| Constant | _MYSQL |
MySQL relaxed sql_mode applied when strict mode is disabled. |
| Constant | _MYSQL |
MySQL strict sql_mode flags. |
| Constant | _REDSHIFT |
Redshift connect options definitions used by dialect. |
| Constant | _SQLITE |
SQLite database markers that identify an in-memory database. |
| Constant | _SYNC |
Map of Orionis driver names to SQLAlchemy dialects backed by a blocking (synchronous) DBAPI driver. Used to build engines for consumers that cannot use the async engine, such as APScheduler's scheduleTaskStore. |
| Constant | _SYNC |
Map of Orionis driver names to (driver package, install extra) hints for the synchronous DBAPI drivers above. SQLite needs nothing extra (stdlib sqlite3); Oracle reuses the async package, which also works synchronously... |
Start a SQLite transaction using the requested write reservation.
| Parameters | |
connection:sqlalchemy.engine.Connection | Connection whose execution options select the transaction mode. |
| Returns | |
None | No return value. |
Install safe binary conversion on one adapted aiomysql connection.
PyMySQL 1.2.3 keeps escape_bytes_prefixed as a noncallable import alias; aiomysql 0.3.2 calls that alias for every bytes parameter. Hex literals keep binary storage working without downgrading PyMySQL or patching its modules.
| Parameters | |
dbapiobject | SQLAlchemy DBAPI adapter exposing its underlying driver connection. |
| Returns | |
None | No return value. |
Build the MySQL session commands for a configuration.
Applies the connection charset and collation through SET NAMES and the strict (or relaxed) sql_mode preset, mirroring the behavior of mainstream frameworks.
| Parameters | |
config:dict | MySQL connection configuration. |
| Returns | |
tuple of str | Session commands to run on each new pooled connection. |
dict[ str, Any], *, sync: bool = False) -> dict[ str, Any]:
(source)
¶
Build asyncpg or libpq connect arguments for PostgreSQL.
Maps sslmode to the driver ssl argument and forwards the configured search_path and charset as server settings.
| Parameters | |
config:dict | PostgreSQL connection configuration. |
sync:bool, optional | Whether to build the blocking libpq options instead of asyncpg settings. |
| Returns | |
dict | Driver connect arguments; empty when nothing is configured. |
Build libpq connection arguments with one escaped search-path option.
| Parameters | |
config:dict[str, typing.Any] | PostgreSQL connection settings for the blocking driver. |
| Returns | |
dict[str, typing.Any] | SSL, client encoding and safely escaped startup options. |
Build the engine URL for host-based drivers.
Covers MySQL, PostgreSQL, and SQL Server connections addressed by host, port, and database name.
| Parameters | |
driver:str | Normalized driver name. |
config:dict | Connection configuration. |
dialect:str | SQLAlchemy dialect name to build the URL for. |
| Returns | |
sqlalchemy.URL | Engine URL with credentials, host, port, and database. |
Build the engine URL for a SQLite connection.
The engine URL is always derived from the database path; the informational url key (sync-style DSN) is intentionally ignored.
| Parameters | |
config:dict | SQLite connection configuration. |
dialect:str | SQLAlchemy dialect name to build the URL for. |
| Returns | |
sqlalchemy.URL | SQLite engine URL. |
Build the engine URL for a connection configuration.
| Parameters | |
config:dict | Connection configuration produced by the database config entities. |
sync:bool, optional | Whether to select the blocking DBAPI dialect instead of the async one. |
| Returns | |
sqlalchemy.URL | Engine URL for the configured driver. |
| Raises | |
orionis.database.UnsupportedDriverException | If the driver has no registered dialect. |
Apply driver-specific session settings to a freshly built engine.
For SQLite this installs a connect hook applying the configured PRAGMA settings; for MySQL it applies the connection charset, collation, and strict mode on every new pooled connection.
| Parameters | |
engine:AsyncEngine | ThreadedEngine | Engine to configure. |
config:dict | Connection configuration. |
| Returns | |
None | No return value. |
str, cause: ImportError | NoSuchModuleError, *, sync: bool = False) -> MissingDatabaseDependencyException:
(source)
¶
Build the exception raised when a DB driver package is absent.
| Parameters | |
driver:str | Orionis driver name whose package is missing. |
cause:ImportError | sqlalchemy.exc.NoSuchModuleError | Original missing driver or dialect error raised by the engine. |
sync:bool, optional | Whether the missing package is the blocking (synchronous) driver instead of the default async one. |
| Returns | |
orionis.database.MissingDatabaseDependencyException | Exception with an actionable uv installation hint. |
Extract and validate the driver name from a connection configuration.
| Parameters | |
config:dict | Connection configuration containing a driver key. |
| Returns | |
str | Normalized driver name. |
| Raises | |
orionis.database.UnsupportedDriverException | If the driver is missing or has no registered dialect. |
Map of Orionis driver names to SQLAlchemy async dialect names.
| Value |
|
Map of Orionis driver names to (driver package, install extra) hints.
| Value |
|
MySQL strict sql_mode flags.
| Value |
|
Redshift connect options definitions used by dialect.
| Value |
|
Map of Orionis driver names to SQLAlchemy dialects backed by a blocking (synchronous) DBAPI driver. Used to build engines for consumers that cannot use the async engine, such as APScheduler's scheduleTaskStore.
| Value |
|
Map of Orionis driver names to (driver package, install extra) hints for the synchronous DBAPI drivers above. SQLite needs nothing extra (stdlib sqlite3); Oracle reuses the async package, which also works synchronously. The other extras install both the async and sync driver together.
| Value |
|