persidict 0.36.11__py3-none-any.whl → 0.37.1__py3-none-any.whl

persidict/file_dir_dict.py

@@ -27,8 +27,7 @@ from .jokers import KEEP_CURRENT, DELETE_CURRENT, Joker
 from .safe_chars import replace_unsafe_chars
 from .safe_str_tuple import SafeStrTuple
 from .safe_str_tuple_signing import sign_safe_str_tuple, unsign_safe_str_tuple
-from .persi_dict import PersiDict, PersiDictKey
-
+from .persi_dict import PersiDict, PersiDictKey, non_empty_persidict_key
 
 jsonpickle_numpy.register_handlers()
 jsonpickle_pandas.register_handlers()
@@ -69,6 +68,7 @@ class FileDirDict(PersiDict):
                 or deleted.
             digest_len (int): Length of a hash suffix appended to each key path
                 element to avoid case-insensitive collisions. Use 0 to disable.
+                If you decide to enable it (not 0), we recommend at least 4.
             base_class_for_values (Optional[type]): Optional base class that all
                 stored values must be instances of. If provided and not ``str``,
                 then file_type must be either "pkl" or "json".
@@ -456,7 +456,7 @@ class FileDirDict(PersiDict):
         Returns:
             bool: True if a file for the key exists; False otherwise.
         """
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
         filename = self._build_full_path(key)
         return os.path.isfile(filename)
 
@@ -478,7 +478,7 @@ class FileDirDict(PersiDict):
             TypeError: If the deserialized value does not match base_class_for_values
                 when it is set.
         """
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
         filename = self._build_full_path(key)
         if not os.path.isfile(filename):
             raise KeyError(f"File {filename} does not exist")
@@ -509,28 +509,13 @@ class FileDirDict(PersiDict):
                 base_class_for_values when it is set.
         """
 
-        if value is KEEP_CURRENT:
+        key = non_empty_persidict_key(key)
+        PersiDict.__setitem__(self, key, value)
+        if isinstance(value, Joker):
+            # processed by base class
             return
 
-        if value is DELETE_CURRENT:
-            self.delete_if_exists(key)
-            return
-
-        if isinstance(value, PersiDict):
-            raise TypeError(
-                f"You are not allowed to store a PersiDict "
-                + f"inside another PersiDict.")
-
-        if self.base_class_for_values is not None:
-            if not isinstance(value, self.base_class_for_values):
-                raise TypeError(
-                    f"Value must be of type {self.base_class_for_values},"
-                    + f"but it is {type(value)} instead.")
-
-        key = SafeStrTuple(key)
         filename = self._build_full_path(key, create_subdirs=True)
-        if self.immutable_items and os.path.exists(filename):
-            raise KeyError("Can't modify an immutable item")
         self._save_to_file(filename, value)
 
 
@@ -543,9 +528,7 @@ class FileDirDict(PersiDict):
         Raises:
             KeyError: If immutable_items is True or if the key does not exist.
         """
-        key = SafeStrTuple(key)
-        if self.immutable_items:
-            raise KeyError("Can't delete immutable items")
+        key = non_empty_persidict_key(key)
         filename = self._build_full_path(key)
         if not os.path.isfile(filename):
             raise KeyError(f"File {filename} does not exist")
@@ -574,15 +557,8 @@ class FileDirDict(PersiDict):
             TypeError: If result_type is not a set.
             ValueError: If result_type is empty or contains unsupported labels.
         """
-        if not isinstance(result_type, set):
-            raise TypeError("result_type must be a set")
-        if not (1 <= len(result_type) <= 3):
-            raise ValueError("result_type must be a non-empty subset of {'keys','values','timestamps'}")
-        allowed = {"keys", "values", "timestamps"}
-        invalid = result_type - allowed
-        if invalid:
-            raise ValueError(f"Unsupported result_type entries: {sorted(invalid)}; allowed: {sorted(allowed)}")
 
+        PersiDict._generic_iter(self, result_type)
         walk_results = os.walk(self._base_dir)
         ext_len = len(self.file_type) + 1
 
@@ -649,7 +625,7 @@ class FileDirDict(PersiDict):
         Raises:
             FileNotFoundError: If the key does not exist.
         """
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
         filename = self._build_full_path(key)
         return os.path.getmtime(filename)
 

persidict/jokers.py

@@ -92,8 +92,8 @@ class DeleteCurrentFlag(Joker):
 register_parameterizable_class(KeepCurrentFlag)
 register_parameterizable_class(DeleteCurrentFlag)
 
-KeepCurrent = KeepCurrentFlag()
+_KeepCurrent = KeepCurrentFlag()
 KEEP_CURRENT = KeepCurrentFlag()
 
-DeleteCurrent = DeleteCurrentFlag()
+_DeleteCurrent = DeleteCurrentFlag()
 DELETE_CURRENT = DeleteCurrentFlag()

