httk.serve.optimade.client¶

Synchronous, read-only discovery for remote OPTIMADE services.

This module establishes lossless schema snapshots and strict definition-IRI recognition. Query construction and paginated execution live in remote_query and are imported lazily by OptimadeStore.searcher().

Attributes¶

ALL_ADVERTISED

Exceptions¶

`OptimadeClientError`	Base class for safe, client-side OPTIMADE failures.
`OptimadeTransportError`	Report that the HTTP client could not complete a request.
`OptimadeHTTPError`	Report a non-success HTTP status from a remote endpoint.
`OptimadeErrorDocumentError`	Report a non-success response with a parseable OPTIMADE error document.
`OptimadeDiscoveryError`	Report a malformed or inconsistent `/info` discovery document.
`OptimadeVersionNegotiationError`	Report failure to negotiate a supported OPTIMADE API version.

Classes¶

`RemoteEntryType`	Describe one immutable remote entry endpoint discovered from `/info`.
`OptimadeStore`	Connect synchronously to a read-only OPTIMADE service and discover it eagerly.

Module Contents¶

httk.serve.optimade.client.ALL_ADVERTISED[source]¶

exception httk.serve.optimade.client.OptimadeClientError[source]¶

Bases: RuntimeError

Base class for safe, client-side OPTIMADE failures.

exception httk.serve.optimade.client.OptimadeTransportError(source_url, detail)[source]¶

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[source]¶

detail[source]¶

exception httk.serve.optimade.client.OptimadeHTTPError(source_url, status_code, detail=None)[source]¶

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[source]¶

status_code[source]¶

detail = None[source]¶

exception httk.serve.optimade.client.OptimadeErrorDocumentError(source_url, status_code, detail=None)[source]¶

Bases: OptimadeHTTPError

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

exception httk.serve.optimade.client.OptimadeDiscoveryError(source_url, detail)[source]¶

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[source]¶

detail[source]¶

exception httk.serve.optimade.client.OptimadeVersionNegotiationError(source_url, detail)[source]¶

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[source]¶

detail[source]¶

class httk.serve.optimade.client.RemoteEntryType[source]¶

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.

name: str[source]¶

definition_id: str | None[source]¶

schema: httk.core.optimade.OptimadeSchemaSnapshot[source]¶

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

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

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

advertised_properties: tuple[str, Ellipsis][source]¶

default_response_properties: tuple[str, Ellipsis][source]¶

sortable_properties: tuple[str, Ellipsis][source]¶

binding: httk.core.register.OptimadeEntryBinding | None[source]¶

backend: type[source]¶

class httk.serve.optimade.client.OptimadeStore(base_url, *, client=None, page_limit=50, max_pages=10000, allow_cross_origin_pagination=False, response_fields=None)[source]¶

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.
page_limit (int) – Default remote page size.
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.

Raises:

OptimadeVersionNegotiationError – If the service cannot select a supported version.
OptimadeDiscoveryError – If discovery documents are malformed.

requested_base_url[source]¶

base_url[source]¶

page_limit = 50[source]¶

max_pages = 10000[source]¶

allow_cross_origin_pagination = False[source]¶

response_fields = None[source]¶

api_version: str | None = None[source]¶

property entry_types: tuple[RemoteEntryType, Ellipsis][source]¶

Discovered entry endpoints in the service-advertised order.

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

An immutable transport-name lookup for entry_types.

entry_type(name)[source]¶

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()[source]¶

Refresh discovery state after a fully successful rediscovery.

Raises:: OptimadeClientError – If the store is closed or discovery fails.

close()[source]¶

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

searcher(*, response_fields=..., as_of=None)[source]¶

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.serve.optimade.remote_query.RemoteSearcher