httk.store.store_common
=======================

.. py:module:: httk.store.store_common

.. autoapi-nested-parse::

   Backend-neutral save-path machinery shared by storage backends.



Exceptions
----------

.. autoapisummary::

   httk.store.store_common.EntryIdConflictError
   httk.store.store_common.EntryMetadataConflictError
   httk.store.store_common.EntryReplacementError
   httk.store.store_common.EntryDispatchIntegrityError


Classes
-------

.. autoapisummary::

   httk.store.store_common.EntryIdScheme
   httk.store.store_common.EntryStore
   httk.store.store_common.SaveProjection
   httk.store.store_common.IdentityCaches


Functions
---------

.. autoapisummary::

   httk.store.store_common.reject_cursor_proxy


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

.. py:class:: EntryIdScheme

   Configuration used to mint human-readable entry identifiers.

   :param base: Dot-separated database namespace.
   :param series: Campaign-series token.
   :param type_in_base: Whether the served entry type is appended to ``base``.


   .. py:attribute:: base
      :type:  str


   .. py:attribute:: series
      :type:  str


   .. py:attribute:: type_in_base
      :type:  bool
      :value: False



.. py:exception:: EntryIdConflictError(table_name, entry_id, existing_logical_id, requested_logical_id)

   Bases: :py:obj:`ValueError`


   An entry id is already owned by a different lineage or alternative group.

   :param table_name: The table containing the conflicting identifier.
   :param entry_id: The conflicting entry identifier.
   :param existing_logical_id: The lineage or group already owning the identifier.
   :param requested_logical_id: The lineage or group requesting it, when known.


   .. py:attribute:: table_name


   .. py:attribute:: entry_id


   .. py:attribute:: existing_logical_id


   .. py:attribute:: requested_logical_id


.. py:class:: EntryStore

   Bases: :py:obj:`Protocol`


   The store surface consumed by :mod:`httk.store.backend.sql.stored_federation`.

   This protocol deliberately describes the small backend seam used by the
   federation.  The stored-property plan and candidate-stream objects remain
   backend-specific; their SQL implementations use :meth:`searcher`.


   .. py:property:: entry_layout
      :type: tuple[httk.store.storage_layout.EntryFamilyLayout, Ellipsis]


      Return the configured entry-family layouts in stable order.


   .. py:method:: searcher(*, as_of = None)

      Return a backend searcher used to build candidate ID streams.



   .. py:method:: fetch(cls, sid, *, eager = False)

      Fetch the stored record of ``cls`` identified by ``sid``.

      :param cls: The storable record class.
      :param sid: The stored row identifier to fetch.
      :param eager: Whether to fully materialize the record instead of returning a lazy row.
      :return: The reconstructed instance.



   .. py:method:: fetch_many(cls, sids, *, eager = False)

      Fetch the stored records of ``cls`` identified by ``sids``.

      Batched counterpart of :meth:`fetch`.

      :param cls: The storable record class.
      :param sids: The stored row identifiers to fetch.
      :param eager: Whether to fully materialize each record instead of returning lazy rows.
      :return: The reconstructed instances in ``sids`` order.
      :raises KeyError: When any requested row is absent.



   .. py:method:: stored_property_plan(family)

      Return the backend-specific stored-property plan for one family.

      :param family: The logical entry-family class to plan.
      :return: The validated stored-property plan consumed by federation.



.. py:exception:: EntryMetadataConflictError

   Bases: :py:obj:`ValueError`


   Stored identity-excluded metadata differs from a repeated save.


.. py:exception:: EntryReplacementError(table_name, predecessor_logical_id, conflicting_logical_id)

   Bases: :py:obj:`ValueError`


   A replacement deduplicated onto a row from a different lineage.

   :param table_name: The table (or collection) whose replacement failed.
   :param predecessor_logical_id: The logical_id of the intended predecessor.
   :param conflicting_logical_id: The logical_id of the row actually hit.


   .. py:attribute:: table_name


   .. py:attribute:: predecessor_logical_id


   .. py:attribute:: conflicting_logical_id


.. py:exception:: EntryDispatchIntegrityError

   Bases: :py:obj:`RuntimeError`


   A persisted entry dispatch row does not name exactly its expected backing.


.. py:class:: SaveProjection(*, store_timestamp = None)

   One-save projection cache shared by core identity and SQL encoding.


   .. py:attribute:: store_timestamp
      :value: None



   .. py:attribute:: values_by_source
      :type:  dict[tuple[type, int], collections.abc.Mapping[str, object]]


   .. py:attribute:: validated
      :type:  set[tuple[type, int]]


   .. py:attribute:: metadata_rows
      :type:  dict[tuple[type, int], collections.abc.Mapping[str, Any]]


   .. py:attribute:: metadata_children
      :type:  dict[tuple[type, int, str], Any]


   .. py:attribute:: metadata_content_ids
      :type:  dict[tuple[type, int], str]


   .. py:attribute:: active
      :type:  set[tuple[type, int]]


   .. py:attribute:: inserted
      :type:  list[tuple[type, int]]
      :value: []



   .. py:method:: projector(record_type, source)


   .. py:method:: content_id(record_type, source, *, extras = None)


.. py:function:: reject_cursor_proxy(obj)

   Reject a lazy cursor row before a backend attempts to save it.


.. py:class:: IdentityCaches

   Weak identity caches shared by storage backends.