persidict/persi_dict.py

@@ -4,10 +4,11 @@ PersiDict defines a unified interface for persistent dictionaries. The API is
 similar to Python's built-in dict with some differences (e.g., insertion order
 is not guaranteed) and several additional convenience methods.
 
-Keys are sequences of URL/filename-safe strings represented by SafeStrTuple.
-Plain strings or sequences of strings are accepted and automatically coerced to
-SafeStrTuple. Values can be arbitrary Python objects unless an implementation
-restricts them via ``base_class_for_values``.
+Keys are non-empty sequences of URL/filename-safe strings
+represented by SafeStrTuple. Plain strings or sequences of strings are accepted
+and automatically coerced to SafeStrTuple. Values can be
+arbitrary Python objects unless an implementation restricts them
+via `base_class_for_values`.
 
 Persistence means items are stored durably (e.g., in local files or cloud
 objects) and remain accessible across process lifetimes.
@@ -35,6 +36,24 @@ If a string (or a sequence of strings) is passed to a PersiDict as a key,
 it will be automatically converted into SafeStrTuple.
 """
 
+
+def non_empty_persidict_key(*args) -> SafeStrTuple:
+    """Create a non-empty SafeStrTuple from the given arguments.
+    This is a convenience function that ensures the resulting SafeStrTuple is
+    not empty, raising a KeyError if it is.
+    Args:
+        *args: Arguments to pass to SafeStrTuple constructor.
+    Returns:
+        SafeStrTuple: A non-empty SafeStrTuple instance.
+    Raises:
+        KeyError: If the resulting SafeStrTuple is empty.
+    """
+    result = SafeStrTuple(*args)
+    if len(result) == 0:
+        raise KeyError("Key cannot be empty")
+    return result
+
+
 class PersiDict(MutableMapping, ParameterizableClass):
     """Abstract dict-like interface for durable key-value stores.
 
@@ -100,10 +119,10 @@ class PersiDict(MutableMapping, ParameterizableClass):
                 This supports the Parameterizable API and is absent in the
                 built-in dict.
         """
-        params =  dict(
-            immutable_items=self.immutable_items
-            , digest_len=self.digest_len
-            , base_class_for_values=self.base_class_for_values
+        params = dict(
+            immutable_items=self.immutable_items,
+            digest_len=self.digest_len,
+            base_class_for_values=self.base_class_for_values
         )
         sorted_params = sort_dict_by_keys(params)
         return sorted_params
@@ -168,7 +187,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             bool: True if key exists, False otherwise.
         """
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                        " and cannot check items directly")
 
 
     @abstractmethod
@@ -181,7 +202,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             Any: The stored value.
         """
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                        " and cannot retrieve items directly")
 
 
     def __setitem__(self, key:PersiDictKey, value:Any):
@@ -201,12 +224,24 @@ class PersiDict(MutableMapping, ParameterizableClass):
         """
         if value is KEEP_CURRENT:
             return
-        elif value is DELETE_CURRENT:
-            self.delete_if_exists(key)
         elif self.immutable_items:
             if key in self:
                 raise KeyError("Can't modify an immutable key-value pair")
-        raise NotImplementedError
+
+        key = non_empty_persidict_key(key)
+
+        if value is DELETE_CURRENT:
+            self.delete_if_exists(key)
+            return
+
+        if self.base_class_for_values is not None:
+            if not isinstance(value, self.base_class_for_values):
+                raise TypeError(f"Value must be an instance of"
+                                f" {self.base_class_for_values.__name__}")
+
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                      " and cannot store items directly")
 
 
     def __delitem__(self, key:PersiDictKey):
@@ -221,7 +256,14 @@ class PersiDict(MutableMapping, ParameterizableClass):
         """
         if self.immutable_items:
             raise KeyError("Can't delete an immutable key-value pair")
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                      " and cannot delete items directly")
+
+        key = non_empty_persidict_key(key)
+
+        if key not in self:
+            raise KeyError(f"Key {key} not found")
 
 
     @abstractmethod
@@ -231,7 +273,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             int: Number of key-value pairs.
         """
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                        " and cannot count items directly")
 
 
     @abstractmethod
@@ -260,7 +304,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
             raise ValueError("result_type can only contain 'keys', 'values', 'timestamps'")
         if not (1 <= len(result_type & allowed) <= 3):
             raise ValueError("result_type must include at least one of 'keys', 'values', 'timestamps'")
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                        " and cannot iterate items directly")
 
 
     def __iter__(self):
@@ -278,7 +324,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             Iterator[SafeStrTuple]: Keys iterator.
         """
-        return  self._generic_iter({"keys"})
+        return self._generic_iter({"keys"})
 
 
     def keys_and_timestamps(self):
@@ -385,7 +431,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Raises:
             TypeError: Always raised; PersiDict instances are not pickleable.
         """
