httk.core.optimade ================== .. py:module:: httk.core.optimade .. autoapi-nested-parse:: OPTIMADE resources, typed entries, and filter parsing. Submodules ---------- .. toctree:: :maxdepth: 1 /reference/autoapi/httk/core/optimade/entries/index /reference/autoapi/httk/core/optimade/filter/index /reference/autoapi/httk/core/optimade/resources/index /reference/autoapi/httk/core/optimade/standard_names/index Attributes ---------- .. autoapisummary:: httk.core.optimade.FilterAst httk.core.optimade.STANDARD_NAME_EVIDENCE Exceptions ---------- .. autoapisummary:: httk.core.optimade.IncompleteOptimadeResourceError httk.core.optimade.ParserError httk.core.optimade.ParserSyntaxError Classes ------- .. autoapisummary:: httk.core.optimade.CalculationView httk.core.optimade.FileView httk.core.optimade.OptimadeCalculation httk.core.optimade.OptimadeEntryBackend httk.core.optimade.OptimadeEntryView httk.core.optimade.OptimadeFile httk.core.optimade.OptimadeReference httk.core.optimade.ReferenceView httk.core.optimade.OptimadeDocument httk.core.optimade.OptimadeResource httk.core.optimade.OptimadeSchemaSnapshot httk.core.optimade.StandardSchemaCompletion Functions --------- .. autoapisummary:: httk.core.optimade.decode_optimade_value httk.core.optimade.decode_optional_timestamp httk.core.optimade.parse_optimade_filter httk.core.optimade.parse_optimade_filter_raw httk.core.optimade.is_optimade_entry_url httk.core.optimade.optimade_document_root httk.core.optimade.optimade_entry_url_info httk.core.optimade.optimade_resource_from_url httk.core.optimade.redact_optimade_document_text httk.core.optimade.redact_optimade_url httk.core.optimade.complete_standard_schema httk.core.optimade.infer_standard_names httk.core.optimade.parse_optimade_api_version Package Contents ---------------- .. py:class:: CalculationView(backend) Bases: :py:obj:`OptimadeEntryView` Present an :class:`OptimadeCalculation` as a lazy canonical view. :param backend: Calculation backend to present, or an existing compatible view. .. py:attribute:: backend_class .. py:attribute:: record_class .. py:class:: FileView(backend) Bases: :py:obj:`OptimadeEntryView` Present an :class:`OptimadeFile` as a lazy canonical view. :param backend: File backend to present, or an existing compatible view. .. py:attribute:: backend_class .. py:attribute:: record_class .. py:exception:: IncompleteOptimadeResourceError Bases: :py:obj:`ValueError` A resource lacks, nulls, or malforms a local record property. .. py:class:: OptimadeCalculation Bases: :py:obj:`OptimadeEntryBackend` Bind an OPTIMADE resource to the standard calculations schema. :param resource: Source resource and its schema provenance. .. py:attribute:: entry_type_name :type: ClassVar[str] :value: 'calculations' .. py:attribute:: entry_type_definition_id :type: ClassVar[str] :value: 'https://schemas.optimade.org/defs/v1.3/entrytypes/optimade/calculations' .. py:class:: OptimadeEntryBackend Store one typed handle around an authoritative OPTIMADE resource. :param resource: Source resource and its schema provenance. .. py:attribute:: resource :type: httk.core.optimade.resources.OptimadeResource .. py:attribute:: kind :type: ClassVar[str] :value: 'optimade' .. py:attribute:: entry_type_name :type: ClassVar[str] .. py:attribute:: entry_type_definition_id :type: ClassVar[str] .. py:property:: raw :type: collections.abc.Mapping[str, httk.core.optimade.resources.FrozenJson] The immutable JSON API resource mapping, retaining source provenance. .. py:method:: unwrap() Return the exact source resource, including document and schema provenance. :return: The source resource represented by this backend. .. py:property:: local_schema :type: httk.core.property_definitions.EntryTypeDefinition Return the standard local schema for this backend. .. py:method:: value_by_definition_id(definition_id, *, default = _MISSING) Return a raw value by exact semantic IRI, retaining missing vs. null. Values are intentionally undecoded here. This lets record views name missing/null semantic properties accurately and gives callers access to exact raw JSON before selecting a representation. :param definition_id: Semantic property IRI to look up. :param default: Value to return when the property is not present. :return: The raw property value, or ``default`` when it is absent. :raises ValueError: If the resource attributes or schema mapping is malformed. .. py:method:: decode_value(definition, value) Decode *value*, applying an exact-IRI binding override when present. :param definition: Local property definition for the value. :param value: Raw value to decode. :return: Decoded value from the matching generic or binding-specific decoder. :raises TypeError: If the value does not match the selected property decoder. :raises ValueError: If the property definition or value is invalid. .. py:property:: id :type: str Return the semantic resource identifier. .. py:property:: type :type: str Return the semantic resource type identifier. .. py:property:: immutable_id :type: str | None Return the optional immutable semantic identifier. .. py:property:: last_modified :type: datetime.datetime | None Return the optional last-modified timestamp. A value without a UTC offset violates RFC 3339 and has no defined meaning, so it is treated as unknown (decoded to ``None`` with a once-per-origin deviation warning) rather than being interpreted as UTC. .. py:class:: OptimadeEntryView(backend) Present one typed resource backend as a lazy generated record. :param backend: Typed backend to present, or an existing compatible view. .. py:attribute:: backend_class :type: ClassVar[type[OptimadeEntryBackend]] .. py:attribute:: record_class :type: ClassVar[type[httk.core.entry_types.Reference] | type[httk.core.entry_types.File] | type[httk.core.entry_types.Calculation]] .. py:property:: backend :type: OptimadeEntryBackend Return the typed backend behind this view. .. py:method:: unwrap() Return the exact source resource behind this view. .. py:property:: id :type: str Return the resource identifier. .. py:property:: type :type: str Return the resource type identifier. .. py:property:: record :type: httk.core.entry_types.Reference | httk.core.entry_types.File | httk.core.entry_types.Calculation Return the lazily materialized canonical record. .. py:class:: OptimadeFile Bases: :py:obj:`OptimadeEntryBackend` Bind an OPTIMADE resource to the standard files schema. :param resource: Source resource and its schema provenance. .. py:attribute:: entry_type_name :type: ClassVar[str] :value: 'files' .. py:attribute:: entry_type_definition_id :type: ClassVar[str] :value: 'https://schemas.optimade.org/defs/v1.2/entrytypes/optimade/files' .. py:class:: OptimadeReference Bases: :py:obj:`OptimadeEntryBackend` Bind an OPTIMADE resource to the standard references schema. :param resource: Source resource and its schema provenance. .. py:attribute:: entry_type_name :type: ClassVar[str] :value: 'references' .. py:attribute:: entry_type_definition_id :type: ClassVar[str] :value: 'https://schemas.optimade.org/defs/v1.2/entrytypes/optimade/references' .. py:class:: ReferenceView(backend) Bases: :py:obj:`OptimadeEntryView` Present an :class:`OptimadeReference` as a lazy canonical view. :param backend: Reference backend to present, or an existing compatible view. .. py:attribute:: backend_class .. py:attribute:: record_class .. py:function:: decode_optimade_value(definition, value) Decode one value exactly from its local property definition. Binding-specific decoder callables use the stable signature ``decoder(value, definition)`` and replace this generic decoder for their exact property-definition IRI. JSON floats are retained as :class:`~decimal.Decimal`; nested lists and dictionaries become tuples and immutable mappings. :param definition: Local property definition that describes the value. :param value: Raw value to decode. :return: Decoded value with nested containers made immutable. :raises TypeError: If the value does not match the declared property shape. :raises ValueError: If the property definition is unsupported or malformed. .. py:function:: decode_optional_timestamp(value, *, source_url) Decode an optional RFC 3339 timestamp, treating an offset-less value as unknown. A string with a full RFC 3339 date-time shape (a ``YYYY-MM-DD`` date, a ``T`` or space separator, and a time to at least the second with an optional fraction) but no UTC offset violates RFC 3339 and has no defined meaning, so it is reported once per service origin through the report channel and decodes to ``None`` rather than being interpreted as UTC. ``None`` decodes to ``None`` and an offset-bearing value (including a ``Z`` suffix) decodes to the aware timestamp. Every other value -- a non-string, an unparseable string, or a partial form such as a bare date or an hour-minute time -- raises. :param value: Raw value to decode; ``None`` decodes to ``None``. :param source_url: Redacted source URL of the serving document, used to derive the service origin that scopes the once-per-origin deviation warning. :return: The decoded offset-aware timestamp, or ``None`` when the value is absent or is a full offset-less RFC 3339 date-time. :raises ValueError: If the value is not ``None`` and is not a parseable, full-shape RFC 3339 timestamp string. .. py:type:: FilterAst :canonical: tuple[Any, ...] .. py:exception:: ParserError Bases: :py:obj:`Exception` Common base class for all non-exit exceptions. .. py:exception:: ParserSyntaxError(*args) Bases: :py:obj:`ParserError` Common base class for all non-exit exceptions. .. py:attribute:: info .. py:attribute:: line .. py:attribute:: pos .. py:attribute:: linestr .. py:function:: parse_optimade_filter(filter_string, verbosity = 0) Parse an OPTIMADE filter into the public abstract syntax tree format. :param filter_string: OPTIMADE filter expression to parse. :param verbosity: Diagnostic verbosity setting passed to the parser. :return: Nested tuple abstract syntax tree in ``ojf`` format. :raises ParserSyntaxError: If the filter cannot be parsed, or is too long or too deeply nested to parse within the interpreter's recursion limit. :raises ParserError: If the filter cannot be parsed. .. py:function:: parse_optimade_filter_raw(filter_string, verbosity = 0) Parse an OPTIMADE filter and return its raw grammar parse tree. :param filter_string: OPTIMADE filter expression to parse. :param verbosity: Diagnostic verbosity setting passed to the parser. :return: Raw nested tuple parse tree before ``ojf`` conversion. :raises ParserSyntaxError: If the filter cannot be parsed, or is too long or too deeply nested to parse within the interpreter's recursion limit. :raises ParserError: If the filter cannot be parsed. .. py:class:: OptimadeDocument Original OPTIMADE response text and the URL from which it was obtained. Direct construction performs no sanitization. Use :meth:`from_response` before storing an externally sourced document or URL. :param text: Original response text, optionally sanitized by :meth:`from_response`. :param source_url: URL from which the response was obtained. .. py:attribute:: text :type: str .. py:attribute:: source_url :type: str .. py:method:: from_response(text, source_url) :classmethod: Construct a source-exact document with safe pagination provenance. :param text: Response text to sanitize and retain. :param source_url: Source URL to sanitize and retain. :return: A source document with safe pagination provenance. .. py:class:: OptimadeResource Bases: :py:obj:`collections.abc.Mapping`\ [\ :py:obj:`str`\ , :py:obj:`FrozenJson`\ ] Represent one immutable resource in an OPTIMADE response envelope. :param document: Source-exact response document to decode lazily. :param data_index: Index of the resource in the response ``member`` array. :param schema: Schema snapshot applicable to the response. :param member: Response envelope member holding this resource: ``"data"`` (the default) for a primary resource, or ``"included"`` for a resource from the response's ``included`` array. This field participates in the resource's identity, so a primary resource and a same-index included resource are never mistaken for the same resource. .. py:attribute:: document :type: OptimadeDocument .. py:attribute:: data_index :type: int .. py:attribute:: schema :type: OptimadeSchemaSnapshot .. py:attribute:: member :type: str :value: 'data' .. py:method:: unwrap() Return the immutable resource object at this response's member index. :return: Immutable resource mapping selected from the response. :raises TypeError: If ``data_index`` is not an integer. :raises IndexError: If ``data_index`` is outside the response member. :raises ValueError: If the response member is not an object or array of objects. .. py:property:: id :type: str The protocol-mandated JSON API resource identifier. This intentionally reads the JSON API envelope directly. It is a generic source-resource capability, not semantic recognition of a transport property name. .. py:property:: type :type: str The protocol-mandated JSON API resource type identifier. .. py:class:: OptimadeSchemaSnapshot Describe the ``/info/`` document for a resource response. :param entry_type: Entry type named by the schema endpoint. :param info_document: Source-exact schema response document. .. py:attribute:: entry_type :type: str .. py:attribute:: info_document :type: OptimadeDocument .. py:function:: is_optimade_entry_url(url) Return whether *url* has the shape of an OPTIMADE single-entry URL. :param url: Candidate URL to inspect. :return: Whether the URL identifies one OPTIMADE entry. .. py:function:: optimade_document_root(document) Return the immutable, Decimal-preserving root of *document* lazily. This is intentionally a small public seam for source-model consumers that need to interpret an OPTIMADE envelope or an ``/info`` document without duplicating JSON parsing. The returned mapping is cached per equal :class:`OptimadeDocument` and must be treated as immutable. :param document: Source document to parse lazily. :return: Cached immutable document root. :raises ValueError: If the document is invalid JSON or has a non-object root. .. py:function:: optimade_entry_url_info(url) Return an OPTIMADE entry type and its derived info URL, if *url* has that shape. :param url: Candidate single-entry URL. :return: Entry type and derived info URL, or ``None`` when the shape is invalid. .. py:function:: optimade_resource_from_url(url, *, timeout = None) Fetch one OPTIMADE entry and its schema snapshot from *url*. Redirects follow ``urllib`` defaults. Both requests use the datastream layer and honor ``timeout`` (or its configured default when it is ``None``). :param url: Single-entry URL to fetch. :param timeout: Optional timeout applied to both requests. :return: Resource backed by the entry and its schema snapshot. :raises ValueError: If the URL or either response is not a valid OPTIMADE resource. .. py:function:: redact_optimade_document_text(text) Sanitize only top-level pagination URLs, preserving source authority. A direct string ``links.next`` or its JSON:API link-object ``href`` has recognized URL credentials removed. Every other byte remains untouched: in particular URL-like object keys, resource attributes, relationships, extension values, whitespace, and number spelling are semantic source data. Malformed JSON is returned unchanged because its envelope path cannot be identified safely without guessing. :param text: JSON document text to sanitize. :return: Text with only recognized pagination credentials removed. :raises TypeError: If *text* is not a string. .. py:function:: redact_optimade_url(url) Return *url* without userinfo, recognized sensitive query parameters, or its fragment. Non-URL strings are returned unchanged except for fragment removal. Non-sensitive URL spelling is retained byte-for-byte; decoding is used only to recognize query keys. Fragments are not semantically load-bearing for OPTIMADE URLs or file fetches and are never retained in diagnostics. :param url: URL or diagnostic string to sanitize. :return: Sanitized URL or unchanged non-URL string. :raises TypeError: If *url* is not a string. .. py:data:: STANDARD_NAME_EVIDENCE :value: 'standard-name' Evidence tag recorded for a name inferred from the standard namespace rule. .. py:class:: StandardSchemaCompletion Identities inferred for standard-namespace property names. :param entry_type: Entry type of the info document these names belong to. :param api_version: Specification version the service declared, if any. :param entry_type_definition_id: Definition IRI of the matched standard entry type, set only when standard-name inference is possible for this snapshot (a usable declared version and an owner-declared version table); ``None`` otherwise. :param definitions_by_name: Remote property name mapped to the property definition IRI inferred for it. :param evidence_by_name: Remote property name mapped to the evidence tag that justified its inference. .. py:attribute:: entry_type :type: str .. py:attribute:: api_version :type: str | None .. py:attribute:: entry_type_definition_id :type: str | None .. py:attribute:: definitions_by_name :type: collections.abc.Mapping[str, str] .. py:attribute:: evidence_by_name :type: collections.abc.Mapping[str, str] .. py:function:: complete_standard_schema(snapshot) Return the standard-name completion for one schema snapshot. Registry-driven wrapper over :func:`infer_standard_names`. It reads the declared specification version from the info document's own ``meta.api_version``, resolves the standard entry type by name against the registered OPTIMADE entry bindings, and gates name-based inference on that binding's ``standard_property_versions`` table. It never raises for malformed or hostile remote input: the safe answer is an empty completion. ``entry_type_definition_id`` is set only when standard-name inference is possible for this snapshot (a usable declared version and an owner-declared version table). :param snapshot: Schema snapshot whose advertised names to complete. :return: The inferred completion, empty when unresolved or unsupported by the declared version. .. py:function:: infer_standard_names(*, entry_type, api_version, advertised, definition_ids_by_name, introduced_in) Infer definition IRIs for advertised standard-namespace property names. Pure and registry-free. For each advertised name the standard namespace rule is applied: an unprefixed name that the declared specification version already defines is completed to that standard property's definition IRI. A declared ``$id`` always wins, provider-prefixed names carry no standard semantics, and a name introduced only in a later version stays unknown. An absent or non-major-1 declared version disables inference entirely. :param entry_type: Entry type being completed. :param api_version: Specification version the service declared. :param advertised: The info document's ``data.properties`` mapping. :param definition_ids_by_name: Standard property name to definition IRI. :param introduced_in: Standard property name to its earliest spec version. :return: The names inferred for this schema, possibly empty. .. py:function:: parse_optimade_api_version(value) Return the ``(major, minor)`` of a major-1 OPTIMADE version, or ``None``. ``MAJOR.MINOR`` and ``MAJOR.MINOR.PATCH`` are accepted with optional trailing pre-release or build text ignored. Only the ``(major, minor)`` pair is compared. A value whose major version is not 1, or which does not parse, yields ``None`` (the client supports major version 1 only). :param value: Candidate version value. :return: The ``(major, minor)`` pair, or ``None`` when unusable.