httk.serve.optimade.schema.served ================================= .. py:module:: httk.serve.optimade.schema.served .. autoapi-nested-parse:: The registry of entry types and properties served by an OPTIMADE deployment. A :class:`ServedSchema` narrows a set of first-class :class:`~httk.core.EntryTypeDefinition` objects (supplied from outside, e.g. by an :class:`~httk.core.EntryProvider`) down to the entry types and properties a backend implements, and derives the endpoint and response-field tables used during request validation and response generation. The full OPTIMADE property definitions live in httk-core; this module keeps, for each served property, a small *simplified* view (its ``fulltype`` and the implementation flags) that the filter-translation and response layers consume, alongside the full property definitions served on the entry listing info endpoint. Classes ------- .. autoapisummary:: httk.serve.optimade.schema.served.ServedSchema Functions --------- .. autoapisummary:: httk.serve.optimade.schema.served.fulltype_of httk.serve.optimade.schema.served.simplified_property httk.serve.optimade.schema.served.entry_type_definition_from_simple httk.serve.optimade.schema.served.derived_endpoint_name httk.serve.optimade.schema.served.build_served_schema Module Contents --------------- .. py:function:: fulltype_of(definition) Reconstruct a property's simplified ``fulltype`` string. Maps the OPTIMADE type back to the compact spelling used by the filter layer: ``"string"``/``"integer"``/``"float"``/``"boolean"``/``"timestamp"``, ``"dict"`` for dictionaries, and ``"list of ..."`` (nesting through the definition's ``items``) for lists. :param definition: Property definition to inspect. :return: Compact fulltype spelling used by the filter and response layers. .. py:function:: simplified_property(definition, *, sortable = False, required_response = False, default_response = False, queryable = True) Build a simplified property view for the filter and wrapping layers. Carries the ``description``, reconstructed ``fulltype``, the implementation flags (``sortable``/``required_response``/``default_response``/``queryable``), and — when present — the property's ``unit`` and ``dimensions`` (used by the trajectory frame-wrapping). :param definition: Property definition to simplify. :param sortable: Mark the property as sortable by the backend. :param required_response: Mark the property as required in responses. :param default_response: Mark the property as returned by default. :param queryable: Mark the property as usable in ``filter=`` (false honors an ``x-optimade-requirements.query-support`` of ``"none"``). :return: Simplified property metadata. .. py:function:: entry_type_definition_from_simple(name, info) Build an :class:`~httk.core.EntryTypeDefinition` from simplified metadata. ``info`` is a ``{"description": , "properties": {: }}`` mapping (as produced by, e.g., :func:`~httk.serve.optimade.schema.trajectories.trajectories_entry_info`); each property is generated with :meth:`~httk.core.PropertyDefinition.from_simple`. :param name: Entry endpoint and definition name. :param info: Simplified entry description and property mapping. :return: Full entry-type definition. .. py:class:: ServedSchema Describe served entry types and their derived lookup tables. :param entry_info: Simplified entry-info documents keyed by entry type. :param entry_definition_ids: Definition IRIs keyed by entry type. :param recognized_prefixes: Property-definition prefixes recognized in requests. :param all_entries: Served entry endpoint names in declaration order. :param revision_endpoints: Store-backed revision endpoint names. :param revision_base: Base entry type keyed by revision endpoint. :param alt_endpoints: Store-backed alternative endpoint names. :param alt_base: Base entry type keyed by alternative endpoint. :param valid_endpoints: Fixed and entry endpoint names accepted by validation. :param properties_by_entry: Served property names keyed by entry type. :param default_response_fields: Default response fields keyed by entry type. :param required_response_fields: Required response fields keyed by entry type. :param unknown_response_fields: Defined but unserved fields keyed by entry type. :param sortable_response_fields: Sortable response fields keyed by entry type. :param property_definitions: Full property definitions keyed by entry type. .. py:attribute:: entry_info :type: dict[str, dict[str, Any]] .. py:attribute:: entry_definition_ids :type: dict[str, str] .. py:attribute:: recognized_prefixes :type: tuple[str, Ellipsis] .. py:attribute:: all_entries :type: tuple[str, Ellipsis] .. py:attribute:: revision_endpoints :type: tuple[str, Ellipsis] .. py:attribute:: revision_base :type: dict[str, str] .. py:attribute:: alt_endpoints :type: tuple[str, Ellipsis] .. py:attribute:: alt_base :type: dict[str, str] .. py:attribute:: valid_endpoints :type: tuple[str, Ellipsis] .. py:attribute:: properties_by_entry :type: dict[str, tuple[str, Ellipsis]] .. py:attribute:: default_response_fields :type: dict[str, tuple[str, Ellipsis]] .. py:attribute:: required_response_fields :type: dict[str, tuple[str, Ellipsis]] .. py:attribute:: unknown_response_fields :type: dict[str, tuple[str, Ellipsis]] .. py:attribute:: sortable_response_fields :type: dict[str, tuple[str, Ellipsis]] .. py:attribute:: property_definitions :type: dict[str, dict[str, dict[str, Any]]] .. py:function:: derived_endpoint_name(base, suffix) Return the derived (``~revs``/``~alts``) endpoint name for a base entry. An already-``_``-prefixed base (a provider wire name such as ``_httk_runs``) keeps its single prefix; a bare standard base gets the ``_httk_`` prefix, so both the schema and the route parser spell ``_httk_runs~revs`` and ``_httk_structures~revs`` alike. :param base: The served base entry-type name. :param suffix: The derived-endpoint suffix (``"revs"`` or ``"alts"``). :return: The derived endpoint name. .. py:function:: build_served_schema(definitions, served = None, *, default_response_overrides = None, sortable = None, recognized_prefixes = None, revisions = (), alternatives = ()) Build a :class:`ServedSchema` from entry-type definitions. ``definitions`` maps each served entry type name to its full :class:`~httk.core.EntryTypeDefinition`. ``served`` maps each entry type to the subset of property names actually served (defaulting to every property the definition describes); every served name MUST be described by the definition (a :class:`ValueError` names any offender). ``id`` and ``type`` are always default- and required-response; ``default_response_overrides`` marks additional served properties as default-response, and ``sortable`` marks served properties as sortable. ``recognized_prefixes`` defaults to the prefixes currently registered via :func:`~httk.core.register_definition_prefix` (resolved at call time so newly registered prefixes are honored). :param definitions: Full definitions keyed by served entry type. :param served: Optional served-property subset keyed by entry type. :param default_response_overrides: Additional default fields keyed by entry type. :param sortable: Sortable fields keyed by entry type. :param recognized_prefixes: Prefixes recognized in response-field requests. :param revisions: Base entries for which stored revision endpoints are served. :param alternatives: Base entries for which stored alternative endpoints are served. :return: Derived schema and lookup tables. :raises ValueError: If a requested served property is not defined.