httk.store.backend.schema¶

Schema IR: resolve a storable dataclass into the relational schema that drives storage.

A storable class is a plain frozen dataclass declared with the stdlib-only marker vocabulary from httk-core (Indexed, Unique, Skip, IdentitySkip, Shape, StorageInfo, stored_property). resolve_schema() reads the class once — dataclass fields, Annotated markers, stored properties, and the optional class-level or externally registered StorageInfo — and produces a TableSchema, the single source of truth from which the SQL layer derives DDL, inserts, selects, and reconstruction alike.

Resolution rules (field annotation, then the resulting relational shape):

int/str/bool/bytes — one scalar column named after the field (bool is its own column kind, never folded into int). float uses a query DOUBLE plus an exact *_exact hexadecimal text column so signed zero and every other finite binary64 value round-trip unchanged.
X | None — the field is optional; all of its columns become nullable.
a type with a registered ValueCodec (fractions.Fraction, FracScalar, SurdScalar, datetime.datetime, …) — the codec’s columns, named by appending each suffix to the field name.
Annotated[FracVector, Shape(r, c)] with r >= 1 — a fixed-shape tensor stored inline: r*c float columns name_0 .. name_{r*c-1} plus one name_exact text column holding the canonical exact tensor text.
Annotated[FracVector, Shape(0, c)] — variable rows in a child table <parent>_<name>, each row c float columns plus a name_exact text column with the same exact encoding per row.
list[T] / homogeneous tuple[T, ...] — a child table: scalar or codec-typed elements store their columns per row; storable-dataclass elements store one name_sid foreign-key column per row.
another storable frozen dataclass (optionally | None) — a reference: one name_sid foreign-key column.
Annotated[..., Skip()] — omitted from storage (the field must have a default so instances can be reconstructed without it).
Annotated[..., IdentitySkip()] — stored normally but omitted from representation identity.
Annotated[..., Related(...)] — relationship metadata carried on the resolved FieldSpec; valid only on reference fields and on lists/tuples of storable classes.
a stored_property — resolved like a field from its return annotation, flagged derived: stored and queryable, recomputed (not passed to __init__) on reconstruction.

Optional child fields also receive a store-managed Boolean <field>_present parent column, preserving the distinction between None and an empty child sequence.

The store layer additionally manages a sid integer primary key and a content_id text column on every table (and <parent>_sid / <name>_index columns on child tables); those never appear in TableSchema.fields, and declaring a field named sid or content_id is an error.

Attributes¶

`ScalarKind`	The five scalar column kinds a storage backend must provide.
`FieldRole`	How a stored field maps onto the relational model.

Exceptions¶

SchemaError

A class or field cannot be resolved into a storage schema; the message names both.

Classes¶

`ColumnSpec`	Describe one scalar column of a table.
`ChildTableSpec`	Describe the out-of-line child table backing a variable-length field.
`FieldSpec`	Describe the resolved storage shape of one stored field or property.
`LinkSpec`	Describe one resolved weak-link declaration of a storable class.
`TableSchema`	Describe the resolved relational schema of one storable class.

Functions¶

`register_schema_override`(cls, info)	Register an external `StorageInfo` for a class that cannot declare one.
`resolve_schema`(cls, *[, override])	Resolve (and cache) the `TableSchema` of a storable dataclass.

Module Contents¶

type httk.store.backend.schema.ScalarKind = Literal['int', 'float', 'str', 'bool', 'bytes']¶: The five scalar column kinds a storage backend must provide.

type httk.store.backend.schema.FieldRole = Literal['scalar', 'encoded', 'fixed_array', 'child', 'reference']¶: How a stored field maps onto the relational model.

exception httk.store.backend.schema.SchemaError¶

Bases: Exception

A class or field cannot be resolved into a storage schema; the message names both.

class httk.store.backend.schema.ColumnSpec¶

Describe one scalar column of a table.

Parameters:

name – The column name.
kind – The scalar storage kind.
nullable – Whether the column accepts NULL.
indexed – Whether a single-column index is requested.
unique – Whether a unique index is requested.

name: str¶: The column name.

kind: httk.store.backend.codecs.ScalarKind¶: The scalar kind of the column.

nullable: bool = False¶: Whether the column accepts NULL (all columns of an optional field do).

indexed: bool = False¶: Whether a single-column index is requested (Indexed).

unique: bool = False¶: Whether a unique index is requested (Unique).

class httk.store.backend.schema.ChildTableSpec¶

Describe the out-of-line child table backing a variable-length field.

Only the per-element value columns are listed; the store layer adds the <parent>_sid foreign key and <name>_index ordering columns.

Parameters:

table_name – The child table name.
element_columns – The value columns of one element row.
target – The storable element class for foreign-key rows, if any.

table_name: str¶: The child table name, <parent table>_<field>.

element_columns: tuple[ColumnSpec, Ellipsis]¶: The value column(s) of one element row.

target: type | None = None¶: The storable element class when rows are foreign keys, else None.

class httk.store.backend.schema.FieldSpec¶

Describe the resolved storage shape of one stored field or property.

Parameters:

field – The dataclass field or stored property name.
python_type – The field value type after marker and optionality resolution.
role – How the field maps onto the relational model.
columns – The field columns in the parent table.
codec_name – The codec name for the field or its child elements, if any.
shape – The tensor shape marker, if any.
child – The child table specification, if the field has a child role.
target – The referenced storable class, if any.
related – The relationship marker, if any.
derived – Whether the value is a stored property recomputed on reconstruction.
optional – Whether the annotation permits None.

