httk.optimade.backend.providers
===============================

.. py:module:: httk.optimade.backend.providers

.. autoapi-nested-parse::

   Build a :class:`~httk.optimade.backend.adapter.BackendAdapter` from :class:`~httk.core.EntryProvider` sources.

   This is the bridge from the neutral httk-core entry-provider contract to an
   OPTIMADE-serving backend: it turns one or more providers into a fully wired
   :class:`~httk.optimade.backend.adapter.BackendAdapter` over an in-memory store, deriving the served schema,
   the filter handlers, and the response-field extractors from each provider's
   descriptions, property keys, and records. It is httk-optimade's only dependency on
   ``httk.core`` beyond the shared runtime.



Functions
---------

.. autoapisummary::

   httk.optimade.backend.providers.adapter_from_providers
   httk.optimade.backend.providers.providers_from_registry


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

.. py:function:: adapter_from_providers(providers: collections.abc.Iterable[httk.core.EntryProvider], **options: Any) -> httk.optimade.backend.adapter.BackendAdapter

   Build a :class:`~httk.optimade.backend.adapter.BackendAdapter` serving the given entry providers.

   Every provider's :meth:`~httk.core.EntryProvider.entry_types` become served
   entry types (described by their :class:`~httk.core.EntryTypeDefinition`), its
   :meth:`~httk.core.EntryProvider.property_keys` name the served subset and drive
   both the filter handlers (via
   :func:`~httk.data.optimade_query.simple_property_handlers`) and the
   response-field extractors, and its
   :meth:`~httk.core.EntryProvider.records` are loaded into an
   :class:`~httk.optimade.backend.memory_store.InMemoryStore`. Every served
   property MUST be described by the entry type's definition (a custom property
   must therefore live in an
   :meth:`~httk.core.EntryTypeDefinition.extended` definition); a
   :class:`ValueError` names any offender. All served properties beyond
   ``id``/``type`` are marked default-response. Extra keyword ``options`` (e.g.
   ``sortable``, ``recognized_prefixes``) are forwarded to
   :func:`~httk.optimade.schema.served.build_served_schema`; every served
   property is sortable-capable, since the provider's property-key map is
   passed through as the source's
   :attr:`~httk.optimade.backend.adapter.EntrySource.sort_keys`.

   Declared relationships (:meth:`~httk.core.EntryProvider.relationships`) are
   fully auto-wired for serving *and* filtering: for each entry type with
   declared relationships, a synthetic ``__rel_<related_type>`` id-list field
   is materialized on EVERY row of that entry type (an empty list when the row
   has no related entries of that type, so inverse set semantics are
   well-defined), and a ``'<related_type>.id'`` entry built with
   :func:`~httk.data.optimade_query.relationship_id_handler` is merged into the
   entry type's derived filter-handler table (never overwriting an entry
   already present, mirroring how :class:`~httk.optimade.backend.adapter.BackendAdapter`
   respects explicitly supplied handler tables). ``<related_type>.id HAS ...``
   filters — and, through the related-property resolver of
   :func:`~httk.optimade.backend.translation.translate_filter`, depth-1
   relationship-property filters such as ``references.doi CONTAINS "10.1"`` —
   therefore work without any hand-wiring.


.. py:function:: providers_from_registry() -> dict[str, collections.abc.Callable[Ellipsis, httk.core.EntryProvider]]

   Return the registered entry-provider factories keyed by their registered name.

   Resolves each factory registered via
   :func:`httk.core.register_entry_provider` (through ``httk.handlers.*``
   self-registration) into a callable. Providers need data, so applications
   instantiate them: ``providers_from_registry()["atomistic-structures"](data)``.