persidict 0.34.1__py3-none-any.whl → 0.34.3__py3-none-any.whl

persidict/safe_str_tuple_signing.py

@@ -1,12 +1,19 @@
-"""Functions for signing and unsigning SafeStrTuples.
-
-Two functions from this module allow to add and remove
-hash signature suffixes to/from all strings in a SafeStrTuple:
-sign_safe_str_tuple() and unsign_safe_str_tuple().
-
-The suffixes are used to ensure correct work of persistent dictionaries
-(which employ SafeStrTuple-s as keys) with case-insensitive filesystems,
-e.g. MacOS HFS.
+"""Sign and unsign SafeStrTuple elements with deterministic suffixes.
+
+This module provides helpers to add or remove short, deterministic hash
+suffixes to every string element of a SafeStrTuple. These suffixes are used
+to avoid collisions on case-insensitive filesystems (e.g., macOS HFS) while
+keeping keys stable and portable.
+
+Functions:
+    sign_safe_str_tuple(str_seq, digest_len):
+        Return a new SafeStrTuple where each element is suffixed with an
+        underscore and a base32-encoded MD5 digest fragment of length
+        ``digest_len``. If a correct suffix is already present, it is not
+        duplicated.
+    unsign_safe_str_tuple(str_seq, digest_len):
+        Return a new SafeStrTuple where a previously added suffix of length
+        ``digest_len`` is removed from each element, when detected.
 """
 
 import base64
@@ -14,8 +21,20 @@ import hashlib
 from .safe_str_tuple import SafeStrTuple
 
 
-def _create_signature_suffix(input_str:str, digest_len:int) -> str:
-    """ Create a hash signature suffix for a string."""
+def _create_signature_suffix(input_str: str, digest_len: int) -> str:
+    """Create a short, deterministic hash suffix for a string.
+
+    The suffix format is ``_<b32(md5(input))[:digest_len].lower()>``. For
+    ``digest_len == 0`` an empty string is returned.
+
+    Args:
+        input_str: Input string to sign.
+        digest_len: Number of base32 characters from the MD5 digest to include.
+            Must be non-negative. A value of 0 disables suffixing.
+
+    Returns:
+        str: The computed suffix to append (may be an empty string).
+    """
 
     assert isinstance(input_str, str)
     assert isinstance(digest_len, int)
@@ -32,8 +51,20 @@ def _create_signature_suffix(input_str:str, digest_len:int) -> str:
     return suffix
 
 
-def _add_signature_suffix_if_absent(input_str:str, digest_len:int) -> str:
-    """ Add a hash signature suffix to a string if it's not there."""
+def _add_signature_suffix_if_absent(input_str: str, digest_len: int) -> str:
+    """Add the hash signature suffix if it's not already present.
+
+    If the input already ends with the exact suffix calculated from its
+    unsuffixed part, it is returned unchanged.
+
+    Args:
+        input_str: The string to sign.
+        digest_len: Length of the digest fragment to use; 0 leaves the string
+            unchanged.
+
+    Returns:
+        str: The original or suffixed string.
+    """
 
     assert isinstance(input_str, str)
     assert isinstance(digest_len, int)
@@ -52,10 +83,18 @@ def _add_signature_suffix_if_absent(input_str:str, digest_len:int) -> str:
 
 
 def _add_all_suffixes_if_absent(
-        str_seq:SafeStrTuple
-        ,digest_len:int
+        str_seq: SafeStrTuple,
+        digest_len: int,
         ) -> SafeStrTuple:
-    """Add hash signature suffixes to all strings in a SafeStrTuple."""
+    """Return a new SafeStrTuple with suffixes added to each element.
+
+    Args:
+        str_seq: Input sequence convertible to SafeStrTuple.
+        digest_len: Digest fragment length; 0 results in a no-op.
+
+    Returns:
+        SafeStrTuple: The suffixed sequence.
+    """
 
     str_seq = SafeStrTuple(str_seq)
 
