httk.data.db

The SQL storage layer of httk-data: store frozen dataclasses in relational databases.

This subpackage turns plain frozen dataclasses — declared storable with the stdlib-only marker vocabulary in httk-core (Indexed, Unique, Skip, Shape, StorageInfo, stored_property) — into relational storage. The pure-Python foundation lives here:

• httk.data.db.schema — resolve_schema() reads a storable class into a TableSchema, the single source of truth for DDL, inserts, selects, and reconstruction;

• httk.data.db.codecs — the ValueCodec registry with exact, round-trippable encodings for rationals, surds, and datetimes;

• httk.data.db.identity — canonical_form() and content_id(), the content identity used for deduplication.

These modules import cleanly without sqlalchemy. The SQL layer proper builds on them and requires the httk-data[db] extra (sqlalchemy):

• Database — the engine wrapper naming where data lives (Database.sqlite(...), Database.duckdb(...));

• SqlStore — save/fetch/dedup/transactions for storable instances, on top of the schema-to-table mapping in httk.data.db.mapping;

• SqlSearcher (from searcher()) — the query DSL implementing the httk.data.query search protocols, with SqlVariable, SqlColumn and SqlExpression;

• StoreEntryProvider — the bridge that serves stored classes through the neutral EntryProvider contract (e.g. as an OPTIMADE API via httk-optimade);

• optimade_filter_searcher() — OPTIMADE-filter querying over storable classes, tying the generic filter translation in httk.data.optimade_query to the SQL layer.

The sqlalchemy-backed names are imported lazily on first attribute access, so import httk.data.db keeps working without sqlalchemy; touching them without sqlalchemy installed raises ImportError naming the extra.

Submodules

• httk.data.db.codecs
• httk.data.db.engine
• httk.data.db.entry_provider
• httk.data.db.identity
• httk.data.db.mapping
• httk.data.db.optimade
• httk.data.db.schema
• httk.data.db.searcher
• httk.data.db.store

Attributes

FRACTION_EXACT_FORMAT	The canonical exact text of a rational — reduced "p/q", always with the /q part.
FRACVECTOR_EXACT_FORMAT	The canonical exact text of a rational tensor — common denominator, then numerators row-major.
SURD_EXACT_FORMAT	The canonical exact text of a surd scalar — radicand:coefficient terms sorted by radicand.
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

ValueCodec	An exact encoding of one Python value type across one or more scalar columns.
ChildTableSpec	The out-of-line child table backing a variable-length field.
ColumnSpec	One scalar column of a table.
FieldSpec	The resolved storage shape of one stored field (or stored property).
TableSchema	The resolved relational schema of one storable class.

Functions

codec_for(→ ValueCodec | None)	Return the codec for python_type, or None if no codec covers it.
codec_named(→ ValueCodec)	Return the codec registered as name; raise ValueError listing the known names.
decode_fraction_exact(→ fractions.Fraction)	Parse FRACTION_EXACT_FORMAT text back into an exact fractions.Fraction.
decode_fracvector_exact(→ httk.core.FracVector)	Parse FRACVECTOR_EXACT_FORMAT text into a rows x cols FracVector.
decode_surdscalar_exact(→ httk.core.SurdScalar)	Parse SURD_EXACT_FORMAT text back into an exact SurdScalar.
encode_fraction_exact(→ str)	The canonical FRACTION_EXACT_FORMAT text of value (e.g. "-7/3", "1/1").
encode_fracvector_exact(→ str)	The canonical FRACVECTOR_EXACT_FORMAT text of a rational tensor.
encode_fracvector_floats(→ tuple[float, Ellipsis])	The elements of a rational tensor as a flat row-major tuple of nearest floats.
encode_surdscalar_exact(→ str)	The canonical SURD_EXACT_FORMAT text of value ("0" for zero).
known_value_codecs(→ list[str])	Return the registered value-codec names, in registration order.
register_value_codec(→ None)	Register codec; raise ValueError on a duplicate name or Python type.
canonical_form(→ str)	The deterministic canonical JSON text of a storable instance's stored values.
content_id(→ str)	The SHA-256 hex digest (64 hex characters) of canonical_form() of obj.
register_schema_override(→ None)	Register an external StorageInfo for a class that cannot declare one.
resolve_schema(→ TableSchema)	Resolve (and cache) the TableSchema of a storable dataclass.
snake_case(→ str)	The default table name for a class name: CamelCase to camel_case (acronym-aware).

Package Contents

httk.data.db.FRACTION_EXACT_FORMAT: Final = 'p/q'

The canonical exact text of a rational — reduced "p/q", always with the /q part.

httk.data.db.FRACVECTOR_EXACT_FORMAT: Final = 'd;n0,n1,n2,...'

The canonical exact text of a rational tensor — common denominator, then numerators row-major.

httk.data.db.SURD_EXACT_FORMAT: Final = 'r1:p1/q1;r2:p2/q2;...'

The canonical exact text of a surd scalar — radicand:coefficient terms sorted by radicand.

type httk.data.db.ScalarKind = Literal['int', 'float', 'str', 'bool', 'bytes']

The five scalar column kinds a storage backend must provide.

