httk.store.optimade

Public remote OPTIMADE client and query APIs.

The synchronous, read-only OPTIMADE client OptimadeStore and its portable RemoteSearcher / RemoteResultSet query layer for accessing remote (federated) OPTIMADE services.

Submodules

• httk.store.optimade.client
• httk.store.optimade.remote_query

Attributes

ALL_ADVERTISED

Exceptions

OptimadeClientError	Base class for safe, client-side OPTIMADE failures.
OptimadeDiscoveryError	Report a malformed or inconsistent /info discovery document.
OptimadeErrorDocumentError	Report a non-success response with a parseable OPTIMADE error document.
OptimadeHTTPError	Report a non-success HTTP status from a remote endpoint.
OptimadeTransportError	Report that the HTTP client could not complete a request.
OptimadeVersionNegotiationError	Report failure to negotiate a supported OPTIMADE API version.
CountUnavailableError	The client could not obtain an exact filtered result count.
OptimadePaginationError	A remote continuation was unsafe, malformed, or non-terminating.
OptimadeResponseError	A successful HTTP response was not a usable OPTIMADE entry document.

Classes

OptimadeStore	Connect synchronously to a read-only OPTIMADE service and discover it eagerly.
RemoteEntryType	Describe one immutable remote entry endpoint discovered from /info.
ServiceDeviation	One specification deviation the client tolerated for a service.
RemoteResultColumn	Expose one named scalar projection from a lazy result set.
RemoteResultSet	Represent a frozen, lazy, and re-iterable remote result plan.
RemoteSearcher	Build one portable single-root OPTIMADE query.

Package Contents

httk.store.optimade.ALL_ADVERTISED

exception httk.store.optimade.OptimadeClientError

Bases: RuntimeError

Base class for safe, client-side OPTIMADE failures.

exception httk.store.optimade.OptimadeDiscoveryError(source_url, detail)

Bases: OptimadeClientError

Report a malformed or inconsistent /info discovery document.

Parameters:

• source_url (str) – Redacted URL of the malformed document.

• detail (str) – Safe discovery detail.

source_url

detail

exception httk.store.optimade.OptimadeErrorDocumentError(source_url, status_code, detail=None)

Bases: OptimadeHTTPError

Report a non-success response with a parseable OPTIMADE error document.

exception httk.store.optimade.OptimadeHTTPError(source_url, status_code, detail=None)

Bases: OptimadeClientError

Report a non-success HTTP status from a remote endpoint.

Parameters:

• source_url (str) – Redacted URL of the response.

• status_code (int) – HTTP status code returned by the service.

• detail (str | None) – Optional safe error detail.

source_url

status_code

detail = None

class httk.store.optimade.OptimadeStore(base_url, *, client=None, timeout=120.0, page_limit=50, max_pages=10000, allow_cross_origin_pagination=False, response_fields=None, count_by_pagination=False, infer_standard_definitions=True, tolerate_deviations=True)

Connect synchronously to a read-only OPTIMADE service and discover it eagerly.

Unversioned bases negotiate strictly through the preference-ordered /versions CSV. Query pagination validates complete pages before yielding, uses lazy one-root exact-literal requests, and bounds continuation links by page count and origin.

Parameters:

• base_url (str) – Absolute HTTP(S) service base URL.

• client (object | None) – Optional borrowed synchronous HTTP client; when given, its own timeout configuration applies and timeout is ignored.

• timeout (float | None) – Request timeout in seconds for the client this store creates when client is not given (default 120; public providers routinely take several seconds per filtered query). None disables the timeout.

• page_limit (int) – Requested default remote page size; lowered automatically when a service rejects it with HTTP 403.

• max_pages (int) – Maximum continuation pages followed by one query.

• allow_cross_origin_pagination (bool) – Permit continuation links on another origin.

• response_fields (object | None) – Default response-field selection for new searchers.

• count_by_pagination (bool) – Count IDs across all pages when the service omits meta.data_returned.

• infer_standard_definitions (bool) – Complete unprefixed standard property names on standard endpoints from the declared specification version (the info document’s meta.api_version) when the service publishes no $id. This governs discovery, entry-type binding, and typed query fields; set False for strict definition-only auditing, where only declared $id definitions are recognized. It does not affect an entry backend constructed directly over a raw OptimadeResource, which always applies the standard-name rule.

• tolerate_deviations (bool) – Apply specification-anchored fallbacks for known service deviations and record them in deviations; set False to fail strictly, for conformance auditing.

Raises:

• OptimadeVersionNegotiationError – If the service cannot select a supported version.

• OptimadeDiscoveryError – If discovery documents are malformed.

requested_base_url

base_url

page_limit = 50

max_pages = 10000

timeout = 120.0

allow_cross_origin_pagination = False

response_fields = None

count_by_pagination = False

infer_standard_definitions = True

tolerate_deviations = True

