httk.optimade.schema.served
===========================

.. py:module:: httk.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.optimade.schema.served.ServedSchema


Functions
---------

.. autoapisummary::

   httk.optimade.schema.served.fulltype_of
   httk.optimade.schema.served.simplified_property
   httk.optimade.schema.served.entry_type_definition_from_simple
   httk.optimade.schema.served.build_served_schema


Module Contents
---------------

.. py:function:: fulltype_of(definition: httk.core.PropertyDefinition) -> str

   Reconstruct the simplified ``fulltype`` string of a property definition.

   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.


.. py:function:: simplified_property(definition: httk.core.PropertyDefinition, *, sortable: bool = False, required_response: bool = False, default_response: bool = False) -> dict[str, Any]

   A small dialect view of a property definition for the filter/wrap layers.

   Carries the ``description``, reconstructed ``fulltype``, the implementation
   flags (``sortable``/``required_response``/``default_response``), and — when
   present — the property's ``unit`` and ``dimensions`` (used by the trajectory
   frame-wrapping).


.. py:function:: entry_type_definition_from_simple(name: str, info: collections.abc.Mapping[str, Any]) -> httk.core.EntryTypeDefinition

   Build an :class:`~httk.core.EntryTypeDefinition` from the simplified dialect.

   ``info`` is a ``{"description": <str>, "properties": {<name>: <simplified
   property dict>}}`` mapping (as produced by, e.g.,
   :func:`~httk.optimade.schema.trajectories.trajectories_entry_info`); each
   property is generated with
   :meth:`~httk.core.PropertyDefinition.from_simple`.


.. py:class:: ServedSchema

   The entry types and properties served, with derived lookup tables.


   .. py:attribute:: entry_info
      :type:  dict[str, dict[str, Any]]


   .. py:attribute:: recognized_prefixes
      :type:  tuple[str, Ellipsis]


   .. py:attribute:: all_entries
      :type:  tuple[str, Ellipsis]


   .. 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:: build_served_schema(definitions: collections.abc.Mapping[str, httk.core.EntryTypeDefinition], served: collections.abc.Mapping[str, collections.abc.Sequence[str]] | None = None, *, default_response_overrides: collections.abc.Mapping[str, collections.abc.Sequence[str]] | None = None, sortable: collections.abc.Mapping[str, collections.abc.Sequence[str]] | None = None, recognized_prefixes: tuple[str, Ellipsis] | None = None) -> ServedSchema

   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).