httk.store.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 client could not obtain an exact filtered result 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.store.optimade.remote_query.OptimadeResponseError¶

Bases: httk.store.optimade.client.OptimadeClientError

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

exception httk.store.optimade.remote_query.OptimadePaginationError¶

Bases: OptimadeResponseError

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

exception httk.store.optimade.remote_query.CountUnavailableError¶

Bases: OptimadeResponseError, httk.store.query.protocols.CountUnavailableError

The client could not obtain an exact filtered result count.

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

Build one portable single-root OPTIMADE query.

Parameters:

store (httk.store.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.

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.

A valid optional meta.data_returned is the fast path. If it is absent or null, counting raises unless the store enables ID pagination explicitly.

Returns:: Exact number of filtered remote results.
Raises:: CountUnavailableError – If no valid count is reported and ID pagination is disabled.
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.store.optimade.client.RemoteEntryType) – The discovered remote entry endpoint to index.
Returns:: A slicer over target.
Return type:: httk.store.query.slicer.Slicer

class httk.store.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.store.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.query.protocols.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.query.protocols.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.query.protocols.ResultRow]