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.
Contract for a single named database connection.
A connection encapsulates the SQL engine entirely: it accepts Orionis query plans or raw SQL strings and always returns plain Python values (dictionaries, integers, result entities). Engine objects never leak through this interface.
| Async Method | begin |
Begin a transaction, or a savepoint when one is already active. |
| Async Method | commit |
Commit the innermost active transaction or savepoint. |
| Async Method | create |
Create the physical table described by the given definition. |
| Async Method | delete |
Run a DELETE statement described by the given plan. |
| Async Method | disconnect |
Dispose the underlying engine and release its pooled resources. |
| Async Method | drop |
Drop the physical table with the given logical name. |
| Async Method | execute |
Run a raw data-modifying SQL statement. |
| Method | get |
Return the configured name of this connection. |
| Async Method | insert |
Run an INSERT statement described by the given plan. |
| Method | in |
Report whether a transaction is active in the current task. |
| Async Method | rollback |
Roll back the innermost active transaction or savepoint. |
| Async Method | scalar |
Run a SELECT plan and return the first column of the first row. |
| Async Method | select |
Run a SELECT query and return its rows as dictionaries. |
| Async Method | statement |
Run a raw SQL statement without inspecting its result. |
| Method | supports |
Report whether primary and unique keys reject duplicate values. |
| Method | to |
Render a SELECT plan without executing it or opening a connection. |
| Method | transaction |
Return a transaction usable as an async context manager. |
| Async Method | update |
Run an UPDATE statement described by the given plan. |
| Class Variable | __slots__ |
Declare that this class introduces no additional instance slots. |
orionis.database.ConnectionBegin a transaction, or a savepoint when one is already active.
| Returns | |
None | No return value. |
| Raises | |
orionis.database.TransactionException | If the transaction cannot be started. |
orionis.database.ConnectionCommit the innermost active transaction or savepoint.
| Returns | |
None | No return value. |
| Raises | |
orionis.database.TransactionException | If no transaction is active. |
TableDefinition, *, if_not_exists: bool = True) -> bool:
(source)
¶
orionis.database.ConnectionCreate the physical table described by the given definition.
| Parameters | |
table:orionis.orm.schema.TableDefinition | Table definition to materialize. |
ifbool, optional | Whether to guard the statement with IF NOT EXISTS so that an already existing table is silently kept. |
| Returns | |
bool | True when the statement executes without errors. |
| Raises | |
orionis.database.QueryException | If the DDL statement fails to execute. |
orionis.database.ConnectionRun a DELETE statement described by the given plan.
| Parameters | |
plan:orionis.orm.query.DeletePlan | Delete plan with filtering conditions. |
| Returns | |
int | Number of affected rows. |
| Raises | |
orionis.database.QueryException | If the statement fails to compile or execute. |
orionis.database.ConnectionDispose the underlying engine and release its pooled resources.
| Returns | |
None | No return value. |
str, schema: str | None = None, *, if_exists: bool = True) -> bool:
(source)
¶
orionis.database.ConnectionDrop the physical table with the given logical name.
| Parameters | |
name:str | Logical table name; the connection prefix is applied. |
schema:str or None, optional | Database schema owning the table, or None for the default. |
ifbool, optional | Whether to guard the statement with IF EXISTS so that a missing table does not raise an error. |
| Returns | |
bool | True when the statement executes without errors. |
| Raises | |
orionis.database.QueryException | If the DDL statement fails to execute. |
str, bindings: Mapping[ str, Any] | None = None) -> int:
(source)
¶
orionis.database.ConnectionRun a raw data-modifying SQL statement.
| Parameters | |
sql:str | Raw SQL using named :param placeholders. |
bindings:collections.abc.Mapping of str to typing.Any, optional | Bound parameters for the statement. |
| Returns | |
int | Number of affected rows. |
| Raises | |
orionis.database.QueryException | If the statement fails to execute. |
orionis.database.ConnectionReturn the configured name of this connection.
| Returns | |
str | Connection name as registered in the manager. |
orionis.database.ConnectionRun an INSERT statement described by the given plan.
| Parameters | |
plan:orionis.orm.query.InsertPlan | Insert plan with the target table and row values. |
| Returns | |
orionis.database.entities.InsertResult | Result carrying the generated key and affected row count. |
| Raises | |
orionis.database.QueryException | If the statement fails to compile or execute. |
orionis.database.ConnectionReport whether a transaction is active in the current task.
| Returns | |
bool | True when at least one transaction level is open. |
orionis.database.ConnectionRoll back the innermost active transaction or savepoint.
| Returns | |
None | No return value. |
| Raises | |
orionis.database.TransactionException | If no transaction is active. |
orionis.database.ConnectionRun a SELECT plan and return the first column of the first row.
| Parameters | |
plan:orionis.orm.query.SelectPlan | Query plan, typically carrying an aggregate projection. |
| Returns | |
typing.Any | Scalar value, or None when the query yields no rows. |
| Raises | |
orionis.database.QueryException | If the statement fails to compile or execute. |
SelectPlan | str, bindings: Mapping[ str, Any] | None = None) -> list[ dict[ str, Any]]:
(source)
¶
orionis.database.ConnectionRun a SELECT query and return its rows as dictionaries.
| Parameters | |
query:orionis.orm.query.SelectPlan or str | Compiled query plan, or a raw SQL string using named :param placeholders. |
bindings:collections.abc.Mapping of str to typing.Any, optional | Bound parameters for raw SQL strings. |
| Returns | |
list of dict | One dictionary per row keyed by column name. |
| Raises | |
orionis.database.QueryException | If the statement fails to compile or execute. |
str, bindings: Mapping[ str, Any] | None = None) -> bool:
(source)
¶
orionis.database.ConnectionRun a raw SQL statement without inspecting its result.
Intended for DDL and maintenance commands.
| Parameters | |
sql:str | Raw SQL statement. |
bindings:collections.abc.Mapping of str to typing.Any, optional | Bound parameters for the statement. |
| Returns | |
bool | True when the statement executes without errors. |
| Raises | |
orionis.database.QueryException | If the statement fails to execute. |
orionis.database.ConnectionReport whether primary and unique keys reject duplicate values.
Custom connections retain the relational default. Backends whose keys are only informational must override this capability so consumers can reject operations that require a database-enforced unique claim.
| Returns | |
bool | Whether uniqueness is enforced by the database. |
SelectPlan, *, literal_binds: bool = False) -> str:
(source)
¶
orionis.database.ConnectionRender a SELECT plan without executing it or opening a connection.
| Parameters | |
plan:orionis.orm.query.SelectPlan | Query plan to render with the configured connection dialect. |
literalbool, optional | Include values for debugging when their types support SQL literals. Literal output may expose sensitive information. |
| Returns | |
str | SQL text with expanded placeholders or literal parameter values. |
| Raises | |
orionis.database.QueryException | If the plan or a literal value cannot be compiled. |
orionis.database.MissingDatabaseDependencyException | If the configured SQL dialect is unavailable. |
orionis.database.ConnectionReturn a transaction usable as an async context manager.
| Returns | |
orionis.database.contracts.ITransaction | Context manager committing on success and rolling back on error. |
orionis.database.ConnectionRun an UPDATE statement described by the given plan.
| Parameters | |
plan:orionis.orm.query.UpdatePlan | Update plan with values and filtering conditions. |
| Returns | |
int | Number of affected rows. |
| Raises | |
orionis.database.QueryException | If the statement fails to compile or execute. |
orionis.database.ConnectionDeclare that this class introduces no additional instance slots.