httk.store.entry_providers

Serve standard entry types through in-memory EntryProvider implementations.

These providers map {id: record} mappings of the stdlib-only record models defined in httk-core (Reference, File, Calculation) onto the neutral httk-core entry-provider contract, so a serving module (such as httk-serve) can expose them as OPTIMADE references/files/calculations endpoints without either side depending on the other. Each provider describes its entry type with the vendored OPTIMADE standard definition loaded from httk-core via standard_entry_type().

The record models live in httk-core (contracts and models); these providers live in httk-store (the capability layer built on those models), together with property-definition validation. The database storage layer in httk.store.backend.sql complements them with a database-backed provider (StoreEntryProvider) serving stored dataclasses the same way.

Classes

StandardEntryProvider

Serve one standard entry type through the neutral provider contract.

ReferenceEntryProvider

Serves OPTIMADE references from a mapping of id to Reference.

FileEntryProvider

Serves OPTIMADE files from a mapping of id to File.

CalculationEntryProvider

Serves OPTIMADE calculations from a mapping of id to Calculation.

RunEntryProvider

Serve core Run records and their provenance edges.

DataRecordEntryProvider

Serve core DataRecord values as provider properties.

Functions

wire_relationship_key(internal_name, definition_id)

Return the wire (prefixed) relationship key for an internal marker name.

strong_link_markers(record_type)

Return a record class's StrongLink markers by field.

product_relationships(links)

Build source-side relationships for a provider's relationships= argument.

Module Contents

class httk.store.entry_providers.StandardEntryProvider(entries, *, record_type, entry_type, relationships)

Bases: httk.core.EntryProvider

Serve one standard entry type through the neutral provider contract.

Parameters:
entry_types()

Return the one standard entry-type definition served by this provider.

Returns:

The served entry-type definition.

Return type:

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

property_keys(entry_type)

Return served property names mapped to record attribute names.

Parameters:

entry_type (str) – The entry type to inspect.

Returns:

The served-property to record-key mapping.

Raises:

KeyError – If entry_type is not this provider’s entry type.

Return type:

collections.abc.Mapping[str, str]

records(entry_type)

Return JSON-compatible records for the requested entry type.

Parameters:

entry_type (str) – The entry type to enumerate.

Returns:

The provider’s records in mapping iteration order.

Raises:

KeyError – If entry_type is not this provider’s entry type.

Return type:

collections.abc.Iterable[collections.abc.Mapping[str, Any]]

relationships(entry_type)

Return related entries keyed by served identifier.

Parameters:

entry_type (str) – The entry type to inspect.

Returns:

The normalized relationship mapping.

Raises:

KeyError – If entry_type is not this provider’s entry type.

Return type:

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

class httk.store.entry_providers.ReferenceEntryProvider(entries, *, relationships=None)

Bases: StandardEntryProvider

Serves OPTIMADE references from a mapping of id to Reference.

relationships optionally maps a reference id to its related entries (RelatedEntry values, served flat per id).

Parameters:
class httk.store.entry_providers.FileEntryProvider(entries, *, relationships=None)

Bases: StandardEntryProvider

Serves OPTIMADE files from a mapping of id to File.

relationships optionally maps a file id to its related entries (RelatedEntry values, served flat per id) — e.g. the calculations a file is input/output of.

Parameters:
class httk.store.entry_providers.CalculationEntryProvider(entries, *, relationships=None)

Bases: StandardEntryProvider

Serves OPTIMADE calculations from a mapping of id to Calculation.

relationships optionally maps a calculation id to its related entries (RelatedEntry values, served flat per id) — e.g. its input/output files, expressed via the role metadata.

Parameters:
httk.store.entry_providers.wire_relationship_key(internal_name, definition_id)

Return the wire (prefixed) relationship key for an internal marker name.

The single serving-edge transform from an internal StrongLink marker name to its served OPTIMADE relationship key. It applies the declaring family’s definition prefix — the exact registry source EntryTypeDefinition.served_form uses — so an internal name such as has_input becomes _httk_has_input. A definition_id of None (or one under no registered prefix) leaves the name bare, and an already-prefixed name is never re-prefixed.

Parameters:

  • internal_name (str) – The internal (unprefixed) marker relationship name.

  • definition_id (str | None) – The declaring family’s definition IRI, whose registered prefix is applied, or None.

