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

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


Attributes
----------

.. autoapisummary::

   fleche.storage.pickle_file.logger


Classes
-------

.. autoapisummary::

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


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

.. py:data:: logger

.. 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:  tuple[bytes, Ellipsis]
      :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:method:: _rewrite_all(transform: Callable[[bytes], bytes | None]) -> None

      Lock, read, and conditionally rewrite every stored file via *transform*.

      *transform* receives the raw file bytes and returns the new bytes to
      write, or ``None`` to leave the file unchanged.



   .. py:method:: compress_all() -> None

      Rewrite all stored files in gzip-compressed form.



   .. py:method:: decompress_all() -> None

      Rewrite all stored files in uncompressed form.



.. py:class:: ValuePickleFile

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


   Mixin that locks per-key so concurrent ops on different keys proceed in parallel.

   A lightweight ``threading.Lock`` guards the lock-table itself; once the
   per-key ``RLock`` is obtained the table lock is released, so two threads
   operating on *different* keys never block each other.  Operations on the
   *same* key are serialized by the per-key lock, which is reentrant to
   allow nested calls (e.g. ``expand`` inside ``load``).

   Instances must be hashable.  Place before the concrete storage class in the
   MRO::

       @dataclass(frozen=True)
       class PerKeyValuePickle(PerKeyLockMixin, ValuePickleFile): ...


.. py:class:: CallPickleFile

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


   Mixin that locks per-key so concurrent ops on different keys proceed in parallel.

   A lightweight ``threading.Lock`` guards the lock-table itself; once the
   per-key ``RLock`` is obtained the table lock is released, so two threads
   operating on *different* keys never block each other.  Operations on the
   *same* key are serialized by the per-key lock, which is reentrant to
   allow nested calls (e.g. ``expand`` inside ``load``).

   Instances must be hashable.  Place before the concrete storage class in the
   MRO::

       @dataclass(frozen=True)
       class PerKeyValuePickle(PerKeyLockMixin, ValuePickleFile): ...