field: str¶: The dataclass field (or stored property) name.

python_type: Any¶: The field’s value type with markers and optionality stripped.

role: FieldRole¶: How the field maps onto the relational model.

columns: tuple[ColumnSpec, Ellipsis] = ()¶: The field’s columns in the parent table (empty for the child role).

codec_name: str | None = None¶: The value codec encoding this field (or its child elements), if any.

shape: httk.core.storage.Shape | None = None¶: The Shape marker for tensor-valued fields, if any.

child: ChildTableSpec | None = None¶: The child table specification for the child role, else None.

target: type | None = None¶: The referenced storable class for reference (and child-of-storable) fields.

related: httk.core.storage.Related | None = None¶

The Related relationship marker of the field, if any.

Only reference fields and child fields of storable elements can carry one; the marker’s metadata flows into the relationships an entry provider emits for the field.

strong_link: httk.core.storage.StrongLink | None = None¶

The StrongLink edge-collection marker of the field, if any.

Carried on a child field whose element class is an edge record with the string fields label, entry_type, and entry_id. It is presentation metadata for the serving edge (which projects the field as forward and reverse OPTIMADE relationships); it is deliberately excluded from the schema fingerprint, exactly as StrongLink is excluded from content identity.

derived: bool = False¶

stored and queryable, recomputed rather than passed to __init__ on reconstruction.

Type:: True for stored_property values

optional: bool = False¶: True when the annotation permits None; child fields also use a managed presence column.

class httk.store.backend.schema.LinkSpec¶

Describe one resolved weak-link declaration of a storable class.

A weak link is a store-managed, lineage-level association living in a dedicated append-only link table (never in a record field), declared as a WeakLink in links. Endpoints bind lineages and always resolve to the latest revision on either side.

Parameters:

name – The link name; namespaces the link (e.g. record.links.<name>).
target – The storable class this link points at.
exposed_relationship – Whether the link is served through the OPTIMADE relationship facility.
role – The machine-readable relationship role, if any.
description – The human-readable relationship description, if any.
table_name – The dedicated link table name.

name: str¶: The link name, namespacing it under the source class’s links.

target: type¶: The storable class the link points at.

exposed_relationship: bool¶: Whether the link is served through the OPTIMADE relationship facility.

role: str | None¶: The machine-readable relationship role, if any.

description: str | None¶: The human-readable relationship description, if any.

table_name: str¶: The dedicated link table name, _httk_link_<source table>__<target table>__<name>.

class httk.store.backend.schema.TableSchema¶

Describe the resolved relational schema of one storable class.

Parameters:

cls – The storable dataclass resolved into this schema.
table_name – The table name used for the class.
fields – The stored fields and properties.
composite_indexes – The resolved composite index declarations.
dedup – The deduplication policy applied on save.
links – The resolved weak-link declarations.

cls: type¶: The storable dataclass this schema was resolved from.

table_name: str¶: The table name (storage_name or the snake-cased class name).

fields: tuple[FieldSpec, Ellipsis]¶

The stored fields, dataclass fields first (in declaration order), then stored properties.

The store-managed sid and content_id columns are not fields and do not appear here.

composite_indexes: tuple[tuple[str, Ellipsis], Ellipsis]¶: The indexes declarations, resolved to column names.

dedup: httk.core.storage.DedupPolicy¶: The deduplication policy applied when instances are saved.

links: tuple[LinkSpec, Ellipsis] = ()¶

The class’s resolved links weak-link declarations.

Each declaration is resolved to a LinkSpec: names are unique, valid identifiers that do not collide with field or reserved names, and each is assigned its dedicated link table name.

field(name)¶

Return the field specification named name.

Parameters:: name (str) – The stored field or property name.
Returns:: The matching field specification.
Raises:: httk.store.backend.schema.SchemaError – If no stored field has that name.
Return type:: FieldSpec

referenced_classes()¶

Return the distinct referenced storable classes in field order.

Returns:: The referenced classes without duplicates.
Return type:: tuple[type, Ellipsis]

httk.store.backend.schema.register_schema_override(cls, info)¶

The registered info is used by resolve_schema() whenever no explicit override argument is passed, and takes precedence over a __httk_storage__ declaration on the class itself.

Parameters:

cls (type) – The storable class whose schema should be overridden.
info (httk.core.storage.StorageInfo) – The external storage information to register.

Returns:

None.

Return type:

None

httk.store.backend.schema.resolve_schema(cls, *, override=None)¶

Resolve (and cache) the TableSchema of a storable dataclass.

The effective StorageInfo is, in order of precedence: the explicit override argument, an info registered via register_schema_override(), the class’s own __httk_storage__ attribute, or defaults. Results are cached per (class, effective override), so repeated calls return the same TableSchema object. Reference cycles (a class referencing itself, or mutually referencing classes) are allowed and resolve without recursion loops.

Parameters:

cls (type) – The storable class to resolve.
override (httk.core.storage.StorageInfo | None) – External storage information taking precedence over declarations.

Returns:

The cached resolved table schema.

Raises:

httk.store.backend.schema.SchemaError – If the class is not a frozen dataclass or one of its fields cannot be resolved; the diagnostic names the class and field.

Return type:

TableSchema