httk.optimade.backend

Submodules

• httk.optimade.backend.adapter
• httk.optimade.backend.execution
• httk.optimade.backend.handlers
• httk.optimade.backend.memory_store
• httk.optimade.backend.partial
• httk.optimade.backend.protocols
• httk.optimade.backend.providers
• httk.optimade.backend.translation

Classes

BackendAdapter	Binds a store to the OPTIMADE entry endpoints it serves.
EntrySource	One queryable source (table/type) behind an OPTIMADE entry endpoint.
StoreResults	Results of a query over one or more searchers.
InMemoryStore	A store over dict rows: InMemoryStore({'structures': [ {...}, ... ]}).
PartialDimension	One list axis of a PartialValue.
PartialValue	A property value provided lazily, one slice at a time.
QueryFunction	The callback seam through which the request engine runs queries on a backend.
QueryResults	The results of a query against a backend, as consumed by the entry endpoints.

Functions

execute_query(→ StoreResults)
adapter_from_providers(...)	Build a BackendAdapter serving the given entry providers.
providers_from_registry(→ dict[str, ...)	Return the registered entry-provider factories keyed by their registered name.
translate_filter(...)	Build one searcher per entry source, with the filter applied to each.
translate_filter_node() → httk.data.query.SearchExpression)	Translate one filter node against an OPTIMADE entry-info property mapping.

Package Contents

class httk.optimade.backend.BackendAdapter

Binds a store to the OPTIMADE entry endpoints it serves.

sources maps entry endpoint names (e.g. 'structures') to the sources queried for that endpoint; an endpoint with several sources (e.g. several calculation result types) is queried across all of them.

schema is required: it declares the served entry types and properties. field_handlers maps each entry type to its filter-handler table. When omitted (left empty) it is derived from schema via simple_property_handlers(), using an identity property-key map (each property is filtered against a backend field of the same name); a backend whose field names differ, or that wants finer control, supplies its own tables instead.

store: httk.data.query.Store

sources: collections.abc.Mapping[str, collections.abc.Sequence[EntrySource]]

schema: httk.optimade.schema.served.ServedSchema

field_handlers: collections.abc.Mapping[str, httk.data.optimade_query.HandlerTable]

query_function() → httk.optimade.model.results.QueryFunction

class httk.optimade.backend.EntrySource

One queryable source (table/type) behind an OPTIMADE entry endpoint.

target is what gets passed to searcher.variable(); fields maps OPTIMADE response-field names to extractors applied to matched row objects. relationships, when set, is an extractor mapping a matched row to a dictionary keyed by related entry type, each value a list of {'id': str, 'description': str?, 'role': str?} dictionaries. sort_keys maps response-field names to the backend field names to sort on. property_metadata maps response-field names to extractors returning the per-property metadata dictionary for a matched row (or None when there is no metadata for that row).

target: Any

fields: collections.abc.Mapping[str, FieldExtractor]

sort_keys: collections.abc.Mapping[str, str]

relationships: FieldExtractor | None = None

property_metadata: collections.abc.Mapping[str, FieldExtractor]

class httk.optimade.backend.StoreResults(pairs: list[tuple[httk.optimade.backend.adapter.EntrySource, httk.data.query.Searcher]], response_fields: list[str], unknown_response_fields: list[str], limit: int | None, offset: int, recognized_prefixes: tuple[str, Ellipsis])

Results of a query over one or more searchers.

Implements the QueryResults protocol. Iteration yields one ResultRow per entry, whose values map response-field names to values extracted from the matched row objects.

pairs

recognized_prefixes

cur: collections.abc.Iterator[tuple[httk.optimade.backend.adapter.EntrySource, Any]] | None

limit

response_fields

unknown_response_fields

offset

more_data_available = True

count() → int

httk.optimade.backend.execute_query(adapter: httk.optimade.backend.adapter.BackendAdapter, entries: list[str], response_fields: list[str], unknown_response_fields: list[str], response_limit: int | None, response_offset: int | None, filter_ast: httk.core.FilterAst | None = None, *, sort: collections.abc.Sequence[tuple[str, bool]] | None = None, debug: bool = False) → StoreResults

class httk.optimade.backend.InMemoryStore(tables: dict[str, list[Row]])

A store over dict rows: InMemoryStore({'structures': [ {...}, ... ]}).

tables

searcher() → MemorySearcher

class httk.optimade.backend.PartialDimension