-        raise TypeError("PersiDict is not picklable.")
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                      " and cannot be pickled directly")
 
 
     def __setstate__(self, state):
@@ -394,7 +442,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Raises:
             TypeError: Always raised; PersiDict instances are not pickleable.
         """
-        raise TypeError("PersiDict is not picklable.")
+        if type(self) is PersiDict:
+            raise TypeError("PersiDict is an abstract base class"
+                            " and cannot be unpickled directly")
 
 
     def clear(self) -> None:
@@ -409,7 +459,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         for k in self.keys():
             try:
                 del self[k]
-            except:
+            except KeyError:
                 pass
 
 
@@ -431,7 +481,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         if self.immutable_items:
             raise KeyError("Can't delete an immutable key-value pair")
 
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
 
         if key in self:
             try:
@@ -464,7 +514,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
             NotImplementedError: Must be implemented by subclasses that support
                 hierarchical key spaces.
         """
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                " and cannot create sub-dictionaries directly")
 
 
     def subdicts(self) -> dict[str, PersiDict]:
@@ -528,7 +580,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Raises:
             NotImplementedError: Must be implemented by subclasses.
         """
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                      " and cannot provide timestamps directly")
 
 
     def oldest_keys(self, max_n=None):
@@ -553,9 +607,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
             return []
         else:
             # Use heapq.nsmallest for efficient partial sorting without loading all keys into memory
-            smallest_pairs = heapq.nsmallest(max_n
-                                             , self.keys_and_timestamps()
-                                             , key=lambda x: x[1])
+            smallest_pairs = heapq.nsmallest(max_n,
+                                             self.keys_and_timestamps(),
+                                             key=lambda x: x[1])
             return [key for key,_ in smallest_pairs]
 
 
@@ -591,15 +645,15 @@ class PersiDict(MutableMapping, ParameterizableClass):
         if max_n is None:
             # If we need all keys, sort them all by timestamp in reverse order
             key_timestamp_pairs = list(self.keys_and_timestamps())
-            key_timestamp_pairs.sort(key=lambda x:x[1], reverse=True)
+            key_timestamp_pairs.sort(key=lambda x: x[1], reverse=True)
             return [key for key,_ in key_timestamp_pairs]
         elif max_n <= 0:
             return []
         else:
             # Use heapq.nlargest for efficient partial sorting without loading all keys into memory
-            largest_pairs = heapq.nlargest(max_n
-                                            , self.keys_and_timestamps()
-                                            , key=lambda item: item[1])
+            largest_pairs = heapq.nlargest(max_n,
+                                           self.keys_and_timestamps(),
+                                           key=lambda item: item[1])
             return [key for key,_ in largest_pairs]
 
 

persidict/s3_dict.py

@@ -15,26 +15,30 @@ from parameterizable.dict_sorter import sort_dict_by_keys
 from .safe_str_tuple import SafeStrTuple
 from .safe_str_tuple_signing import sign_safe_str_tuple, unsign_safe_str_tuple
 from .persi_dict import PersiDict
-from .jokers import KEEP_CURRENT, DELETE_CURRENT
-from .file_dir_dict import FileDirDict, PersiDictKey
+from .jokers import KEEP_CURRENT, DELETE_CURRENT, Joker
+from .file_dir_dict import FileDirDict, PersiDictKey, non_empty_persidict_key
 from .overlapping_multi_dict import OverlappingMultiDict
 
 S3DICT_DEFAULT_BASE_DIR = "__s3_dict__"
 
 class S3Dict(PersiDict):
-    """ A persistent dictionary that stores key-value pairs as S3 objects.
-
-    A new object is created for each key-value pair.
-
-    A key is either an objectname (a 'filename' without an extension),
-    or a sequence of folder names (object name prefixes) that ends
-    with an objectname. A value can be an instance of any Python type,
-    and will be stored as an S3-object.
-
-    S3Dict can store objects in binary objects (as pickles)
-    or in human-readable texts objects (using jsonpickles).
-
-    Unlike in native Python dictionaries, insertion order is not preserved.
+    """A persistent dictionary that stores key-value pairs as S3 objects.
+    
+    Each key-value pair is stored as a separate S3 object in the specified bucket.
+    
+    A key can be either a string (object name without file extension) or a sequence
+    of strings representing a hierarchical path (folder structure ending with an
+    object name). Values can be instances of any Python type and are serialized
+    to S3 objects.
+    
+    S3Dict supports multiple serialization formats:
+    - Binary storage using pickle ('pkl' format)  
+    - Human-readable text using jsonpickle ('json' format)
+    - Plain text for string values (other formats)
+    
+    Note:
+        Unlike native Python dictionaries, insertion order is not preserved.
+        Operations may incur S3 API costs and network latency.
     """
     region: str
     bucket_name: str
