ORMTableBase¶
ORMTableBase is the foundational mixin for all ORM tables in
orm-loader.
It provides: - primary key introspection - column inspection - ID allocation helpers
It contains no domain logic.
This page is generated from in-code documentation.
API¶
Mixin for SQLAlchemy ORM-mapped tables providing structural introspection and helper utilities.
This base class intentionally avoids any domain or schema semantics and is designed to sit at the lowest level of a model hierarchy.
It provides: - mapper access - primary key discovery and extraction - column inspection helpers - required-field detection for ingestion - monotonic ID allocation support
allocator(session)
classmethod
¶
Create an ID allocator initialised from the current table state.
The allocator is initialised using the current maximum primary key value and can be used to generate monotonically increasing identifiers in environments without database-managed sequences.
Used to support autoincrementing primary keys on dialects without native sequence support (e.g., SQLite).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
An active SQLAlchemy session. |
required |
Returns:
| Type | Description |
|---|---|
IdAllocator
|
An ID allocator initialised to the current maximum ID. |
mapper_for()
classmethod
¶
Return the SQLAlchemy mapper associated with this ORM class.
This is a thin wrapper around sqlalchemy.inspect that provides
a single, explicit access point for mapper inspection.
Returns:
| Type | Description |
|---|---|
Mapper
|
The mapper associated with the ORM-mapped class. |
Raises:
| Type | Description |
|---|---|
TypeError
|
If the class is not a mapped SQLAlchemy ORM class. |
max_id(session)
classmethod
¶
Return the maximum value of the primary key column.
This method only supports tables with a single-column primary key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
A SQLAlchemy session. |
required |
Returns:
| Type | Description |
|---|---|
int
|
The maximum primary key value, or 0 if the table is empty. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the table has a composite primary key. |
model_columns()
classmethod
¶
Return all mapped columns for the table.
Returns:
| Type | Description |
|---|---|
dict[str, ColumnElement]
|
A mapping of column name to column object. |
pk_columns()
classmethod
¶
Return the primary key columns for the mapped table.
The columns are returned in mapper-defined order.
Returns:
| Type | Description |
|---|---|
list[ColumnElement]
|
A list of primary key column objects. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the table has no primary key defined. |
pk_names()
classmethod
¶
Return the primary key column names.
Returns:
| Type | Description |
|---|---|
list[str]
|
A list of primary key column names. |
pk_tuple(obj)
classmethod
¶
Extract primary key values from an ORM instance as a tuple.
Values are returned in mapper-defined primary key order.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
Any
|
An ORM-mapped instance of this class. |
required |
Returns:
| Type | Description |
|---|---|
tuple
|
A tuple of primary key values. |
pk_values(obj)
classmethod
¶
Extract primary key values from an ORM instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
Any
|
An ORM-mapped instance of this class. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary mapping primary key column names to values. |
required_columns()
classmethod
¶
Return column names that must be present in inbound data.
A column is considered required if it is: - non-nullable - has no Python-side default - has no server-side default
This method is intended for ingestion-time validation and does not attempt to enforce schema semantics beyond insert viability.
Returns:
| Type | Description |
|---|---|
set[str]
|
A set of required column names. |