class httk.data.db.ValueCodec

An exact encoding of one Python value type across one or more scalar columns.

The columns tuple gives (suffix, kind) pairs: the empty suffix names the field’s own column (by convention the query column), non-empty suffixes are appended to the field name by the schema layer (e.g. "_exact"). encode and decode map a value to and from the column-value tuple, in columns order, and must round-trip exactly.

name: str

Registry name of the codec (e.g. "fraction").

python_type: type

The Python type this codec stores; matched exactly first, then by subclass.

columns: tuple[tuple[str, ScalarKind], Ellipsis]

The (column name suffix, scalar kind) pairs the codec encodes into.

encode: collections.abc.Callable[[Any], tuple[Any, Ellipsis]]

Encode a value into one scalar per entry of columns, in order.

decode: collections.abc.Callable[[tuple[Any, Ellipsis]], Any]

Recover the exact value from the tuple produced by encode.

query_suffix: str = ''

Suffix of the column used for querying/indexing (normally the empty suffix).

httk.data.db.codec_for(python_type: Any) → ValueCodec | None

Return the codec for python_type, or None if no codec covers it.

An exact type match wins; otherwise the registered codecs are scanned once in registration order and the first whose python_type is a base class of python_type is returned (deterministic by registration order).

httk.data.db.codec_named(name: str) → ValueCodec

Return the codec registered as name; raise ValueError listing the known names.

httk.data.db.decode_fraction_exact(text: str) → fractions.Fraction

Parse FRACTION_EXACT_FORMAT text back into an exact fractions.Fraction.

httk.data.db.decode_fracvector_exact(text: str, rows: int, cols: int) → httk.core.FracVector

Parse FRACVECTOR_EXACT_FORMAT text into a rows x cols FracVector.

The numerators are laid out row-major into a tensor of shape (rows, cols); their count must equal rows * cols. Raises ValueError on malformed text or a count/shape mismatch.

httk.data.db.decode_surdscalar_exact(text: str) → httk.core.SurdScalar

Parse SURD_EXACT_FORMAT text back into an exact SurdScalar.

httk.data.db.encode_fraction_exact(value: fractions.Fraction) → str

The canonical FRACTION_EXACT_FORMAT text of value (e.g. "-7/3", "1/1").

httk.data.db.encode_fracvector_exact(value: httk.core.FracVector) → str

The canonical FRACVECTOR_EXACT_FORMAT text of a rational tensor.

The tensor is flattened row-major and normalized through to_fractions(): d is the least positive common denominator of the (reduced) elements and the numerators are the elements scaled by d. The text is therefore canonical — independent of the internal denominator the input happened to carry — and lossless at arbitrary precision. The shape itself is not encoded; fixed-shape schema fields carry it in their declaration.

httk.data.db.encode_fracvector_floats(value: httk.core.FracVector) → tuple[float, Ellipsis]

The elements of a rational tensor as a flat row-major tuple of nearest floats.

This is the (documented approximate) companion of encode_fracvector_exact(), used to fill the per-element float query/index columns of fixed-shape fields.

httk.data.db.encode_surdscalar_exact(value: httk.core.SurdScalar) → str

The canonical SURD_EXACT_FORMAT text of value ("0" for zero).

The terms are the canonical radicand map of the surd — squarefree radicands in increasing order, each with its reduced rational coefficient — so the text is unique per value and round-trips exactly.

httk.data.db.known_value_codecs() → list[str]

Return the registered value-codec names, in registration order.

httk.data.db.register_value_codec(codec: ValueCodec) → None

Register codec; raise ValueError on a duplicate name or Python type.

httk.data.db.canonical_form(obj: Any) → str

The deterministic canonical JSON text of a storable instance’s stored values.

Resolves the schema of obj’s class (so the class must be storable) and serializes [table_name, [[field, canonical value], ...]] over the non-derived stored fields, sorted by field name, as compact JSON.

httk.data.db.content_id(obj: Any) → str

The SHA-256 hex digest (64 hex characters) of canonical_form() of obj.

class httk.data.db.ChildTableSpec

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.

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

One scalar column of a table.

name: str

The column name.

kind: httk.data.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).

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

How a stored field maps onto the relational model.

class httk.data.db.FieldSpec

The resolved storage shape of one stored field (or stored property).

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.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.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 was X | None; all columns are then nullable.

exception httk.data.db.SchemaError

Bases: Exception

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

class httk.data.db.TableSchema

The resolved relational schema of one storable class.

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

The deduplication policy applied when instances are saved.

links: tuple[httk.core.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: str) → FieldSpec

Return the FieldSpec named name; raise SchemaError if absent.

referenced_classes() → tuple[type, Ellipsis]

The distinct storable classes this schema references (field order, no duplicates).

httk.data.db.register_schema_override(cls: type, info: httk.core.StorageInfo) → None

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.

httk.data.db.resolve_schema(cls: type, *, override: httk.core.StorageInfo | None = None) → TableSchema

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.

Raises:

SchemaError – If the class is not a frozen dataclass or any field cannot be resolved; the message names the class and field.

httk.data.db.snake_case(name: str) → str

The default table name for a class name: CamelCase to camel_case (acronym-aware).