SerialisableTableInterface¶
Mixin providing explicit, deterministic serialisation helpers for ORM row instances.
Supports: - dictionary conversion - JSON serialisation - stable row fingerprints
API¶
Bases: ORMTableBase
Mixin for SQLAlchemy ORM tables providing explicit serialisation helpers.
This interface adds lightweight, deterministic helpers for converting ORM-mapped rows into dictionaries, JSON strings, and stable fingerprints.
It is intended for: - debugging and inspection - auditing and reproducibility checks - lightweight export or API layers - content-addressable comparisons
No assumptions are made about schema semantics or domain logic.
__iter__()
¶
Iterate over the ORM instance as (key, value) pairs.
This enables lightweight unpacking and interoperability with dictionary-based APIs.
Yields:
| Type | Description |
|---|---|
tuple[str, Any]
|
Column name and value pairs. |
__json__()
¶
Return a JSON-serialisable representation of the ORM instance.
This hook is provided for compatibility with JSON encoders
that check for a __json__ method.
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary representation of the ORM row. |
fingerprint()
¶
Compute a stable fingerprint for the ORM instance.
The fingerprint is derived from the JSON serialisation of the row with null values included and is suitable for: - change detection - deduplication - caching - reproducibility checks
Returns:
| Type | Description |
|---|---|
str
|
A SHA-256 hexadecimal digest representing the row content. |
to_dict(*, include_nulls=False, only=None, exclude=None)
¶
Convert the ORM instance into a dictionary.
The output is derived directly from the mapped model columns and reflects the current in-memory state of the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
include_nulls
|
bool
|
Whether to include keys whose values are |
False
|
only
|
set[str] | None
|
An optional set of column names to include. If provided, all other columns are ignored. |
None
|
exclude
|
set[str] | None
|
An optional set of column names to exclude. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A dictionary representation of the ORM row. |
to_json(**kwargs)
¶
Serialise the ORM instance to a JSON string.
This method delegates to :meth:to_dict and applies a stable,
deterministic JSON encoding with sorted keys.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
**kwargs
|
Keyword arguments forwarded to :meth: |
{}
|
Returns:
| Type | Description |
|---|---|
str
|
A JSON representation of the ORM row. |