httk.serve.optimade.remote_query

Neutral synchronous query/result protocols over a remote OPTIMADE service.

Exceptions

OptimadeResponseError	A successful HTTP response was not a usable OPTIMADE entry document.
OptimadePaginationError	A remote continuation was unsafe, malformed, or non-terminating.
CountUnavailableError	The service omitted a valid filtered meta.data_returned count.

Classes

RemoteSearcher	Build one portable single-root OPTIMADE query.
RemoteResultColumn	Expose one named scalar projection from a lazy result set.
RemoteResultSet	Represent a frozen, lazy, and re-iterable remote result plan.

Module Contents

exception httk.serve.optimade.remote_query.OptimadeResponseError

Bases: httk.serve.optimade.client.OptimadeClientError

A successful HTTP response was not a usable OPTIMADE entry document.

exception httk.serve.optimade.remote_query.OptimadePaginationError

Bases: OptimadeResponseError

A remote continuation was unsafe, malformed, or non-terminating.

exception httk.serve.optimade.remote_query.CountUnavailableError

Bases: OptimadeResponseError, httk.store.CountUnavailableError

The service omitted a valid filtered meta.data_returned count.

class httk.serve.optimade.remote_query.RemoteSearcher(store, *, response_fields=None)

Build one portable single-root OPTIMADE query.

Parameters:

• store (httk.serve.optimade.client.OptimadeStore) – Remote OPTIMADE store used for discovery and requests.

• response_fields (object) – Optional field-selection policy for this search.

offset = 0

variable(target)

Bind the query to one discovered remote entry type.

Parameters:

target (object) – Discovered entry descriptor or registered backend class.

Returns:

Query variable exposing portable fields.

Raises:

httk.store.query.protocols.UnsupportedQueryError – If the target is not recognized or a root variable is already bound.

Return type:

_RemoteVariable

add(expression)

Add a filter expression to the query.

Parameters:

expression (object) – Expression created by this searcher.

Raises:

• ValueError – If no query variable is bound.

• httk.store.UnsupportedQueryError – If the expression belongs elsewhere.

output(variable, name)

Declare a whole-record or scalar output.

Parameters:

• variable (object) – Root variable or field to project.

• name (str) – Output name.

Raises:

• ValueError – If the name is empty or duplicated.

• httk.store.UnsupportedQueryError – If the output belongs elsewhere.

add_sort(field, descending=False)

Append a sortable field to the remote query.

Parameters:

• field (object) – Field exposed by this searcher’s variable.

• descending (bool) – Sort in descending order when true.

Raises:

httk.store.UnsupportedQueryError – If the field is not portable or sortable.

set_limit(limit)

Set the query result limit.

Parameters:

limit (int) – Nonnegative limit, or a negative value for no bound.

add_offset(offset)

Advance the query offset.

Parameters:

offset (int) – Nonnegative number of matching rows to skip.

count()

Return the filtered remote count.

Returns:

meta.data_returned reported by the service.

Raises:

CountUnavailableError – If the service omits a valid count.

Return type:

int

results(**outputs)

Freeze the query as a lazy, re-iterable result set.

Parameters:

**outputs (object) – Optional output names mapped to this searcher’s projections.

Returns:

Frozen remote result plan.

Raises:

ValueError – If no outputs are declared.

Return type:

RemoteResultSet

class httk.serve.optimade.remote_query.RemoteResultColumn(result, index)

Expose one named scalar projection from a lazy result set.

Parameters:

• result (RemoteResultSet) – Result set owning the projection.

• index (int) – Zero-based projection index.

name

class httk.serve.optimade.remote_query.RemoteResultSet(searcher, outputs=None)

Represent a frozen, lazy, and re-iterable remote result plan.

Parameters:

• searcher (RemoteSearcher) – Search plan to clone.

• outputs (collections.abc.Mapping[str, object] | None) – Optional output names mapped to the searcher’s projections.

names

first()

Return the first result, if present.

Returns:

First row or None.

Return type:

httk.store.ResultRow | None

one()

Return the only result.

Returns:

Sole result row.

Raises:

• httk.store.NoResultError – If no result exists.

• httk.store.MultipleResultsError – If more than one result exists.

Return type:

httk.store.ResultRow

scalars(name=None)

Iterate one named scalar output from each result.

Parameters:

name (str | None) – Output name, or None when exactly one exists.

Returns:

Iterator over scalar values.

Raises:

• KeyError – If the named output is unknown.

• ValueError – If no name is given and multiple outputs exist.

Return type:

collections.abc.Iterator[object]

column(name)

Return a lazy column for a scalar output.

Parameters:

name (str) – Scalar output name.

Returns:

Lazy result column.

Raises:

• KeyError – If the output is unknown.

• TypeError – If the output is a whole-record projection.

Return type:

RemoteResultColumn

abstractmethod cursor()

Reject unsupported cursor access.

Returns:

Never; remote OPTIMADE cursors are unsupported.

Raises:

NotImplementedError – Remote OPTIMADE cursors are unavailable.

Return type:

collections.abc.Iterator[httk.store.ResultRow]