@@ -42,40 +46,47 @@ class S3Dict(PersiDict):
     file_type: str
     _base_dir: str
 
-    def __init__(self, bucket_name:str = "my_bucket"
-                 , region:str = None
-                 , root_prefix:str = ""
-                 , base_dir:str = S3DICT_DEFAULT_BASE_DIR
-                 , file_type:str = "pkl"
-                 , immutable_items:bool = False
-                 , digest_len:int = 8
-                 , base_class_for_values:Optional[type] = None
-                 ,*args ,**kwargs):
+    def __init__(self, bucket_name: str = "my_bucket",
+                 region: str = None,
+                 root_prefix: str = "",
+                 base_dir: str = S3DICT_DEFAULT_BASE_DIR,
+                 file_type: str = "pkl",
+                 immutable_items: bool = False,
+                 digest_len: int = 8,
+                 base_class_for_values: Optional[type] = None,
+                 *args, **kwargs):
         """Initialize an S3-backed persistent dictionary.
 
         Args:
-            bucket_name (str): Name of the S3 bucket to use. The bucket will be
-                created if it does not already exist.
-            region (str | None): AWS region of the bucket. If None, the default
-                client region is used.
-            root_prefix (str): Common S3 key prefix under which all objects are
-                stored. A trailing slash is added if missing.
-            base_dir (str): Local directory used for temporary files and a
-                small on-disk cache.
-            file_type (str): Extension/format for stored values. "pkl" or
-                "json" store arbitrary Python objects; other values imply plain
-                text and only allow str values.
-            immutable_items (bool): If True, disallow changing existing items.
-            digest_len (int): Number of base32 MD5 characters appended to key
-                elements to avoid case-insensitive collisions. Use 0 to disable.
-            base_class_for_values (type | None): Optional base class that all
-                values must inherit from. If provided and not str, file_type
-                must be "pkl" or "json".
-            *args: Ignored; reserved for compatibility.
-            **kwargs: Ignored; reserved for compatibility.
+            bucket_name: Name of the S3 bucket to use. The bucket will be
+                created automatically if it does not exist and permissions allow.
+            region: AWS region for the bucket. If None, uses the default
+                client region from AWS configuration.
+            root_prefix: Common S3 key prefix under which all objects are
+                stored. A trailing slash is automatically added if missing.
+            base_dir: Local directory path used for temporary files and
+                local caching of S3 objects.
+            file_type: File extension/format for stored values. Supported formats:
+                'pkl' (pickle), 'json' (jsonpickle), or custom text formats.
+            immutable_items: If True, prevents modification of existing items
+                after they are initially stored.
+            digest_len: Number of base32 MD5 hash characters appended to key
+                elements to prevent case-insensitive filename collisions. 
+                Set to 0 to disable collision prevention.
+            base_class_for_values: Optional base class that all stored values
+                must inherit from. When specified (and not str), file_type
+                must be 'pkl' or 'json' for proper serialization.
+            *args: Additional positional arguments (ignored, reserved for compatibility).
+            **kwargs: Additional keyword arguments (ignored, reserved for compatibility).
+            
+        Note:
+            The S3 bucket will be created if it doesn't exist and AWS permissions
+            allow. Network connectivity and valid AWS credentials are required.
         """
 
-        super().__init__(immutable_items = immutable_items, digest_len = digest_len)
+        super().__init__(immutable_items = immutable_items
+                         , digest_len = digest_len
+                         , base_class_for_values=base_class_for_values)
         self.file_type = file_type
         self.etag_file_type = f"{file_type}_etag"
 
@@ -107,24 +118,25 @@ class S3Dict(PersiDict):
         except ClientError as e:
             error_code = e.response['Error']['Code']
             if error_code == '404' or error_code == 'NotFound':
-                # The bucket does not exist, so attempt to create it.
+                # Bucket does not exist, attempt to create it
                 try:
                     self.s3_client.create_bucket(Bucket=bucket_name)
                 except ClientError as create_e:
                     create_error_code = create_e.response['Error']['Code']
-                    # Handles the race condition and the bucket-is-taken error
+                    # Handle race condition where bucket was created by another process
+                    # or the bucket name is already taken by another AWS account
                     if ( create_error_code == 'BucketAlreadyOwnedByYou'
                         or create_error_code == 'BucketAlreadyExists'):
                         pass
                     else:
-                        raise create_e  # Re-raise other unexpected creation errors.
+                        raise create_e  # Re-raise other unexpected creation errors
             elif error_code == '403' or error_code == 'Forbidden':
-                # The bucket exists, but access is forbidden.
-                # This is likely a cross-account bucket with a policy that grants
-                # access to you. Subsequent calls will fail if permissions are not granted.
+                # Bucket exists but access is forbidden - likely a cross-account
+                # bucket with policy granting limited access. Operations may still
+                # work if the policy allows the required S3 permissions.
                 pass
             else:
