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
exception httk.serve.optimade.client.OptimadeClientError

Bases: RuntimeError

Base class for safe, client-side OPTIMADE failures.

exception httk.serve.optimade.client.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.serve.optimade.client.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
exception httk.serve.optimade.client.OptimadeErrorDocumentError(source_url, status_code, detail=None)

Bases: OptimadeHTTPError

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

exception httk.serve.optimade.client.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.serve.optimade.client.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.serve.optimade.client.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.

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, Ellipsis]
default_response_properties: tuple[str, Ellipsis]
sortable_properties: tuple[str, Ellipsis]
binding: httk.core.register.OptimadeEntryBinding | None
backend: type
class httk.serve.optimade.client.OptimadeStore(base_url, *, client=None, page_limit=50, max_pages=10000, allow_cross_origin_pagination=False, response_fields=None)

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:
requested_base_url
base_url
page_limit = 50
max_pages = 10000
allow_cross_origin_pagination = False
response_fields = None
api_version: str | None = None
property entry_types: tuple[RemoteEntryType, Ellipsis]

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:
Return type:

httk.serve.optimade.remote_query.RemoteSearcher