httk.store.db.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.
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.db.schema.ScalarKind = Literal['int', 'float', 'str', 'bool', 'bytes']

The five scalar column kinds a storage backend must provide.

type httk.store.db.schema.FieldRole = Literal['scalar', 'encoded', 'fixed_array', 'child', 'reference']

How a stored field maps onto the relational model.

exception httk.store.db.schema.SchemaError

Bases: Exception

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

class httk.store.db.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.db.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.db.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.db.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.

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.db.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 validated relationship 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[httk.core.storage.RelationshipLink, Ellipsis] = ()

The class’s links relationship declarations.

Each link is validated: every non-None endpoint names an existing reference field of the class (child fields are not valid endpoints — a link row expresses exactly one FROM→TO pair).

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.db.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.db.schema.register_schema_override(cls, info)

Register an external StorageInfo for a class that cannot declare one.

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.db.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.db.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