-                raise e  # Re-raise other unexpected ClientErrors on head_bucket.
+                raise e  # Re-raise other unexpected head_bucket errors
 
         self.bucket_name = bucket_name
 
@@ -134,15 +146,15 @@ class S3Dict(PersiDict):
 
 
     def get_params(self):
-        """Return configuration parameters of the object as a dictionary.
+        """Return configuration parameters as a dictionary.
 
-        This method is needed to support Parameterizable API.
-        The method is absent in the original dict API.
+        This method supports the Parameterizable API and is not part of
+        the standard Python dictionary interface.
 
         Returns:
             dict: A mapping of parameter names to their configured values,
-            including region, bucket_name, and root_prefix combined with
-            parameters from the local cache.
+            including S3-specific parameters (region, bucket_name, root_prefix)
+            combined with parameters from the local cache, sorted by key names.
         """
         params = self.main_cache.get_params()
         params["region"] = self.region
@@ -156,51 +168,57 @@ class S3Dict(PersiDict):
     def base_url(self):
         """Return the S3 URL prefix of this dictionary.
 
-        This property is absent in the original dict API.
+        This property is not part of the standard Python dictionary interface.
 
         Returns:
-            str: The base S3 URL in the form "s3://<bucket>/<root_prefix>".
+            str: The base S3 URL in the format "s3://<bucket>/<root_prefix>".
         """
         return f"s3://{self.bucket_name}/{self.root_prefix}"
 
 
     @property
     def base_dir(self) -> str:
-        """Return dictionary's base directory in the local filesystem.
+        """Return the dictionary's base directory in the local filesystem.
 
-        This property is absent in the original dict API.
+        This property is not part of the standard Python dictionary interface.
 
         Returns:
-            str: Path to the local on-disk cache directory used by S3Dict.
+            str: Path to the local cache directory used for temporary files
+            and caching S3 objects.
         """
         return self.main_cache.base_dir
 
 
-    def _build_full_objectname(self, key:PersiDictKey) -> str:
-        """Convert a key into a full S3 object key (object name).
+    def _build_full_objectname(self, key: PersiDictKey) -> str:
+        """Convert a key into a full S3 object key.
 
         Args:
-            key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
 
         Returns:
-            str: The full S3 key under root_prefix with file_type suffix applied.
+            str: The complete S3 object key including root_prefix and file_type
+            extension, with digest-based collision prevention applied if enabled.
         """
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
         key = sign_safe_str_tuple(key, self.digest_len)
         objectname = self.root_prefix +  "/".join(key)+ "." + self.file_type
         return objectname
 
 
-    def __contains__(self, key:PersiDictKey) -> bool:
-        """Return True if the specified key exists in S3.
+    def __contains__(self, key: PersiDictKey) -> bool:
+        """Check if the specified key exists in the dictionary.
+
+        For immutable dictionaries, checks the local cache first. Otherwise,
+        performs a HEAD request to S3 to verify object existence.
 
         Args:
-            key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
 
         Returns:
-            bool: True if the object exists (or is cached when immutable), else False.
+            bool: True if the key exists in S3 (or local cache for immutable
+            items), False otherwise.
         """
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
         if self.immutable_items and key in self.main_cache:
                 return True
         try:
@@ -216,21 +234,24 @@ class S3Dict(PersiDict):
                 raise
 
 
-    def __getitem__(self, key:PersiDictKey) -> Any:
-        """Retrieve the value stored for a key from S3 or local cache.
+    def __getitem__(self, key: PersiDictKey) -> Any:
+        """Retrieve the value stored for a key.
 
-        If immutable_items is True and a local cached file exists, that cache is
-        returned. Otherwise, the object is fetched from S3, with conditional
-        requests used when possible.
+        For immutable dictionaries with cached values, returns the cached copy.
+        Otherwise, fetches from S3 using conditional requests (ETags) when
+        available to minimize unnecessary downloads.
 
         Args:
-            key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
 
         Returns:
