httk.core.entry_provider

The neutral entry-provider contract shared across httk₂ modules.

An EntryProvider supplies queryable entry types — named collections of records with described properties — to consumers that expose them, for example an OPTIMADE server. The contract is deliberately domain-neutral: nothing here is specific to materials science (or to OPTIMADE). A materials module such as httk.atomistic implements a provider that serves its structures from this contract, and a serving module such as httk.optimade consumes any provider without depending on the domain module.

Classes

RelatedEntry	One related entry of a record, as reported by EntryProvider.relationships().
EntryProvider	Supplies described, queryable entry types as plain JSON-able records.

Module Contents

class httk.core.entry_provider.RelatedEntry

One related entry of a record, as reported by EntryProvider.relationships().

Mirrors the OPTIMADE v1.3 relationships model: a related entry is named by its entry type and id, optionally carrying the per-identifier metadata the standard defines — description (the human-readable relationship description introduced in OPTIMADE v1.2 as meta.description) and role (the machine-readable relationship role introduced in OPTIMADE v1.3 as meta.role, e.g. "input"/"output" for the calculations↔files relationship). An absent role means exactly that — no role is declared and no default is assumed.

entry_type: str

The entry type of the related entry (e.g. "references").

id: str

The id of the related entry.

description: str | None = None

A human-readable description of the relationship, if declared.

role: str | None = None

The machine-readable role of the relationship, if declared.

class httk.core.entry_provider.EntryProvider

Bases: abc.ABC

Supplies described, queryable entry types as plain JSON-able records.

A provider serves one or more entry types, each identified by a name (e.g. "structures"). For every entry type it describes the entry type and its properties, states how each served property maps to a record key, and yields the records themselves.

Three notions define the contract:

• Definitions (entry_types()) are first-class EntryTypeDefinition objects — the OPTIMADE property-definition model shared across httk₂ modules. A provider obtains them from the vendored standards (via standard_entry_type() or load_entry_type_definition()) or builds them from from_optimade() and from_simple(). A standard definition typically describes more properties than a provider serves; the served subset is exactly the property names in property_keys().

• Property keys (property_keys()) map each served property name to the key under which that property’s value is found in a record. Every entry type’s property-key map MUST cover at least id and type, and every served name MUST be described by the entry type’s definition (custom properties must therefore live in an extended() definition).

• Records (records()) are plain JSON-able mappings keyed by the record keys named in property_keys() (values are strings, numbers, booleans, None, or nested lists/dicts of the same).

A consumer combines the three: the definitions become the served schema, the property keys drive both response-field extraction and filter handling, and the records are loaded into a store the consumer queries.

A provider may additionally declare relationships (relationships()): a flat tuple of RelatedEntry values per entry id, each naming a related entry (and optionally the relationship’s description/role metadata) that the consumer serves as the entry’s relationships block.

abstractmethod entry_types() → collections.abc.Mapping[str, httk.core.property_definitions.EntryTypeDefinition]

Return the served entry types keyed by name.

Each value is an EntryTypeDefinition describing the entry type and its properties. The subset a provider actually serves is named by property_keys(); a definition may describe more properties than are served.

abstractmethod property_keys(entry_type: str) → collections.abc.Mapping[str, str]

Return the served-property-name to record-key map for entry_type.

The mapping MUST include entries for at least id and type. Every key names a property described by entry_types(); every value names the key under which that property’s value is found in a record from records().

abstractmethod records(entry_type: str) → collections.abc.Iterable[collections.abc.Mapping[str, Any]]

Yield the records for entry_type as plain JSON-able mappings.

Each record is a mapping keyed by the record keys named in property_keys(); values are JSON-able (strings, numbers, booleans, None, or nested lists/dicts of the same).

relationships(entry_type: str) → collections.abc.Mapping[str, tuple[RelatedEntry, Ellipsis]]

Return the related entries for each record of entry_type.

The result maps an entry id to a flat tuple of RelatedEntry values, e.g. {"struct-1": (RelatedEntry("references", "ref-1"), RelatedEntry("references", "ref-2", description="Cites the method"))}. Grouping the related entries by related entry type is the serving layer’s concern (JSON:API groups them at render time). This is the neutral source of an OPTIMADE relationships block: a consumer turns each related entry into a resource identifier under its entry type (carrying the description/role metadata when present), and an include=<type> request then embeds those related resources. The default implementation returns an empty mapping (no relationships); a provider overrides it to declare them. Ids referring to records this provider (or a sibling provider serving the related type) does not supply are simply not resolvable by the consumer.