fleche.digest
=============

.. py:module:: fleche.digest


Attributes
----------

.. autoapisummary::

   fleche.digest.logger
   fleche.digest.DIGEST_LENGTH
   fleche.digest.T
   fleche.digest._HOOKS
   fleche.digest._EP_HOOKS
   fleche.digest._TYPES_WITHOUT_DIGEST


Exceptions
----------

.. autoapisummary::

   fleche.digest.Unhashable


Classes
-------

.. autoapisummary::

   fleche.digest.Digest
   fleche.digest.Hook


Functions
---------

.. autoapisummary::

   fleche.digest.get_hooks
   fleche.digest.add_hook
   fleche.digest.load_entry_points
   fleche.digest._digest_mapping
   fleche.digest.digest
   fleche.digest._digest_bytes


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

.. py:data:: logger

.. py:exception:: Unhashable

   Bases: :py:obj:`Exception`


   Exception raised when an object cannot be digested.


.. py:class:: Digest

   Bases: :py:obj:`str`


   str(object='') -> str
   str(bytes_or_buffer[, encoding[, errors]]) -> str

   Create a new string object from the given object. If encoding or
   errors is specified, then the object must expose a data buffer
   that will be decoded using the given encoding and error handler.
   Otherwise, returns the result of object.__str__() (if defined)
   or repr(object).
   encoding defaults to sys.getdefaultencoding().
   errors defaults to 'strict'.


   .. py:method:: expand(cache=None) -> Digest

      Expand a short digest prefix to its full-length digest using the cache.

      :param cache: A cache instance to use. If None, uses the current context's cache.

      :returns: The full-length :class:`Digest`.



   .. py:method:: shrink(cache=None) -> Digest

      Shrink a digest to its shortest unambiguous prefix using the cache.

      :param cache: A cache instance to use. If None, uses the current context's cache.

      :returns: The shortest unambiguous :class:`Digest` prefix.



.. py:data:: DIGEST_LENGTH
   :value: 64


.. py:data:: T

.. py:class:: Hook

   Bases: :py:obj:`Generic`\ [\ :py:obj:`T`\ ]


   .. py:attribute:: type
      :type:  T


   .. py:attribute:: digest
      :type:  Callable[[T], str | Digest]


.. py:data:: _HOOKS
   :value: []


.. py:data:: _EP_HOOKS
   :value: []


.. py:data:: _TYPES_WITHOUT_DIGEST
   :type:  set[type]

.. py:function:: get_hooks()

.. py:function:: add_hook(hook: Hook | tuple[Type[T], Callable[[T], str]])

.. py:function:: load_entry_points()

.. py:function:: _digest_mapping(m, contents: collections.abc.Mapping) -> bytes

.. py:function:: digest(value: Any) -> Digest

.. py:function:: _digest_bytes(value: Any) -> bytes

   Returns bytes representing the SHA-256 digest of *value*.

   All recursive call sites pass the result directly to ``m.update()``.

   **Wire-format note**: currently returns ``m.hexdigest().encode()`` (64 UTF-8
   hex bytes) so the bytes fed into parent hashes are identical to the previous
   ``digest(v).encode()`` calls — no backwards-incompatible change.  To gain
   the raw-bytes speedup (Issue #440), change **only** the final ``return``
   here to ``m.digest()`` (32 bytes), update ``digest()`` to call ``.hex()``
   instead of ``.decode()``, and change the ``encode()`` calls on the
   early-return paths (Digest pass-through, hooks, ``__digest__``) to
   ``bytes.fromhex(...)``.  That must be coordinated with a ``hash_version``
   bump and a ``Cache.redigest`` migration.