-            Any: The stored value.
+            Any: The deserialized value stored for the key.
+
+        Raises:
+            KeyError: If the key does not exist in S3.
         """
 
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
 
         if self.immutable_items and key in self.main_cache:
             return self.main_cache[key]
@@ -252,8 +273,7 @@ class S3Dict(PersiDict):
             s3_etag = response.get("ETag")
             body = response['Body']
 
-            # Read all data into memory and store in cache
-
+            # Deserialize and cache the S3 object content
             if self.file_type == 'json':
                 deserialized_value = jsonpickle.loads(body.read().decode('utf-8'))
             elif self.file_type == 'pkl':
@@ -266,110 +286,86 @@ class S3Dict(PersiDict):
 
         except ClientError as e:
             if e.response['ResponseMetadata']['HTTPStatusCode'] == 304:
-                # 304 Not Modified: our cached version is up-to-date.
-                # The value will be read from cache at the end of the function.
+                # HTTP 304 Not Modified: cached version is current, no download needed
                 pass
             elif e.response.get("Error", {}).get("Code") == 'NoSuchKey':
                 raise KeyError(f"Key {key} not found in S3 bucket {self.bucket_name}")
             else:
-                # Re-raise other client errors (e.g., permissions, throttling)
+                # Re-raise other client errors (permissions, throttling, etc.)
                 raise
 
         return self.main_cache[key]
 
 
-    def __setitem__(self, key:PersiDictKey, value:Any):
-        """Store a value for a key in S3 and update the local cache.
+    def __setitem__(self, key: PersiDictKey, value: Any):
+        """Store a value for a key in both S3 and local cache.
 
-        Interprets special joker values: KEEP_CURRENT (no-op) and DELETE_CURRENT 
-        (deletes the key). Validates value type if base_class_for_values is set, 
-        then writes to the local cache and uploads to S3. If possible, caches the 
-        S3 ETag locally to enable conditional GETs later.
+        Handles special joker values (KEEP_CURRENT, DELETE_CURRENT) for
+        conditional operations. Validates value types against base_class_for_values
+        if specified, then stores locally and uploads to S3. Attempts to cache
+        the S3 ETag for efficient future retrievals.
 
         Args:
-            key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
-            value (Any): Value to store, or a joker command (KEEP_CURRENT or 
+            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
+            value: Value to store, or a joker command (KEEP_CURRENT or 
                 DELETE_CURRENT from the jokers module).
 
         Raises:
             KeyError: If attempting to modify an existing item when
                 immutable_items is True.
-            TypeError: If value is a PersiDict or does not match
-                base_class_for_values when it is set.
+            TypeError: If value is a PersiDict instance or does not match
+                the required base_class_for_values when specified.
         """
 
-        if value is KEEP_CURRENT:
-            return
-
-        if value is DELETE_CURRENT:
-            self.delete_if_exists(key)
+        key = non_empty_persidict_key(key)
+        PersiDict.__setitem__(self, key, value)
+        if isinstance(value, Joker):
+            # Joker values (KEEP_CURRENT, DELETE_CURRENT) are handled by base class
             return
 
-        if isinstance(value, PersiDict):
-            raise TypeError(
-                f"You are not allowed to store a PersiDict "
-                + f"inside another PersiDict.")
-
-        if self.base_class_for_values is not None:
-            if not isinstance(value, self.base_class_for_values):
-                raise TypeError(
-                    f"Value must be of type {self.base_class_for_values},"
-                    + f"but it is {type(value)} instead." )
-
-        key = SafeStrTuple(key)
-
-        if self.immutable_items and key in self:
-            raise KeyError("Can't modify an immutable item")
-
         obj_name = self._build_full_objectname(key)
 
         # Store in local cache first
         self.main_cache[key] = value
         
-        # Get the file path from the cache to upload to S3
+        # Upload the serialized file from local cache to S3
         file_path = self.main_cache._build_full_path(key)
         self.s3_client.upload_file(file_path, self.bucket_name, obj_name)
 
         try:
+            # Cache the S3 ETag for efficient conditional requests on future reads
             head = self.s3_client.head_object(
                 Bucket=self.bucket_name, Key=obj_name)
             self.etag_cache[key] = head.get("ETag")
         except ClientError:
-            # If we can't get ETag, we should remove any existing etag
-            # to force a re-download on the next __getitem__ call.
+            # Remove stale ETag on failure to force fresh downloads later
             self.etag_cache.delete_if_exists(key)
 
 
-    def __delitem__(self, key:PersiDictKey):
-        """Delete the stored value for a key from S3 and local cache.
+    def __delitem__(self, key: PersiDictKey):
+        """Delete the stored value for a key from both S3 and local cache.
 
         Args:
-            key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
 
         Raises:
