persidict 0.105.4__tar.gz → 0.105.5__tar.gz

{persidict-0.105.4 → persidict-0.105.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.105.4
+Version: 0.105.5
 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

{persidict-0.105.4 → persidict-0.105.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "persidict"
-version = "0.105.4"
+version = "0.105.5"
 description = "Simple persistent key-value store for Python. Values are stored as files on a disk or as S3 objects on AWS cloud."
 readme = "README.md"
 requires-python = ">=3.10"

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/__init__.py

@@ -4,6 +4,7 @@ This package provides a unified interface for persistent dictionary-like
 storage with various backends including filesystem and AWS S3.
 
 Classes:
+
     PersiDict: Abstract base class defining the unified interface for all
         persistent dictionaries.
     NonEmptySafeStrTuple: A flat tuple of URL/filename-safe strings that
@@ -11,24 +12,30 @@ Classes:
     FileDirDict: A dictionary that stores key-value pairs as files on a
         local hard drive. Keys compose filenames, values are stored as
         pickle or JSON objects.
+
     BasicS3Dict: A basic S3-backed dictionary with direct S3 operations.
+
     WriteOnceDict: A write-once wrapper that prevents modification of existing
         items after initial storage.
     EmptyDict: Equivalent of null device in OS - accepts all writes but discards
         them, returns nothing on reads. Always appears empty regardless of
         operations performed. Useful for testing, debugging, or as a placeholder.
+
     OverlappingMultiDict: A dictionary that can handle overlapping key spaces.
 
 Functions:
+
     get_safe_chars(): Returns a set of URL/filename-safe characters permitted
         in keys.
     replace_unsafe_chars(): Replaces forbidden characters in a string with
         safe alternatives.
 
 Constants:
+
     KEEP_CURRENT, DELETE_CURRENT: Special joker values for conditional operations.
 
 Note:
+
     All persistent dictionaries support multiple serialization formats, including
     pickle and JSON, with automatic type handling and collision-safe key encoding.
 """

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/basic_s3_dict.py

@@ -165,7 +165,18 @@ class BasicS3Dict(PersiDict):
 
 
     def etag(self, key:NonEmptyPersiDictKey) -> str|None:
-        """Get an ETag for a key."""
+        """Get an ETag for a key.
+
+        Args:
+            key: Dictionary key (string or sequence of strings
+                or NonEmptySafeStrTuple).
+
+        Returns:
+            str|None: The ETag value for the S3 object, or None if not available.
+
+        Raises:
+            KeyError: If the key does not exist in S3.
+        """
         key = NonEmptySafeStrTuple(key)
         obj_name = self._build_full_objectname(key)
         try:
@@ -590,6 +601,4 @@ class BasicS3Dict(PersiDict):
             if not_found_error(e):
                 raise KeyError(f"Key {key} not found in S3 bucket {self.bucket_name}")
             else:
-                raise
-
-# parameterizable.register_parameterizable_class(BasicS3Dict)
+                raise

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/cached_appendonly_dict.py

@@ -1,3 +1,23 @@
+"""Read-through cached, append-only persistent dictionary adapter.
+
+This module provides `AppendOnlyDictCached`, an append-only facade that
+combines two concrete `PersiDict` implementations:
+
+- `main_dict`: the authoritative store (source of truth) where data is
+  actually persisted;
+- `data_cache`: a secondary `PersiDict` that is used strictly as a cache for
+  values.
+
+Because both backends are append-only (items may be added once and never
+modified or deleted), the cache can be trusted once it has a value for a key.
+Reads go to the cache first and fall back to the main dict on a miss, at which
+point the cache is populated. Writes always go to the main dict first and are
+mirrored to the cache after validation performed by the `PersiDict` base.
+
+The adapter delegates iteration, length, timestamps, and base properties to the
+main dict to keep semantics consistent with the authoritative store.
+"""
+
 from __future__ import annotations
 
 from typing import Any, Optional
@@ -8,40 +28,41 @@ from .singletons import ETAG_HAS_NOT_CHANGED, EXECUTION_IS_COMPLETE
 
 
 class AppendOnlyDictCached(PersiDict):
-    """Append-only dict facade with a read-through cache.
-
-    This adapter wraps two concrete PersiDict instances:
-    - main_dict: the source of truth that actually persists data.
-    - data_cache: a second PersiDict used purely as a cache for values.
+    """Append-only `PersiDict` facade with a read-through cache.
 
-    Both the main dict and the cache must have append_only=True. Keys can
-    be added once but never modified or deleted. Because of that contract, the
-    cache can be trusted when it already has a value for a key without
-    re-validating the main dict.
+    This adapter composes two concrete `PersiDict` instances and presents them
+    as a single append-only mapping. It trusts the cache because both backends
+    are append-only: once a key is written it will never be modified or
+    deleted.
 
     Behavior summary:
-    - Reads: __getitem__ first tries the cache, falls back to the main dict and
-      populates the cache on a miss.
-    - Membership: __contains__ returns True if the key is in the cache; else it
-      checks the main dict.
-    - Writes: __setitem__ writes to the main dict and mirrors the value into
-      the cache after argument validation by the PersiDict base.
-    - set_item_get_etag delegates the write to the main dict, mirrors the value
-      into the cache, and returns the ETag from the main dict.
-    - Deletion is not supported and will raise TypeError (append-only).
-    - Iteration, length, timestamps, base_url and base_dir are delegated to the
-      main dict. get_item_if_new_etag is delegated too, and on change the
-      value is cached.
+
+    - Reads: `__getitem__` first tries the cache, falls back to the main dict,
+      then populates the cache on a miss.
+    - Membership: `__contains__` returns True immediately if the key is in the
+      cache; otherwise it checks the main dict.
+    - Writes: `__setitem__` writes to the main dict and then mirrors the value
+      into the cache (after base validation performed by `PersiDict`).
+    - `set_item_get_etag`: delegates the write to the main dict, mirrors the
+      value into the cache, and returns the ETag from the main dict.
+    - Deletion: not supported (append-only), will raise `TypeError`.
+    - Iteration/length/timestamps: delegated to the main dict.
+
+    Attributes:
+      _main: The authoritative append-only `PersiDict` instance.
+      _data_cache: The append-only `PersiDict` used purely as a value cache.
 
     Args:
-      main_dict: The authoritative append-only PersiDict.
-      data_cache: A PersiDict used as a value cache; must be append-only and
-        compatible with main_dict's base_class_for_values and serialization_format.
+      main_dict: The authoritative append-only `PersiDict`.
+      data_cache: A `PersiDict` used as a cache; must be append-only and
+        compatible with `main_dict` (same `base_class_for_values` and
+        `serialization_format`).
 
     Raises:
-      TypeError: If main_dict or data_cache are not PersiDict instances.
-      ValueError: If either dict is not immutable (append-only) or their
-        base_class_for_values differ.
+      TypeError: If `main_dict` or `data_cache` are not `PersiDict` instances.
+      ValueError: If either dict is not append-only or their
+        `base_class_for_values` differ.
+
     """
 
     def __init__(self,
@@ -101,7 +122,11 @@ class AppendOnlyDictCached(PersiDict):
             return key in self._main
 
     def __len__(self) -> int:
-        """int: Number of items, delegated to the main dict."""
+        """Return the number of items.
+
+        Returns:
+            int: Number of items in the dictionary, delegated to the main dict.
+        """
         return len(self._main)
 
     def _generic_iter(self, result_type: set[str]):

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/file_dir_dict.py

@@ -809,5 +809,3 @@ class FileDirDict(PersiDict):
             winner = os.path.abspath(winner)
             winner = add_long_path_prefix(winner)
             return self._build_key_from_full_path(winner)
-
-# parameterizable.register_parameterizable_class(FileDirDict)

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/local_dict.py

@@ -497,6 +497,3 @@ class LocalDict(PersiDict):
                          append_only=self.append_only,
                          base_class_for_values=self.base_class_for_values,
                          prune_interval=self._prune_interval)
-
-
-# parameterizable.register_parameterizable_class(LocalDict)

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/s3_dict_file_dir_cached.py

@@ -209,7 +209,4 @@ class S3Dict_FileDirCached(PersiDict):
             return False
 
 
-S3Dict = S3Dict_FileDirCached # Alias for backward compatibility
-
-
-# parameterizable.register_parameterizable_class(S3Dict_FileDirCached)
+S3Dict = S3Dict_FileDirCached # Alias for backward compatibility

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/singletons.py

@@ -18,7 +18,6 @@ Examples:
 from typing import Any
 
 from parameterizable import ParameterizableClass
-    # , register_parameterizable_class)
 
 
 class Singleton(ParameterizableClass):
@@ -140,13 +139,6 @@ class ExecutionIsCompleteFlag(StatusFlag):
     """
     pass
 
-
-# register_parameterizable_class(KeepCurrentFlag)
-# register_parameterizable_class(DeleteCurrentFlag)
-# register_parameterizable_class(ContinueNormalExecutionFlag)
-# register_parameterizable_class(ExecutionIsCompleteFlag)
-# register_parameterizable_class(ETagHasNotChangedFlag)
-
 _KeepCurrent = KeepCurrentFlag()
 KEEP_CURRENT = KeepCurrentFlag()
 """Flag indicating that the current value should be kept unchanged.

{persidict-0.105.4 → persidict-0.105.5}/src/persidict/write_once_dict.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 import time
 
 from deepdiff import DeepDiff
-from parameterizable import sort_dict_by_keys #,register_parameterizable_class
+from parameterizable import sort_dict_by_keys
 
 from .singletons import KEEP_CURRENT, KeepCurrentFlag, ETagHasNotChangedFlag
 from .persi_dict import PersiDict, NonEmptyPersiDictKey
@@ -61,13 +61,6 @@ class WriteOnceDict(PersiDict):
     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
@@ -343,7 +336,4 @@ class WriteOnceDict(PersiDict):
         """
         subdict = self._wrapped_dict.get_subdict(prefix_key)
         result = WriteOnceDict(subdict, self.p_consistency_checks)
-        return result
-
-
-# register_parameterizable_class(WriteOnceDict)
+        return result