httk.serve.optimade.remote_query

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

Attribute access on a bound query variable (variable.some_field) resolves against the endpoint’s declared field map, including OPTIMADE provider-prefixed properties such as variable._anyterial_max_spin_splitting – on a generic, unregistered entry type the local field names are the wire names verbatim, and provider prefixes are the norm there. A double-leading-underscore name (a dunder, e.g. __deepcopy__) is always rejected with a bare AttributeError before the field map is even consulted, so interpreter and library introspection stay cheap and can never collide with a field name. A single-leading-underscore name that is not a declared field also raises a bare AttributeError rather than the descriptive UnsupportedQueryError used for other unknown names: this keeps probes shaped like a provider field but not one, such as IPython’s _ipython_canary_method_should_not_exist_, indistinguishable from “no such attribute” instead of surfacing as a backend failure.

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, scalar, or set-valued relationship output.

A relationship namespace (variable.links.<name>) is a set-valued output: it yields a tuple of bound related records per row, resolved from the response’s included array or one lazy fetch per missing identifier – the same resolution a returned record’s own .links.<name> performs. Served-entry-type relationship names are also added to the request’s include= parameter automatically.

Parameters:

• variable (object) – Root variable, portable scalar field, or relationship namespace 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

slicer(target)

A pandas-style [] indexing view over one discovered entry endpoint.

Each terminal indexing operation runs against a fresh searcher minted with this searcher’s response_fields policy, so slicer operations never share filter state. No sorting is offered here – use searcher() and add_sort() directly for a sorted or relationship query.

Parameters:

target (httk.serve.optimade.client.RemoteEntryType) – The discovered remote entry endpoint to index.

Returns:

A slicer over target.

Return type:

httk.store.query.slicer.Slicer

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]