fleche.storage.pickle_file
==========================

.. py:module:: fleche.storage.pickle_file


Attributes
----------

.. autoapisummary::

   fleche.storage.pickle_file.logger
   fleche.storage.pickle_file._HMAC_MIN_KEY_BYTES


Classes
-------

.. autoapisummary::

   fleche.storage.pickle_file.PickleFileBackend
   fleche.storage.pickle_file.ValuePickleFile
   fleche.storage.pickle_file.CallPickleFile


Functions
---------

.. autoapisummary::

   fleche.storage.pickle_file._normalize_secret_key


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

.. py:data:: logger

.. py:data:: _HMAC_MIN_KEY_BYTES
   :value: 32


.. py:function:: _normalize_secret_key(key) -> list[bytes]

   Normalize a secret key value to ``list[bytes]``.

   Accepts:
   - ``bytes``: wrapped in a list
   - ``str``: split on ``":"`` delimiter, each part encoded to UTF-8
   - ``list[bytes]``: each element validated for minimum length
   - ``list[str]``: each element (or colon-delimited parts) encoded to UTF-8

   Each resulting key must be at least ``_HMAC_MIN_KEY_BYTES`` bytes long.

   :raises TypeError: if ``key`` or any element is not ``bytes`` or ``str``.
   :raises ValueError: if any resulting key is shorter than ``_HMAC_MIN_KEY_BYTES``.


.. py:class:: PickleFileBackend

   Bases: :py:obj:`fleche.storage.file.FileStorage`


   Store values as files on the filesystem using a serialization module.


   .. py:attribute:: secret_key
      :type:  list[bytes]
      :value: []



   .. py:attribute:: dumps
      :type:  Callable


   .. py:attribute:: loads
      :type:  Callable


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



   .. py:method:: __post_init__()


   .. py:method:: with_pickle(*args, **kwargs)
      :classmethod:


      Construct a PickleFileBackend using the standard pickle module.



   .. py:method:: with_cloudpickle(*args, **kwargs)
      :classmethod:


      Construct a PickleFileBackend using the cloudpickle module.



   .. py:method:: with_dill(*args, **kwargs)
      :classmethod:


      Construct a PickleFileBackend using the dill module.



   .. py:method:: _to_file(value: Any, path: pathlib.Path) -> None


   .. py:method:: _from_file(path: pathlib.Path) -> Any


.. py:class:: ValuePickleFile

   Bases: :py:obj:`fleche.storage.base.ValueMixin`, :py:obj:`fleche.storage.destructuring.DestructuringMixin`, :py:obj:`PickleFileBackend`


   Bridges :class:`ValueStorage` with :class:`StorageBackend` primitives.

   Implements ``save`` and ``load`` using ``put`` and ``get``.
   Concrete classes inherit from this and a :class:`StorageBackend`
   implementation to get a fully functional value storage.


.. py:class:: CallPickleFile

   Bases: :py:obj:`fleche.storage.base.CallMixin`, :py:obj:`PickleFileBackend`


   Bridges :class:`CallStorage` with :class:`StorageBackend` primitives.

   Implements ``save``, ``load``, and ``query`` using ``put`` and ``get``,
   deriving the storage key from the call's lookup key.  ``transform`` is
   inherited from :class:`CallStorage`.

   Concrete classes inherit from this and a :class:`StorageBackend`
   implementation to get a fully functional call storage.