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

Searcher	A single query under construction, and its results once iterated.
SearchExpression	Base class for protocol classes.
SearchField	A queryable field of a search variable.
SearchResult	One match: the declared output values, and the names they were declared under.
SearchVariable	A query variable bound to a target type; attribute access yields fields.
Store	Base class for protocol 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)
simple_property_handlers(→ dict[str, ...)	Build a filter handler table for an entry type from a property-key map.
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.Searcher

Bases: Protocol

A single query under construction, and its results once iterated.

Iteration yields one SearchResult per match, so item[0][0] is the first declared output of the match (typically the matched row object). The expressions received by add are always ones produced by this same backend’s search variables, so implementations may type them as their own expression class; a backend that needs a second (post-filter) evaluation position decides that from the expression itself, not from the caller.

offset: int

variable(target: Any) → Any

output(variable: Any, name: str) → None

add(expression: Any) → None

count() → int

set_limit(limit: int) → None

add_offset(offset: int) → None

add_sort(field: Any, descending: bool) → None

class httk.optimade.backend.SearchExpression

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

class httk.optimade.backend.SearchField

Bases: Protocol

A queryable field of a search variable.

In addition to the methods below, fields support the rich comparison operators (==, !=, <, <=, >, >=), returning SearchExpression. The handlers invoke those via getattr(field, '__eq__')(value) since the comparison dunders cannot be typed as expression-returning.

The three string-matching methods take literal text: no wildcard or pattern syntax whatsoever crosses this contract, so % and _ (and any other metacharacter) match themselves. A backend is therefore free to implement them with SQL LIKE over an escaped pattern, with a regular expression, or with a full-text index — the choice is invisible here.

has_any(*values: Any) → SearchExpression

has_only(*values: Any) → SearchExpression

contains(text: str) → SearchExpression

Match values containing text as a literal substring.

startswith(prefix: str) → SearchExpression

Match values beginning with the literal prefix.

endswith(suffix: str) → SearchExpression

Match values ending with the literal suffix.

class httk.optimade.backend.SearchResult

Bases: NamedTuple

One match: the declared output values, and the names they were declared under.

values holds one entry per Searcher.output() call in declaration order; it is a tuple, so values, names = result and result[0][0] both work.

values: tuple[Any, Ellipsis]

names: tuple[str, Ellipsis]

class httk.optimade.backend.SearchVariable

Bases: Protocol

A query variable bound to a target type; attribute access yields fields.

always_true/always_false are reserved names: they are real methods of the variable, never stored fields resolved through __getattr__. They exist so a translation layer can express a constant truth value without inventing a probe field. A field == field probe is NULL-unsound, since it yields NULL (not true) for a NULL field.

always_true() → SearchExpression

An expression that matches every row.

always_false() → SearchExpression

An expression that matches no row.

class httk.optimade.backend.Store

Bases: Protocol

Base class for protocol classes.

Protocol classes are defined as:

class Proto(Protocol):
    def meth(self) -> int:
        ...

Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).

For example:

class C:
    def meth(self) -> int:
        return 0

def func(x: Proto) -> int:
    return x.meth()

func(C())  # Passes static type check

See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:

class GenProto[T](Protocol):
    def meth(self) -> T:
        ...

searcher() → Searcher

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

httk.optimade.backend.simple_property_handlers(entry_type: str, property_keys: collections.abc.Mapping[str, str], property_fulltypes: collections.abc.Mapping[str, str]) → dict[str, collections.abc.Mapping[str, collections.abc.Callable[Ellipsis, Any]]]

Build a filter handler table for an entry type from a property-key map.

Always provides the standard id (matched against the __id field) and type (a constant equal to entry_type) handlers. For every property named in property_keys (which maps property names to backend field names), handlers are generated from the property’s fulltype in property_fulltypes (default "string"): string properties get comparison and stringmatching handlers; integer and float properties get a numeric comparison handler; list of ... properties get a HAS (set membership) handler. Every generated property also gets a known unknown handler.

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.