httk.store.db

The SQL storage layer of httk-store: 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.store.db.schema — resolve_schema() reads a storable class into a TableSchema, the single source of truth for DDL, inserts, selects, and reconstruction;

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

• httk.core.storage — 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-store[db] extra (sqlalchemy):

• Database — the engine wrapper naming where data lives (Database.sqlite(...), Database.duckdb(...), or the Keeper-backed Database.clickhouse(...));

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

• SqlSearcher (from searcher()) — the query DSL implementing the httk.store.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-serve);

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

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

Submodules

• httk.store.db.bulk
• httk.store.db.bulk_deferred
• httk.store.db.bulk_parallel
• httk.store.db.clickhouse
• httk.store.db.codecs
• httk.store.db.engine
• httk.store.db.entry_provider
• httk.store.db.fsck
• httk.store.db.graph
• httk.store.db.layout
• httk.store.db.mapping
• httk.store.db.optimade
• httk.store.db.paging
• httk.store.db.results
• httk.store.db.rows
• httk.store.db.schema
• httk.store.db.searcher
• httk.store.db.store
• httk.store.db.stored_federation
• httk.store.db.stored_properties

Exceptions

MultipleResultsError	Report that a result-set one() operation found multiple results.
NoResultError	Report that a result-set one() operation found no matching result.
SchemaError	A class or field cannot be resolved into a storage schema; the message names both.

Classes

ResultRow	Represent one named result row by position, name, or attribute.
ValueCodec	An exact encoding of one Python value type across one or more scalar columns.

Functions

register_value_codec(codec)	Register codec in the value-codec registry.
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.

Package Contents

exception httk.store.db.MultipleResultsError

Bases: LookupError

Report that a result-set one() operation found multiple results.

exception httk.store.db.NoResultError

Bases: LookupError

Report that a result-set one() operation found no matching result.

class httk.store.db.ResultRow(values, names, resolver=None, guard=None)

Represent one named result row by position, name, or attribute.

Parameters:

• values (tuple[Any, Ellipsis]) – The row values in declaration order.

• names (tuple[str, Ellipsis]) – The corresponding output names.

• resolver (Any) – An optional lazy value resolver.

• guard (Any) – An optional callback that rejects access to expired values.

property names: tuple[str, Ellipsis]

Return the declared output names.

property values: tuple[Any, Ellipsis]

Return the row values in declaration order.

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

Parameters:

• name – The registry name of the codec.

• python_type – The Python type stored by the codec.

• columns – The column suffix and scalar-kind pairs encoded by the codec.

• encode – The function that encodes a value into column values.

• decode – The function that reconstructs a value from column values.

• query_suffix – The suffix of the query and index column.

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, httk.store.db.codecs.ScalarKind], ...]

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.store.db.register_value_codec(codec)

Register codec in the value-codec registry.

Parameters:

codec (ValueCodec) – The codec to register.

Returns:

None.

Raises:

ValueError – If the codec name or Python type is already registered.

Return type:

None

exception httk.store.db.SchemaError

Bases: Exception

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

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