api_version: str | None = None

property deviations: tuple[ServiceDeviation, ...]

Specification deviations this client tolerated, in observation order.

property entry_types: tuple[RemoteEntryType, ...]

Discovered entry endpoints in the service-advertised order.

property entry_types_by_name: collections.abc.Mapping[str, RemoteEntryType]

An immutable transport-name lookup for entry_types.

entry_type(name)

Return one discovered endpoint by transport name.

Parameters:

name (str) – Service-advertised endpoint name.

Returns:

Discovered endpoint descriptor.

Raises:

KeyError – If no endpoint has that name.

Return type:

RemoteEntryType

refresh()

Refresh discovery state after a fully successful rediscovery.

Raises:

OptimadeClientError – If the store is closed or discovery fails.

close()

Close an internally owned HTTP client; borrowed clients stay open.

searcher(*, response_fields=..., as_of=None)

Create one synchronous, read-only remote search plan.

Passing response_fields overrides the store-level selection. An omitted value inherits it, while explicit None requests the service default.

Parameters:

• response_fields (object) – Per-search field selection override.

• as_of (object) – Historic cutoff; unsupported because remote snapshot negotiation is unavailable.

Returns:

New remote search plan.

Raises:

• OptimadeClientError – If the store is closed.

• ValueError – If a historic cutoff is requested.

Return type:

httk.store.optimade.remote_query.RemoteSearcher

slicer(target)

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

target is a discovered RemoteEntryType, or its transport endpoint name resolved the same way as entry_type(). Each terminal indexing operation runs its own fresh search against a searcher created with this store’s default response_fields policy. No sorting is offered here – use searcher() directly for a sorted or relationship query.

Parameters:

target (RemoteEntryType | str) – A discovered endpoint descriptor, or its endpoint name.

Returns:

A slicer over the endpoint’s records.

Raises:

KeyError – If target is a name with no discovered endpoint.

Return type:

httk.store.query.slicer.Slicer

exception httk.store.optimade.OptimadeTransportError(source_url, detail)

Bases: OptimadeClientError

Report that the HTTP client could not complete a request.

Parameters:

• source_url (str) – Redacted URL of the failed request.

• detail (str) – Safe transport detail.

source_url

detail

exception httk.store.optimade.OptimadeVersionNegotiationError(source_url, detail)

Bases: OptimadeClientError

Report failure to negotiate a supported OPTIMADE API version.

Parameters:

• source_url (str) – Redacted URL used for negotiation.

• detail (str) – Safe negotiation detail.

source_url

detail

class httk.store.optimade.RemoteEntryType

Describe one immutable remote entry endpoint discovered from /info.

name is solely the service’s transport endpoint name. Semantic recognition is intentionally represented by binding and is derived exclusively from definition IRIs.

Parameters:

• name – Transport endpoint name.

• definition_id – Entry-definition IRI, when advertised.

• schema – Lossless schema snapshot from discovery.

• property_iris – Transport property names keyed by definition IRI.

• property_names – Local property names keyed by definition IRI.

• property_types – Property kinds keyed by transport name.

• advertised_properties – Properties advertised by the service.

• default_response_properties – Properties returned by default.

• sortable_properties – Properties accepted by remote sorting.

• binding – Recognized semantic binding, when available.

• backend – Backend class associated with the binding.

• binding_evidence – Why the binding was selected – "declared" when a links.describedby IRI selected it, "property-ids" when an unambiguous set of declared property definition IRIs did, "standard-name" when the declared specification version’s standard namespace did, and None when the endpoint stays unbound.

• inferred_properties – Sorted transport names whose definition IRI came from standard-name completion rather than a declared $id.

name: str

definition_id: str | None

schema: httk.core.optimade.OptimadeSchemaSnapshot

property_iris: collections.abc.Mapping[str, str]

property_names: collections.abc.Mapping[str, str]

property_types: collections.abc.Mapping[str, tuple[str, str | None]]

advertised_properties: tuple[str, ...]

default_response_properties: tuple[str, ...]

sortable_properties: tuple[str, ...]

binding: httk.core.register.OptimadeEntryBinding | None

backend: type

binding_evidence: str | None

inferred_properties: tuple[str, ...]

class httk.store.optimade.ServiceDeviation

One specification deviation the client tolerated for a service.

Parameters:

• kind – Deviation category – "versions-endpoint", "entry-info-identity", or "continuation-scheme".

• url – Redacted URL the deviation was observed at.

• detail – One factual sentence describing the applied fallback.

kind: str

url: str

detail: str

exception httk.store.optimade.CountUnavailableError

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

The client could not obtain an exact filtered result count.

exception httk.store.optimade.OptimadePaginationError

Bases: OptimadeResponseError

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

exception httk.store.optimade.OptimadeResponseError

Bases: httk.store.optimade.client.OptimadeClientError

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

class httk.store.optimade.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.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]

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