One list axis of a PartialValue.

length is the number of items along the axis (None when unknown or entry-dependent and not declared). sliceable indicates whether the server can honour a slice request for this axis.

name: str

length: int | None = None

sliceable: bool = False

class httk.optimade.backend.PartialValue

A property value provided lazily, one slice at a time.

fetch takes a tuple of Python slices (one per dimension, with the usual exclusive stop) and returns the corresponding nested lists.

dimensions: tuple[PartialDimension, Ellipsis]

fetch: collections.abc.Callable[[tuple[slice, Ellipsis]], Any]

class httk.optimade.backend.QueryFunction

Bases: Protocol

The callback seam through which the request engine runs queries on a backend.

class httk.optimade.backend.QueryResults

Bases: Protocol

The results of a query against a backend, as consumed by the entry endpoints.

Iteration yields one ResultRow per entry; its values map OPTIMADE response-field names to values, and the id and type keys are always present.

more_data_available: bool

count() → int

httk.optimade.backend.adapter_from_providers(providers: collections.abc.Iterable[httk.core.EntryProvider], **options: Any) → httk.optimade.backend.adapter.BackendAdapter

Build a BackendAdapter serving the given entry providers.

Every provider’s entry_types() become served entry types (described by their EntryTypeDefinition), its property_keys() name the served subset and drive both the filter handlers (via simple_property_handlers()) and the response-field extractors, and its records() are loaded into an InMemoryStore. Every served property MUST be described by the entry type’s definition (a custom property must therefore live in an extended() definition); a ValueError names any offender. All served properties beyond id/type are marked default-response. Extra keyword options (e.g. sortable, recognized_prefixes) are forwarded to build_served_schema(); every served property is sortable-capable, since the provider’s property-key map is passed through as the source’s sort_keys.

Declared relationships (relationships()) are fully auto-wired for serving and filtering: for each entry type with declared relationships, a synthetic __rel_<related_type> id-list field is materialized on EVERY row of that entry type (an empty list when the row has no related entries of that type, so inverse set semantics are well-defined), and a '<related_type>.id' entry built with relationship_id_handler() is merged into the entry type’s derived filter-handler table (never overwriting an entry already present, mirroring how BackendAdapter respects explicitly supplied handler tables). <related_type>.id HAS ... filters — and, through the related-property resolver of translate_filter(), depth-1 relationship-property filters such as references.doi CONTAINS "10.1" — therefore work without any hand-wiring.

httk.optimade.backend.providers_from_registry() → dict[str, collections.abc.Callable[Ellipsis, httk.core.EntryProvider]]

Return the registered entry-provider factories keyed by their registered name.

Resolves each factory registered via httk.core.register_entry_provider() (through httk.handlers.* self-registration) into a callable. Providers need data, so applications instantiate them: providers_from_registry()["atomistic-structures"](data).

httk.optimade.backend.translate_filter(filter_ast: httk.core.FilterAst | None, entries: list[str], adapter: httk.optimade.backend.adapter.BackendAdapter, sort: collections.abc.Sequence[tuple[str, bool]] | None = None) → list[tuple[httk.optimade.backend.adapter.EntrySource, httk.data.query.Searcher]]

Build one searcher per entry source, with the filter applied to each.

Relationship-property filters (dotted identifiers over served entry types) are resolved through the adapter’s related-property resolver (built by _related_property_resolver), so filtering references.doi behaves exactly like filtering /references directly.

httk.optimade.backend.translate_filter_node(node: httk.core.FilterAst, search_variable: httk.data.query.SearchVariable, entry: str, entry_info: collections.abc.Mapping[str, Any], handlers: httk.data.optimade_query.HandlerTable, recognized_prefixes: tuple[str, Ellipsis], served_entries: tuple[str, Ellipsis] = ()) → httk.data.query.SearchExpression

Translate one filter node against an OPTIMADE entry-info property mapping.

An OPTIMADE-side adaptation of translate_filter_ast(): entry_info maps property names to their property dictionaries (only their 'fulltype' keys are read) rather than straight to fulltypes, served_entries names the relationship targets, and failures surface as TranslatorError instead of the upstream neutral FilterTranslationError.

No related-property resolver is threaded through, so relationship-property filters other than <type>.id HAS ... raise a not-implemented (501) error. Use translate_filter() (which builds the resolver from its adapter) for full relationship-property filtering.