-            KeyError: If immutable_items is True, or if the key does not exist in S3.
+            KeyError: If immutable_items is True, or if the key does not exist.
         """
-
-        key = SafeStrTuple(key)
-        if self.immutable_items:
-            raise KeyError("Can't delete an immutable item")
-
-        if key not in self:
-            raise KeyError(f"Key {key} not found in S3 bucket {self.bucket_name}")
-
+        key = non_empty_persidict_key(key)
+        PersiDict.__delitem__(self, key)
         obj_name = self._build_full_objectname(key)
-        
         self.s3_client.delete_object(Bucket = self.bucket_name, Key = obj_name)
         self.etag_cache.delete_if_exists(key)
         self.main_cache.delete_if_exists(key)
 
 
     def __len__(self) -> int:
-        """Return len(self).
+        """Return the number of key-value pairs in the dictionary.
 
-        WARNING: This operation can be very slow and costly on large S3 buckets
-        as it needs to iterate over all objects in the dictionary's prefix.
-        Avoid using it in performance-sensitive code.
+        Warning:
+            This operation can be very slow and expensive on large S3 buckets
+            as it must paginate through all objects under the dictionary's prefix.
+            Avoid using in performance-critical code.
 
         Returns:
             int: Number of stored items under this dictionary's root_prefix.
@@ -395,56 +391,47 @@ class S3Dict(PersiDict):
 
 
     def _generic_iter(self, result_type: set[str]):
-        """Underlying implementation for .items()/.keys()/.values() iterators.
+        """Underlying implementation for items(), keys(), and values() iterators.
 
-        Iterates over S3 objects under the configured root_prefix and yields
+        Paginates through S3 objects under the configured root_prefix and yields
         keys, values, and/or timestamps according to the requested result_type.
-        Keys are mapped to SafeStrTuple by removing the file extension and
-        unsigning based on digest_len.
+        S3 object keys are converted to SafeStrTuple instances by removing the
+        file extension and reversing digest-based signing if enabled.
 
         Args:
-            result_type (set[str]): Any non-empty subset of {"keys", "values",
-                "timestamps"} specifying which fields to yield.
+            result_type: Non-empty subset of {"keys", "values", "timestamps"}
+                specifying which fields to yield from each dictionary entry.
 
         Returns:
-            Iterator: A generator yielding:
+            Iterator: A generator that yields:
                 - SafeStrTuple if result_type == {"keys"}
-                - Any if result_type == {"values"}
+                - Any if result_type == {"values"}  
                 - tuple[SafeStrTuple, Any] if result_type == {"keys", "values"}
-                - tuple[..., float] including POSIX timestamp if "timestamps" is requested.
+                - tuple including float timestamp if "timestamps" requested
 
         Raises:
-            ValueError: If result_type is not a set or contains entries other than
-                "keys", "values", and/or "timestamps", or if it is empty.
+            ValueError: If result_type is invalid (empty, not a set, or contains
+                unsupported field names).
         """
 
-        if not isinstance(result_type, set):
-            raise ValueError(
-                "result_type must be a set containing one to three of: 'keys', 'values', 'timestamps'"
-            )
-        if not (1 <= len(result_type) <= 3):
-            raise ValueError("result_type must be a non-empty set with at most three elements")
-        allowed = {"keys", "values", "timestamps"}
-        if not result_type.issubset(allowed):
-            invalid = ", ".join(sorted(result_type - allowed))
-            raise ValueError(f"result_type contains invalid entries: {invalid}. Allowed: {sorted(allowed)}")
-        # Intersections/length checks are implied by the above conditions.
+        PersiDict._generic_iter(self, result_type)
 
         suffix = "." + self.file_type
         ext_len = len(self.file_type) + 1
         prefix_len = len(self.root_prefix)
 
         def splitter(full_name: str) -> SafeStrTuple:
-            """Convert an S3 object key into a SafeStrTuple without the suffix.
+            """Convert an S3 object key into a SafeStrTuple without the file extension.
 
             Args:
-                full_name (str): Full S3 object key (including root_prefix).
+                full_name: Complete S3 object key including root_prefix and extension.
 
             Returns:
-                SafeStrTuple: The parsed key parts, still signed.
+                SafeStrTuple: The parsed key components with digest signatures intact.
 
             Raises:
-                ValueError: If the provided key does not start with this dictionary's root_prefix.
+                ValueError: If the object key does not start with this dictionary's
+                    root_prefix (indicating it's outside the dictionary's scope).
             """
             if not full_name.startswith(self.root_prefix):
                 raise ValueError(
@@ -454,7 +441,11 @@ class S3Dict(PersiDict):
             return SafeStrTuple(result)
 
         def step():
-            """Generator that pages through S3 and yields entries based on result_type."""
+            """Generator that paginates through S3 objects and yields requested data.
+            
+            Yields dictionary entries (keys, values, timestamps) according to the
+            result_type specification from the parent _generic_iter method.
+            """
             paginator = self.s3_client.get_paginator("list_objects_v2")
             page_iterator = paginator.paginate(
                 Bucket=self.bucket_name, Prefix = self.root_prefix)
@@ -491,19 +482,20 @@ class S3Dict(PersiDict):
         return step()
 
 
-    def get_subdict(self, key:PersiDictKey) -> S3Dict:
-        """Get a subdictionary containing items with the same prefix key.
+    def get_subdict(self, key: PersiDictKey) -> S3Dict:
+        """Create a subdictionary scoped to items with the specified prefix.
 
-        For a non-existing prefix key, an empty sub-dictionary is returned.
-        This method is absent in the original dict API.
+        Returns an empty subdictionary if no items exist under the prefix.
+        This method is not part of the standard Python dictionary interface.
 
         Args:
             key (PersiDictKey): A common prefix (string or sequence of strings)
                 used to scope items stored under this dictionary.
 
         Returns:
-            S3Dict: A new S3Dict instance rooted at the given prefix, sharing
-            the same bucket, region, serialization, and immutability settings.
+            S3Dict: A new S3Dict instance with root_prefix extended by the given
+            key, sharing the parent's bucket, region, file_type, and other
+            configuration settings.
         """
 
         key = SafeStrTuple(key)
