httk.store.query.portable
=========================

.. py:module:: httk.store.query.portable

.. autoapi-nested-parse::

   Derive portable query fields and operations from OPTIMADE definitions.



Classes
-------

.. autoapisummary::

   httk.store.query.portable.PortableQueryCapabilities


Functions
---------

.. autoapisummary::

   httk.store.query.portable.portable_query_capabilities
   httk.store.query.portable.portable_query_fields


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

.. py:class:: PortableQueryCapabilities

   Describe the query operations guaranteed by one property definition.

   ``query-support`` expresses a cross-provider guarantee, not a particular
   server's implementation detail.  ``all optional`` is deliberately
   fail-closed here: it gives a portable client no operation it can rely on.
   A server may offer more, but that is not represented by the definition.

   :param query_support: The normalized declared query-support level.
   :param operations: The portable operation families guaranteed by the definition.


   .. py:attribute:: query_support
      :type:  str | None


   .. py:attribute:: operations
      :type:  frozenset[str]


   .. py:method:: supports(operation)

      Report whether ``operation`` is guaranteed by this definition.

      :param operation: The operation family to test.
      :return: ``True`` when the operation is portable.



.. py:function:: portable_query_capabilities(definition)

   Derive the portable operation subset for ``definition``.

   The operation names are ``"equality"``, ``"ordering"``,
   ``"stringmatching"``, and ``"set"``.  They intentionally describe the
   query-language operation families rather than storage implementation.
   ``IS [NOT] KNOWN`` is part of the equality family because it is the NULL
   spelling of equality/inequality in the OPTIMADE filter language.

   :param definition: The OPTIMADE property definition to inspect.
   :return: The guaranteed portable query capabilities.


.. py:function:: portable_query_fields(entry_type, *, include = (), exclude = ())

   Return the ordered portable query fields described by ``entry_type``.

   By default, this selects scalar fields and flat lists with at least one
   operation guaranteed by their definition. ``include`` is an explicit
   binding override for named existing properties; it is appended as a second
   ordered group after the derived fields, in entry-definition order among the
   included names, but does not manufacture query capabilities absent from that
   definition. ``exclude`` always wins. Both arguments reject unknown or
   duplicate names so binding mistakes cannot silently broaden a profile.

   :param entry_type: The entry definition whose properties are inspected.
   :param include: Existing property names to append to the derived selection.
   :param exclude: Existing property names to remove from the selection.
   :return: Derived property names followed by explicitly included names.
   :raises ValueError: If ``include`` or ``exclude`` contains an unknown or
       duplicate property name.