Returns:

The served (wire) relationship key.

Return type:

str

Return a record class’s StrongLink markers by field.

Parameters:

record_type (type[Any]) – The storable record class to inspect.

Returns:

The strong-link markers keyed by field name, in dataclass field order.

Return type:

dict[str, httk.core.storage.StrongLink]

class httk.store.entry_providers.RunEntryProvider(entries)

Bases: httk.core.EntryProvider

Serve core Run records and their provenance edges.

Parameters:

entries (collections.abc.Mapping[str, httk.core.Run | collections.abc.Mapping[str, Any]]) – The runs keyed by their served identifiers.

entry_types()

Return the served _httk_runs entry definition.

The wire naming is the served form of the internal runs definition (see EntryTypeDefinition.served_form()).

Returns:

The served run entry-type definition.

Return type:

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

property_keys(entry_type)

Return the served run-property to record-key mapping.

Parameters:

entry_type (str) – The entry type to inspect.

Returns:

The served-property to record-key mapping.

Raises:

KeyError – If entry_type is not _httk_runs.

Return type:

collections.abc.Mapping[str, str]

records(entry_type)

Return JSON-compatible run records.

Parameters:

entry_type (str) – The entry type to enumerate.

Yield:

Run records in input mapping order.

Raises:

KeyError – If entry_type is not _httk_runs.

relationships(entry_type)

Return run provenance edges as forward semantic relationships.

Each edge is grouped under its owning field’s StrongLink forward relationship key in wire form (e.g. _httk_has_input, read from the markers on Run, not hardcoded). Run edges carry internal entry-type names; this serving edge translates each target type to its served (wire) name (via EntryTypeDefinition.served_form()), so a target such as records is served as _httk_records while standard type names pass through unchanged.

Parameters:

entry_type (str) – The entry type to inspect.

Returns:

Relationships grouped by run identifier.

Raises:

KeyError – If entry_type is not _httk_runs.

Return type:

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

reverse_relationships()

Return the derived reverse view of the runs’ provenance edges.

Each run edge (entry_type, entry_id) yields a reverse related entry attached to the targeted entry: keyed by the target’s served (wire) entry type and its raw id, the related entry names this run under the edge field’s StrongLink reverse relationship key in wire form (e.g. _httk_is_input). Fields whose marker declares no reverse key contribute nothing.

Returns:

Related runs keyed by target entry type and then target entry id.

Return type:

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

class httk.store.entry_providers.DataRecordEntryProvider(entries, *, definitions=None, relationships=None)

Bases: httk.core.EntryProvider

Serve core DataRecord values as provider properties.

Definitions are resolved eagerly at construction. Every served property name must start with _; absent record properties are emitted as JSON null.

Parameters:
Raises:

ValueError – If a property name, definition, or non-nullable property is inconsistent with the supplied records.

entry_types()

Return the resolved _httk_records entry definition.

Returns:

The served data-record entry-type definition.

Return type:

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

property_keys(entry_type)

Return served property names mapped to data-record keys.

Parameters:

entry_type (str) – The entry type to inspect.

Returns:

The served-property to record-key mapping.

Raises:

KeyError – If entry_type is not _httk_records.

Return type:

collections.abc.Mapping[str, str]

records(entry_type)

Return records with union-null values for unserved properties.

Parameters:

entry_type (str) – The entry type to enumerate.

Yield:

JSON-compatible records in input mapping order.

Raises:

KeyError – If entry_type is not _httk_records.

relationships(entry_type)

Return normalized data-record relationships by identifier.

Parameters:

entry_type (str) – The entry type to inspect.

Returns:

The relationship mapping supplied at construction.

Raises:

KeyError – If entry_type is not _httk_records.

Return type:

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

httk.store.entry_providers.product_relationships(links)

Build source-side relationships for a provider’s relationships= argument.

Feed the inner mapping into the source-side provider’s relationships= argument; per-edge workflow_declaration_uri is deliberately not served yet (relation-object serving is future work).

Parameters:

links (collections.abc.Iterable[httk.core.ProductLink]) – The product links to group by source type and identifier.

Returns:

Source-type mappings of source identifiers to related product entries.

Raises:

ValueError – If one source has duplicate product labels.

Return type:

dict[str, dict[str, tuple[httk.core.RelatedEntry, Ellipsis]]]