httk.serve.optimade.client ========================== .. py:module:: httk.serve.optimade.client .. autoapi-nested-parse:: 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 :meth:`OptimadeStore.searcher`. Attributes ---------- .. autoapisummary:: httk.serve.optimade.client.ALL_ADVERTISED Exceptions ---------- .. autoapisummary:: httk.serve.optimade.client.OptimadeClientError httk.serve.optimade.client.OptimadeTransportError httk.serve.optimade.client.OptimadeHTTPError httk.serve.optimade.client.OptimadeErrorDocumentError httk.serve.optimade.client.OptimadeDiscoveryError httk.serve.optimade.client.OptimadeVersionNegotiationError Classes ------- .. autoapisummary:: httk.serve.optimade.client.RemoteEntryType httk.serve.optimade.client.OptimadeStore Module Contents --------------- .. py:data:: ALL_ADVERTISED .. py:exception:: OptimadeClientError Bases: :py:obj:`RuntimeError` Base class for safe, client-side OPTIMADE failures. .. py:exception:: OptimadeTransportError(source_url, detail) Bases: :py:obj:`OptimadeClientError` Report that the HTTP client could not complete a request. :param source_url: Redacted URL of the failed request. :param detail: Safe transport detail. .. py:attribute:: source_url .. py:attribute:: detail .. py:exception:: OptimadeHTTPError(source_url, status_code, detail = None) Bases: :py:obj:`OptimadeClientError` Report a non-success HTTP status from a remote endpoint. :param source_url: Redacted URL of the response. :param status_code: HTTP status code returned by the service. :param detail: Optional safe error detail. .. py:attribute:: source_url .. py:attribute:: status_code .. py:attribute:: detail :value: None .. py:exception:: OptimadeErrorDocumentError(source_url, status_code, detail = None) Bases: :py:obj:`OptimadeHTTPError` Report a non-success response with a parseable OPTIMADE error document. .. py:exception:: OptimadeDiscoveryError(source_url, detail) Bases: :py:obj:`OptimadeClientError` Report a malformed or inconsistent ``/info`` discovery document. :param source_url: Redacted URL of the malformed document. :param detail: Safe discovery detail. .. py:attribute:: source_url .. py:attribute:: detail .. py:exception:: OptimadeVersionNegotiationError(source_url, detail) Bases: :py:obj:`OptimadeClientError` Report failure to negotiate a supported OPTIMADE API version. :param source_url: Redacted URL used for negotiation. :param detail: Safe negotiation detail. .. py:attribute:: source_url .. py:attribute:: detail .. py:class:: 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. :param name: Transport endpoint name. :param definition_id: Entry-definition IRI, when advertised. :param schema: Lossless schema snapshot from discovery. :param property_iris: Transport property names keyed by definition IRI. :param property_names: Local property names keyed by definition IRI. :param property_types: Property kinds keyed by transport name. :param advertised_properties: Properties advertised by the service. :param default_response_properties: Properties returned by default. :param sortable_properties: Properties accepted by remote sorting. :param binding: Recognized semantic binding, when available. :param backend: Backend class associated with the binding. .. py:attribute:: name :type: str .. py:attribute:: definition_id :type: str | None .. py:attribute:: schema :type: httk.core.optimade.OptimadeSchemaSnapshot .. py:attribute:: property_iris :type: collections.abc.Mapping[str, str] .. py:attribute:: property_names :type: collections.abc.Mapping[str, str] .. py:attribute:: property_types :type: collections.abc.Mapping[str, tuple[str, str | None]] .. py:attribute:: advertised_properties :type: tuple[str, Ellipsis] .. py:attribute:: default_response_properties :type: tuple[str, Ellipsis] .. py:attribute:: sortable_properties :type: tuple[str, Ellipsis] .. py:attribute:: binding :type: httk.core.register.OptimadeEntryBinding | None .. py:attribute:: backend :type: type .. py:class:: 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. :param base_url: Absolute HTTP(S) service base URL. :param client: Optional borrowed synchronous HTTP client. :param page_limit: Default remote page size. :param max_pages: Maximum continuation pages followed by one query. :param allow_cross_origin_pagination: Permit continuation links on another origin. :param response_fields: Default response-field selection for new searchers. :raises OptimadeVersionNegotiationError: If the service cannot select a supported version. :raises OptimadeDiscoveryError: If discovery documents are malformed. .. py:attribute:: requested_base_url .. py:attribute:: base_url .. py:attribute:: page_limit :value: 50 .. py:attribute:: max_pages :value: 10000 .. py:attribute:: allow_cross_origin_pagination :value: False .. py:attribute:: response_fields :value: None .. py:attribute:: api_version :type: str | None :value: None .. py:property:: entry_types :type: tuple[RemoteEntryType, Ellipsis] Discovered entry endpoints in the service-advertised order. .. py:property:: entry_types_by_name :type: collections.abc.Mapping[str, RemoteEntryType] An immutable transport-name lookup for :attr:`entry_types`. .. py:method:: entry_type(name) Return one discovered endpoint by transport name. :param name: Service-advertised endpoint name. :return: Discovered endpoint descriptor. :raises KeyError: If no endpoint has that name. .. py:method:: refresh() Refresh discovery state after a fully successful rediscovery. :raises OptimadeClientError: If the store is closed or discovery fails. .. py:method:: close() Close an internally owned HTTP client; borrowed clients stay open. .. py:method:: 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. :param response_fields: Per-search field selection override. :param as_of: Historic cutoff; unsupported because remote snapshot negotiation is unavailable. :return: New remote search plan. :raises OptimadeClientError: If the store is closed. :raises ValueError: If a historic cutoff is requested.