@@ -68,8 +107,21 @@ def _add_all_suffixes_if_absent(
     return new_seq
 
 
-def _remove_signature_suffix_if_present(input_str:str, digest_len:int) -> str:
-    """ Remove a hash signature suffix from a string if it's detected."""
+def _remove_signature_suffix_if_present(input_str: str, digest_len: int) -> str:
+    """Remove the hash signature suffix if it is detected.
+
+    Detection is performed by recomputing the expected suffix from the
+    unsuffixed portion and comparing it to the current ending.
+
+    Args:
+        input_str: The possibly suffixed string.
+        digest_len: Digest fragment length used during signing; 0 leaves the
+            string unchanged.
+
+    Returns:
+        str: The original string without the suffix if detected; otherwise the
+        original string.
+    """
 
     assert isinstance(input_str, str)
     assert isinstance(digest_len, int)
@@ -88,10 +140,19 @@ def _remove_signature_suffix_if_present(input_str:str, digest_len:int) -> str:
 
 
 def _remove_all_signature_suffixes_if_present(
-        str_seq:SafeStrTuple
-        , digest_len:int
+        str_seq: SafeStrTuple,
+        digest_len: int,
         ) -> SafeStrTuple:
-    """Remove hash signature suffixes from all strings in a SafeStrTuple."""
+    """Return a new SafeStrTuple with detected suffixes removed from elements.
+
+    Args:
+        str_seq: Input sequence convertible to SafeStrTuple.
+        digest_len: Digest fragment length used during signing; 0 results in a
+            no-op.
+
+    Returns:
+        SafeStrTuple: The unsigned sequence.
+    """
 
     str_seq = SafeStrTuple(str_seq)
 
@@ -108,10 +169,22 @@ def _remove_all_signature_suffixes_if_present(
     return new_seq
 
 
-def sign_safe_str_tuple(str_seq:SafeStrTuple
-                        , digest_len:int
+def sign_safe_str_tuple(
+                        str_seq: SafeStrTuple,
+                        digest_len: int,
                         ) -> SafeStrTuple:
-    """Add hash signature suffixes to all strings in a SafeStrTuple."""
+    """Return a SafeStrTuple with signature suffixes added to all elements.
+
+    This is the public function for signing keys used by persistent dicts.
+
+    Args:
+        str_seq: Input sequence convertible to SafeStrTuple.
+        digest_len: Number of characters from the base32 digest to append. Use
+            0 to disable suffixing.
+
+    Returns:
+        SafeStrTuple: The suffixed sequence.
+    """
 
     str_seq = SafeStrTuple(str_seq)
 
@@ -120,10 +193,20 @@ def sign_safe_str_tuple(str_seq:SafeStrTuple
     return str_seq
 
 
-def unsign_safe_str_tuple(str_seq:SafeStrTuple
-                          , digest_len:int
+def unsign_safe_str_tuple(
+                          str_seq: SafeStrTuple,
+                          digest_len: int,
                           ) -> SafeStrTuple:
-    """Remove hash signature suffixes from all strings in a SafeStrTuple."""
+    """Return a SafeStrTuple with detected signature suffixes removed.
+
+    Args:
+        str_seq: Input sequence convertible to SafeStrTuple.
+        digest_len: Number of characters that were appended during signing. Use
+            0 for a no-op.
+
+    Returns:
+        SafeStrTuple: The unsigned sequence.
+    """
 
     str_seq = SafeStrTuple(str_seq)
 

persidict/write_once_dict.py

@@ -16,11 +16,20 @@ from typing import Any
 import joblib.hashing
 from .persi_dict import PersiDictKey
 
-def _get_md5_signature(x:Any) -> str:
-    """Return base16 MD5 hash signature of an object.
+def _get_md5_signature(x: Any) -> str:
+    """Compute an MD5 signature for an arbitrary Python object.
 
-    Uses joblib's Hasher (or NumpyHasher). It uses Pickle for serialization,
-    except for NumPy arrays, which use optimized custom routines.
+    Uses joblib's Hasher (or NumpyHasher when NumPy is available). joblib
+    relies on Pickle for serialization, except for NumPy arrays which are
+    handled by optimized routines. The resulting digest is returned as a
+    lower-case base16 string.
+
+    Args:
+        x: Any serializable Python object. NumPy arrays are supported with
+            specialized hashing.
+
+    Returns:
+        str: The base16 MD5 hash of the object.
     """
     if 'numpy' in sys.modules:
         hasher = joblib.hashing.NumpyHasher(hash_name='md5')
@@ -30,12 +39,26 @@ def _get_md5_signature(x:Any) -> str:
     return str(hash_signature)
 
 class WriteOnceDict(PersiDict):
-    """ A dictionary that always keeps the first value assigned to a key.
-
-    If a key is already set, it randomly checks the value against the value
-    that was first set. If the new value is different, it raises a
-    ValueError exception. Once can control the frequency of these checks
-    or even completely disable them by setting `p_consistency_checks` to 0.
+    """Dictionary wrapper that preserves the first value written for each key.
+
+    Subsequent writes to an existing key are allowed but ignored as they are
+    expected to have exactly the same value. They are randomly checked
+    against the original value to ensure consistency. If a randomly triggered
+    check finds a difference, a ValueError is raised. The probability of
+    performing a check is controlled by ``p_consistency_checks``.
+
+    This is useful in concurrent or distributed settings where the same value
+    is assumed to be assigned repeatedly to the same key,
+    and you want to check this assumption (detect divergent values)
+    without paying the full cost of always comparing values.
+
+    Attributes:
+        p_consistency_checks (float): Probability in [0, 1] of performing a
+            consistency check for a key that has been previously set.
+        consistency_checks_attempted (int): Number of checks that were
+            attempted.
+        consistency_checks_passed (int): Number of checks that succeeded.
+        consistency_checks_failed (int): Derived as attempted - passed.
 
     """
     _wrapped_dict: PersiDict
@@ -43,18 +66,31 @@ class WriteOnceDict(PersiDict):
     _consistency_checks_attempted: int
     _consistency_checks_passed: int
 
-    def __init__(self
-                 , wrapped_dict:PersiDict | None = None
-                 , p_consistency_checks: float | None=None):
+    def __init__(self,
+                 wrapped_dict: PersiDict | None = None,
+                 p_consistency_checks: float | None = None):
+        """Initialize a WriteOnceDict.
+
+        Args:
+            wrapped_dict: The underlying persistent dictionary to wrap. If not
+                provided, a FileDirDict with immutable_items=True is created.
+            p_consistency_checks: Probability in [0, 1] to perform a
+                consistency check when a key already exists. ``None`` means 0.0
+                (disabled).
+
+        Raises:
+            AssertionError: If ``wrapped_dict`` is not a PersiDict or does not
+                enforce immutable items.
+        """
         if wrapped_dict is None:
-            wrapped_dict = FileDirDict(immutable_items = True)
+            wrapped_dict = FileDirDict(immutable_items=True)
         assert isinstance(wrapped_dict, PersiDict)
         assert wrapped_dict.immutable_items == True
         self.p_consistency_checks = p_consistency_checks
-        PersiDict.__init__(self
-            , base_class_for_values=wrapped_dict.base_class_for_values
-            , immutable_items=True
-            , digest_len=wrapped_dict.digest_len)
+        PersiDict.__init__(self,
+            base_class_for_values=wrapped_dict.base_class_for_values,
+            immutable_items=True,
+            digest_len=wrapped_dict.digest_len)
         self._wrapped_dict = wrapped_dict
         self._consistency_checks_passed = 0
         self._consistency_checks_attempted = 0
@@ -62,12 +98,27 @@ class WriteOnceDict(PersiDict):
 
     @property
     def p_consistency_checks(self) -> float:
-        """ Probability of checking the value against the first value set. """
+        """Probability of checking a new value against the first value stored.
+
+        Returns:
+            float: Probability in [0, 1].
+        """
         return self._p_consistency_checks
 
 
     @p_consistency_checks.setter
-    def p_consistency_checks(self, value: float|None|KeepCurrentFlag) -> None:
+    def p_consistency_checks(self, value: float | None | KeepCurrentFlag) -> None:
+        """Set the probability of performing consistency checks.
+
+        Args:
+            value: Probability in [0, 1]. ``None`` is treated as 0.0.
+                ``KEEP_CURRENT`` can be used only after initialization to
+                preserve the current value.
+
+        Raises:
+            ValueError: If used with ``KEEP_CURRENT`` during initialization or
+                if ``value`` is outside [0, 1].
+        """
         if value is KEEP_CURRENT:
             if hasattr(self, '_p_consistency_checks'):
                 return
@@ -85,34 +136,65 @@ class WriteOnceDict(PersiDict):
 
     @property
     def consistency_checks_failed(self) -> int:
-        """ Returns the number of failed consistency checks. """
-        return self._consistency_checks_attempted - self._consistency_checks_passed
+        """Number of failed consistency checks.
+
+        Returns:
+            int: Failed checks (attempted - passed).
+        """
+        return (self._consistency_checks_attempted
+                - self._consistency_checks_passed)
 
 
     @property
     def consistency_checks_attempted(self) -> int:
-        """ Returns the number of attempted consistency checks. """
+        """Number of attempted consistency checks.
+
+        Returns:
+            int: Attempted checks counter.
+        """
         return self._consistency_checks_attempted
 
 
     @property
     def consistency_checks_passed(self) -> int:
-        """ Returns the number of successful consistency checks. """
+        """Number of successful consistency checks.
+
+        Returns:
+            int: Passed checks counter.
+        """
         return self._consistency_checks_passed
 
 
     def get_params(self):
+        """Return parameterization of this instance.
+
+        Returns:
+            dict: A dictionary with keys 'wrapped_dict' and
+                'p_consistency_checks', sorted by keys for deterministic
+                comparison/serialization.
+        """
         params = dict(
-            wrapped_dict = self._wrapped_dict,
-            p_consistency_checks = self.p_consistency_checks)
+            wrapped_dict=self._wrapped_dict,
+            p_consistency_checks=self.p_consistency_checks)
         sorted_params = sort_dict_by_keys(params)
         return sorted_params
 
-    def __setitem__(self, key, value):
-        """ Set the value of a key if it is not already set.
+    def __setitem__(self, key:PersiDictKey, value):
+        """Set a value for a key, preserving the first assignment.
+
+        If the key is new, the value is stored. If the key already exists,
+        a probabilistic consistency check may be performed to ensure the new
+        value matches the originally stored value. If a check is performed and
+        the values differ, a ValueError is raised.
 
-        If the key is already set, it checks the value
-        against the value that was first set.
+        Args:
+            key: key (string or sequence of strings or SafeStrTuple)
+            value: Value to store.
+
+        Raises:
+            KeyError: If the wrapped dict failed to set a new key unexpectedly.
+            ValueError: If a consistency check is triggered and the new value
+                differs from the original value for the key.
         """
         check_needed = False
 
@@ -149,34 +231,91 @@ class WriteOnceDict(PersiDict):
                         + f"which is not allowed. Details here: {diff_dict} ")
                 self._consistency_checks_passed += 1
 
-    def __contains__(self, item):
+    def __contains__(self, item:PersiDictKey):
+        """Check if a key exists in the dictionary.
+
+        Args:
+            item: Key to check.
+
+        Returns:
+            bool: True if the key exists, False otherwise.
+        """
         return item in self._wrapped_dict
 
-    def __getitem__(self, key):
+    def __getitem__(self, key:PersiDictKey):
+        """Retrieve a value by key.
+
+        Args:
+            key: Key to look up.
+
+        Returns:
+            Any: Stored value.
+        """
         return self._wrapped_dict[key]
 
     def __len__(self):
+        """Return the number of items stored.
+
+        Returns:
+            int: Number of key-value pairs.
+        """
         return len(self._wrapped_dict)
 
-    def _generic_iter(self, iter_type: str):
+    def _generic_iter(self, iter_type: set[str]):
+        """Delegate iteration to the wrapped dict.
+
+        Args:
+            iter_type: tType of iterator: 'items' and/or 'keys' and/or 'timestamps'.
+
+        Returns:
+            Any: Iterator from the wrapped dictionary.
+        """
         return self._wrapped_dict._generic_iter(iter_type)
 
-    def timestamp(self, key:PersiDictKey) -> float:
+    def timestamp(self, key: PersiDictKey) -> float:
+        """Return the timestamp for a given key.
+
+        Args:
+            key: Key for which to retrieve the timestamp.
+
+        Returns:
+            float: POSIX timestamp (seconds since epoch) of the item's last
+                modification as tracked by the wrapped dict.
+        """
         return self._wrapped_dict.timestamp(key)
 
     def __getattr__(self, name):
-        # Forward attribute access to the wrapped object
+        """Forward attribute access to the wrapped object.
+
+        Args:
+            name: Attribute name.
+
+        Returns:
+            Any: Attribute value from the wrapped dict.
+        """
         return getattr(self._wrapped_dict, name)
 
     @property
     def base_dir(self):
+        """Base directory of the wrapped dict (if applicable)."""
         return self._wrapped_dict.base_dir
 
     @property
     def base_url(self):
+        """Base URL of the wrapped dict (if applicable)."""
         return self._wrapped_dict.base_url
 
-    def get_subdict(self, prefix_key:PersiDictKey) -> WriteOnceDict:
+    def get_subdict(self, prefix_key: PersiDictKey) -> WriteOnceDict:
+        """Return a WriteOnceDict view over a sub-keyspace.
+
+        Args:
+            prefix_key: Prefix identifying the sub-dictionary.
+
+        Returns:
+            WriteOnceDict: A new WriteOnceDict wrapping the corresponding
+                sub-dictionary of the underlying store, sharing the same
+                p_consistency_checks probability.
+        """
         subdict = self._wrapped_dict.get_subdict(prefix_key)
         result = WriteOnceDict(subdict, self.p_consistency_checks)
         return result

{persidict-0.34.1.dist-info → persidict-0.34.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.34.1
+Version: 0.34.3
 Summary: Simple persistent key-value store for Python. Values are stored as files on a disk or as S3 objects on AWS cloud.
 Keywords: persistence,dicts,distributed,parallel
 Author: Vlad (Volodymyr) Pavlov
@@ -158,10 +158,9 @@ that simultaneously work with the same instance of a dictionary.
 * Insertion order is not preserved.
 * You cannot assign initial key-value pairs to a dictionary in its constructor.
 * `PersiDict` API has additional methods `delete_if_exists()`, `timestamp()`,
-`get_subdict()`, `subdicts()`, `random_keys()`, `newest_keys()`, 
-`oldest_keys()`, `newest_values()`, `oldest_values()`, 
-`get_params()`, `get_metaparams()`, and `get_default_metaparams()`,
-which are not available in native Python dicts.
+`get_subdict()`, `subdicts()`, `random_key()`, `newest_keys()`, 
+`oldest_keys()`, `newest_values()`, `oldest_values()`, and
+`get_params()`, which are not available in native Python dicts.
 * You can use KEEP_CURRENT constant as a fake new value 
 to avoid actually setting/updating a value. Or DELETE_CURRENT as 
 a fake new value to delete the previous value from a dictionary.

persidict-0.34.3.dist-info/RECORD

@@ -0,0 +1,13 @@
+persidict/__init__.py,sha256=CDOSJGgCnyRTkGUTzaeg3Cqsxwx0-0EFieOtldXwAls,1380
+persidict/file_dir_dict.py,sha256=Lf65HqI00J7Pi2jELWEXo5DUk8cW1GdKdgkVyFgFHGo,25135
+persidict/jokers.py,sha256=H2MzKllvgm7t2sjX3GaRNLngOiG2ohE-lv0B3g3J1SQ,2710
+persidict/overlapping_multi_dict.py,sha256=ZUbkNConqUDTP1LFxKv0WFvsAPcCiHUjhNKe8912wNs,5112
+persidict/persi_dict.py,sha256=mwHng2pjXf_durHKeiTZRDOVJbpHjANkdVR1_y2Bs4E,19408
+persidict/s3_dict.py,sha256=Xl-ZOukY7dl-LkujaPiPNVZo9sK9t5bFhG2lCYLAbjs,20635
+persidict/safe_chars.py,sha256=9Qy24fu2dmiJOdmCF8mKZULfQaRp7H4oxfgDXeLgogI,1160
+persidict/safe_str_tuple.py,sha256=4wt3Jfd7efKczTP1o--XkOSic5_7riVDIgnK19Bzfbk,6741
+persidict/safe_str_tuple_signing.py,sha256=ihV1hLx24N9f64nFbqAvbnsPZDon-kUAVncs1628Q6M,6428
+persidict/write_once_dict.py,sha256=5tGqm51EIEcjnAhP8oOY-eQ1AaQhteQxSd0SPIp934c,11217
+persidict-0.34.3.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
+persidict-0.34.3.dist-info/METADATA,sha256=nXLxLxK2mZ7NmVfRu6H--W8hVNJOQZl1lAs1mbkALXQ,9262
+persidict-0.34.3.dist-info/RECORD,,

persidict-0.34.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-persidict/.DS_Store,sha256=1lFlJ5EFymdzGAUAaI30vcaaLHt3F1LwpG7xILf9jsM,6148
-persidict/__init__.py,sha256=CDOSJGgCnyRTkGUTzaeg3Cqsxwx0-0EFieOtldXwAls,1380
-persidict/file_dir_dict.py,sha256=Dr4gdIC5uqykRgNca1pI_M_jEd_9FGjys0BvzAJR0JU,17804
-persidict/jokers.py,sha256=kX4bE-jKWTM2ki7JOmm_2uJS8zm8u6InZ_V12xo2ImI,1436
-persidict/overlapping_multi_dict.py,sha256=a-lUbmY15_HrDq6jSIt8F8tJboqbeYiuRQeW4elf_oU,2663
-persidict/persi_dict.py,sha256=SF6aWs6kCeeW-bZ9HJwx0sPX7Xav_aURqeSZ-j5quv0,14266
-persidict/s3_dict.py,sha256=fzU3GKKNor6WRoIpP_-7d8ckO4eyhBOOo5kbpsmdxQA,15434
-persidict/safe_chars.py,sha256=HjK1MwROYy_U9ui-rhg1i3nGkj52K4OFWD-wCCcnJ7Y,536
-persidict/safe_str_tuple.py,sha256=xyIzxlCKmvnNHkFFKWtcBREefxZ0-HLxoH_epYDt8qg,3719
-persidict/safe_str_tuple_signing.py,sha256=5uCjAVZRqOou-KpDZw-Exboc3-3vuayJMqrrt8aZ0ck,3742
-persidict/write_once_dict.py,sha256=-XHQhTEdvPHTKqLXK4WWW0k5cFitkzalVJC1n4BbKGo,6496
-persidict-0.34.1.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
-persidict-0.34.1.dist-info/METADATA,sha256=a6o3joH0aBP1HEWHYxJgKn8KkktLA79TLenbkuttITM,9312
-persidict-0.34.1.dist-info/RECORD,,