@@ -529,23 +521,23 @@ class S3Dict(PersiDict):
         return new_dict
 
 
-    def timestamp(self,key:PersiDictKey) -> float:
-        """Get last modification time (Unix epoch seconds) for a key.
+    def timestamp(self, key: PersiDictKey) -> float:
+        """Get the last modification timestamp for a key.
 
-        This method is absent in the original dict API.
+        This method is not part of the standard Python dictionary interface.
 
         Args:
-            key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
 
         Returns:
-            float: POSIX timestamp (seconds since the Unix epoch) of the last
-            modification time as reported by S3 for the object. The timestamp
-            is timezone-aware and converted to UTC.
+            float: POSIX timestamp (seconds since Unix epoch) of the last
+            modification time as reported by S3. The timestamp is timezone-aware
+            and converted to UTC.
 
         Raises:
             KeyError: If the key does not exist in S3.
         """
-        key = SafeStrTuple(key)
+        key = non_empty_persidict_key(key)
         obj_name = self._build_full_objectname(key)
         response = self.s3_client.head_object(Bucket=self.bucket_name, Key=obj_name)
         return response["LastModified"].timestamp()

{persidict-0.36.11.dist-info → persidict-0.37.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.36.11
+Version: 0.37.1
 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.36.11.dist-info → persidict-0.37.1.dist-info}/RECORD

@@ -1,14 +1,14 @@
 persidict/.DS_Store,sha256=1lFlJ5EFymdzGAUAaI30vcaaLHt3F1LwpG7xILf9jsM,6148
 persidict/__init__.py,sha256=CDOSJGgCnyRTkGUTzaeg3Cqsxwx0-0EFieOtldXwAls,1380
-persidict/file_dir_dict.py,sha256=mWMgLN_uj-IlqIbyVdbABLVxiB-t2wh2rbv98sUWyrY,25758
-persidict/jokers.py,sha256=7ibh0ccfkEm3EvKIOhH9ShfZ0_MBKYMvKa1rwqHg1hk,3010
+persidict/file_dir_dict.py,sha256=2McFaDdr03g-PXlCIiG3fPb7h59LXW_3hDo0xLA17DE,24804
+persidict/jokers.py,sha256=gTu7g2l2MIgBc3-hjvUrcwcgWs6tcbLyxB0u57M3bfU,3012
 persidict/overlapping_multi_dict.py,sha256=UFyPEG2GbMmMHY48UmcaLHpsaxMqRH3bc_UA8S90yJo,5947
-persidict/persi_dict.py,sha256=Q7fGs9LFPxSLtC0jJwDOP1AVD9_t01SnwdN4RVBMZtg,20660
-persidict/s3_dict.py,sha256=0o2RslAkdE75N9zDuqQMyiSbO0uzdQmiNmZSfHZzfxw,21137
+persidict/persi_dict.py,sha256=CKVHy8YELLRVgLWgo0Akbd8RznCVxqt8JHszIjqA_sI,23176
+persidict/s3_dict.py,sha256=F5N7DlpZBkEEUsDk7OQXiqACY-mJ2SOMNrh3AlHC9qo,21454
 persidict/safe_chars.py,sha256=H-cL9waCmDtwaRR5Y4b4oTzcBx09nc8wn8u61SVZDY0,1728
 persidict/safe_str_tuple.py,sha256=YBTcYjUKIffznOawXb9xKjz4HaKdklrgyVtegJFmr5w,7202
 persidict/safe_str_tuple_signing.py,sha256=mpOfx_xyprc0_c60XPB_EihI3vR1gOn6T03iCx1HwwQ,7494
 persidict/write_once_dict.py,sha256=nv5vx9uh6VZ5Qh3HJcBgUHLnDX9KY843FbHndcy-63E,11677
-persidict-0.36.11.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
-persidict-0.36.11.dist-info/METADATA,sha256=T3NKQWLF_OlBZTx4wg3x16RUiTlcYignxP9UVrNrVPc,12388
-persidict-0.36.11.dist-info/RECORD,,
+persidict-0.37.1.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
+persidict-0.37.1.dist-info/METADATA,sha256=M2EVewTSqdjfqdMi-7VHkSUKHqlL-ohlXYrcVRj7ViA,12387
+persidict-0.37.1.dist-info/RECORD,,