httk.optimade.backend.protocols

Typed protocols for the store/searcher contract the OPTIMADE backend uses.

The store/searcher protocols are defined in httk.data.query (httk-data is where httk’s data stores live, and this backend programs against their shared query contract); this module re-exports them for the backend’s use, together with the OPTIMADE-specific query-callable types from the result model.

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.
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.

Module Contents

class httk.optimade.backend.protocols.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.protocols.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.protocols.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.protocols.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.protocols.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.protocols.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.protocols.QueryFunction

Bases: Protocol

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

class httk.optimade.backend.protocols.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