httk.store.db.entry_provider

Serve stored dataclasses through the httk-core entry-provider contract.

StoreEntryProvider bridges the SQL storage layer to the neutral EntryProvider contract: it serves the rows of one or more storable classes in a SqlStore as described, JSON-able entry-type records, so a serving module (such as httk-serve) can expose a database as an OPTIMADE API without either side depending on the other.

For each served class the provider either passes through a supplied EntryTypeDefinition (validated to describe every served property) or auto-generates one from the class’s resolved TableSchema: the OPTIMADE core id/type properties plus one from_simple() definition per servable stored field, each named with a registered database-specific prefix (default "_httk_") and merged in via extended() — the same construction route the other httk entry providers use.

The schema-to-OPTIMADE type mapping is:

  • str/int/bool/float fields — string/integer/ boolean/float;

  • rational fields (fractions.Fraction, FracScalar, SurdScalar) — float, served as the nearest float (stored values themselves remain exact; only the served value is approximate);

  • datetime.datetime fields — timestamp, served as ISO-8601 text;

  • fixed-shape (Shape(r, c)) and variable-rows (Shape(0, c)) FracVector fields — list of list of float (the fixed shape also declares its dimension sizes);

  • list/tuple fields of scalars or of the codec types above — list of the mapped element type.

Not every stored field can be served as a property: bytes fields (and fields encoded by a custom, non-built-in value codec) have no OPTIMADE value representation and are skipped, while reference fields and child fields of storable elements surface through StoreEntryProvider.relationships() instead — when their target class is itself served, each record declares its related entries as a flat tuple of RelatedEntry values, carrying the role/description metadata of an optional Related field marker (Related(serve=False) suppresses the field as a relationship).

Classes

StoreEntryProvider

Serves the stored rows of storable classes as httk-core entry types.

Functions

served_specs(schema, prefix)

Return the served (name, field spec, fulltype) triples.

auto_definition(entry_type, schema, prefix)

Auto-generate the EntryTypeDefinition of a storable class.

Module Contents

httk.store.db.entry_provider.served_specs(schema, prefix)[source]

Return the served (name, field spec, fulltype) triples.

Parameters:
Returns:

One triple for every schema field with an OPTIMADE value type.

Return type:

list[tuple[str, httk.store.db.schema.FieldSpec, str]]

httk.store.db.entry_provider.auto_definition(entry_type, schema, prefix)[source]

Auto-generate the EntryTypeDefinition of a storable class.

The definition carries the OPTIMADE core id/type properties plus one from_simple() definition per triple of served_specs(), named in the custom_ sub-namespace of prefix so generated names cannot collide with curated prefixed definitions, merged in via extended() (so prefix must be a registered definition prefix).

Parameters:

  • entry_type (str) – The entry type name to define.

  • schema (httk.store.db.schema.TableSchema) – The resolved schema of the stored class.

  • prefix (str) – The registered prefix used for generated property names.

Returns:

The generated entry-type definition.

Return type:

httk.core.EntryTypeDefinition

class httk.store.db.entry_provider.StoreEntryProvider(store, classes, *, definitions=None, prefix='_httk_', id_of=None, link_classes=())[source]

Bases: httk.core.EntryProvider

Serves the stored rows of storable classes as httk-core entry types.

classes maps each served entry-type name to its storable dataclass; the classes’ tables are read through store. definitions optionally supplies the EntryTypeDefinition of an entry type (validated: it must describe every property the provider serves for it); entry types without a supplied definition get one auto-generated from the class’s schema, with every schema-derived property name carrying prefix (which must be registered, see register_definition_prefix()). id_of maps (entry_type, sid, instance) to the served entry id; the default is "<entry_type>-<sid>". link_classes supplies additional storable classes for link metadata validation.

See the module docstring for which stored fields are served as properties (and how their types map), which are skipped, and which surface through relationships() instead.

Parameters:
entry_types()[source]

Return the definitions of all served entry types.

Returns:

The served entry-type definitions keyed by entry type.

Return type:

collections.abc.Mapping[str, httk.core.EntryTypeDefinition]

property_keys(entry_type)[source]

Return the served property-to-storage-key mapping for an entry type.

Parameters:

entry_type (str) – The served entry type to inspect.

Returns:

The public property names and their storage keys.

Raises:

KeyError – If entry_type is not served.

Return type:

collections.abc.Mapping[str, str]

records(entry_type)[source]

Yield JSON-able records for a served entry type.

Parameters:

entry_type (str) – The served entry type whose records are read.

Yield:

A served record.

Raises:

KeyError – If entry_type is not served.

relationships(entry_type)[source]

Return relationships grouped by source entry id.

Relationships come from stored reference fields and child fields targeting served storable classes; loose-edge projections are not part of this provider contract.

Parameters:

entry_type (str) – The served entry type whose relationships are read.

Returns:

Related entries keyed by source entry id.

Raises:

KeyError – If entry_type is not served.

Return type:

collections.abc.Mapping[str, tuple[httk.core.RelatedEntry, Ellipsis]]