persidict 0.36.8__py3-none-any.whl → 0.36.10__py3-none-any.whl

persidict/file_dir_dict.py

@@ -45,7 +45,7 @@ class FileDirDict(PersiDict):
     Insertion order is not preserved.
 
     FileDirDict can store objects in binary files or in human-readable
-    text files (either in jason format or as a plain text).
+    text files (either in JSON format or as plain text).
     """
 
     _base_dir:str
@@ -74,9 +74,9 @@ class FileDirDict(PersiDict):
                 then file_type must be either "pkl" or "json".
 
         Raises:
-            ValueError: If base_dir points to a file; if file_type is "__etag__";
-                if file_type contains unsafe characters; or if configuration is
-                inconsistent (e.g., non-str values with unsupported file_type).
+            ValueError: If file_type contains unsafe characters; or
+                if configuration is inconsistent (e.g., non-str values
+                with unsupported file_type).
             RuntimeError: If base_dir cannot be created or is not a directory.
         """
 
@@ -87,10 +87,6 @@ class FileDirDict(PersiDict):
         if file_type != replace_unsafe_chars(file_type, ""):
             raise ValueError("file_type contains unsafe characters")
         self.file_type = file_type
-        if self.file_type == "__etag__":
-            raise ValueError(
-                "file_type cannot be 'etag' as it is a reserved"
-                " extension for S3 caching.")
 
         if (base_class_for_values is None or
                 not issubclass(base_class_for_values,str)):

persidict/jokers.py

@@ -29,8 +29,9 @@ class Joker(ParameterizableClass):
     parameterizable framework. Subclasses represent value-less commands that
     alter persistence behavior when assigned to a key.
 
-    Returns:
-        Joker: The singleton instance for the subclass when instantiated.
+    Note:
+        This class uses a singleton pattern where each subclass maintains
+        exactly one instance that is returned on every instantiation.
     """
     _instances: dict[type, "Joker"] = {}
 
@@ -43,7 +44,14 @@ class Joker(ParameterizableClass):
         return {}
 
     def __new__(cls):
-        """Create or return the singleton instance for the subclass."""
+        """Create or return the singleton instance for the subclass.
+        
+        Args:
+            cls: The class for which to create or retrieve the singleton instance.
+            
+        Returns:
+            Joker: The singleton instance for the specified class.
+        """
         if cls not in Joker._instances:
             Joker._instances[cls] = super().__new__(cls)
         return Joker._instances[cls]

persidict/overlapping_multi_dict.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any, Dict, Type
+from typing import Any, Dict, List, Type
 
 from .persi_dict import PersiDict
 
@@ -14,17 +14,17 @@ class OverlappingMultiDict:
     bucket and differ only in how items are materialized by file type.
 
     Attributes:
-        dict_type (type):
-            A subclass of PersiDict used to create each sub-dictionary.
-        shared_subdicts_params (dict):
-            Parameters applied to every created sub-dictionary (e.g., base_dir,
-            bucket, immutable_items, digest_len).
-        individual_subdicts_params (dict):
-            Mapping from file_type (attribute name) to a dict of parameters that
-            are specific to that sub-dictionary. These override or extend
-            shared_subdicts_params for the given file_type.
-        subdicts_names (list[str]):
-            The list of file_type names (i.e., attribute names) created.
+        dict_type (Type[PersiDict]): A subclass of PersiDict used to create each 
+            sub-dictionary.
+        shared_subdicts_params (Dict[str, Any]): Parameters applied to every 
+            created sub-dictionary (e.g., base_dir, bucket, immutable_items, 
+            digest_len).
+        individual_subdicts_params (Dict[str, Dict[str, Any]]): Mapping from 
+            file_type (attribute name) to a dict of parameters that are specific 
+            to that sub-dictionary. These override or extend shared_subdicts_params 
+            for the given file_type.
+        subdicts_names (List[str]): The list of file_type names (i.e., attribute 
+            names) created.
 
     Raises:
         TypeError: If pickling is attempted or item access is used on the
@@ -37,17 +37,16 @@ class OverlappingMultiDict:
         """Initialize the container and create sub-dictionaries.
 
         Args:
-            dict_type (type):
-                A subclass of PersiDict that will be instantiated for each
-                file_type provided via individual_subdicts_params.
-            shared_subdicts_params (dict):
-                Parameters shared by all sub-dicts (e.g., base_dir, bucket).
-            **individual_subdicts_params: Dict[str, dict]
-                Keyword arguments where each key is a file_type (also the
-                attribute name to be created) and each value is a dict of
-                parameters specific to that sub-dict. These are merged with
-                shared_subdicts_params when constructing the sub-dict. The
-                resulting dict also receives file_type=<key>.
+            dict_type (Type[PersiDict]): A subclass of PersiDict that will be 
+                instantiated for each file_type provided via individual_subdicts_params.
+            shared_subdicts_params (Dict[str, Any]): Parameters shared by all 
+                sub-dicts (e.g., base_dir, bucket).
+            **individual_subdicts_params (Dict[str, Dict[str, Any]]): Keyword 
+                arguments where each key is a file_type (also the attribute name 
+                to be created) and each value is a dict of parameters specific to 
+                that sub-dict. These are merged with shared_subdicts_params when 
+                constructing the sub-dict. The resulting dict also receives 
+                file_type=<key>.
 
         Raises:
             TypeError: If dict_type is not a PersiDict subclass, or if
@@ -67,9 +66,9 @@ class OverlappingMultiDict:
                 raise TypeError(
                     f"Params for subdict {subdict_name!r} must be a dict")
             self.__dict__[subdict_name] = dict_type(
-                **{**shared_subdicts_params
-                ,**individual_subdicts_params[subdict_name]
-                ,"file_type":subdict_name})
+                **{**shared_subdicts_params,
+                   **individual_subdicts_params[subdict_name],
+                   "file_type": subdict_name})
 
     def __getstate__(self):
         """Prevent pickling.
@@ -82,6 +81,9 @@ class OverlappingMultiDict:
     def __setstate__(self, state):
         """Prevent unpickling.
 
+        Args:
+            state: The state dictionary that would be used for unpickling (ignored).
+
         Raises:
             TypeError: Always raised; this object is not pickleable.
         """
@@ -93,6 +95,9 @@ class OverlappingMultiDict:
         Suggest accessing items through the sub-dictionaries exposed as
         attributes (e.g., obj.json[key]).
 
+        Args:
+            key: The key that would be accessed (ignored).
+
         Raises:
             TypeError: Always raised to indicate unsupported operation.
         """
@@ -104,6 +109,10 @@ class OverlappingMultiDict:
     def __setitem__(self, key, value):
         """Disallow item assignment on the container itself.
 
+        Args:
+            key: The key that would be assigned (ignored).
+            value: The value that would be assigned (ignored).
+
         Raises:
             TypeError: Always raised to indicate unsupported operation.
         """
@@ -115,10 +124,13 @@ class OverlappingMultiDict:
     def __delitem__(self, key):
         """Disallow item deletion on the container itself.
 
+        Args:
+            key: The key that would be deleted (ignored).
+
         Raises:
             TypeError: Always raised to indicate unsupported operation.
         """
         raise TypeError(
             "OverlappingMultiDict does not support item deletion by key. "
-            "Individual items can be deletedthrough nested dicts, "
+            "Individual items can be deleted through nested dicts, "
             f"which are available via attributes {self.subdicts_names}")

persidict/persi_dict.py

@@ -26,9 +26,9 @@ from .jokers import KEEP_CURRENT, DELETE_CURRENT, Joker
 from .safe_str_tuple import SafeStrTuple
 
 PersiDictKey = SafeStrTuple | Sequence[str] | str
-""" A value which can be used as a key for PersiDict. 
+"""A value which can be used as a key for PersiDict.
 
-PersiDict-s accept keys on a form of SafeStrTuple,
+PersiDict instances accept keys in the form of SafeStrTuple,
 or a string, or a sequence of strings.
 The characters within strings must be URL/filename-safe.
 If a string (or a sequence of strings) is passed to a PersiDict as a key,
@@ -60,21 +60,26 @@ class PersiDict(MutableMapping, ParameterizableClass):
     immutable_items:bool
     base_class_for_values:Optional[type]
 
-    def __init__(self
-                 , immutable_items:bool = False
-                 , digest_len:int = 8
-                 , base_class_for_values:Optional[type] = None
-                 , *args, **kwargs):
-        """Initialize base parameters shared by all persistent dicts.
+    def __init__(self,
+                 immutable_items: bool = False,
+                 digest_len: int = 8,
+                 base_class_for_values: Optional[type] = None,
+                 *args, **kwargs):
+        """Initialize base parameters shared by all persistent dictionaries.
 
         Args:
-            immutable_items: If True, items cannot be modified or deleted.
-            digest_len: Number of hash characters to append to key components to
-                avoid case-insensitive collisions. Must be non-negative.
-            base_class_for_values: Optional base class that values must inherit
-                from; if None, values are not type-restricted.
-            *args: Ignored in the base class (reserved for subclasses).
-            **kwargs: Ignored in the base class (reserved for subclasses).
+            immutable_items (bool): If True, items cannot be modified or deleted.
+                Defaults to False.
+            digest_len (int): Number of hash characters to append to key components
+                to avoid case-insensitive collisions. Must be non-negative.
+                Defaults to 8.
+            base_class_for_values (Optional[type]): Optional base class that values
+                must inherit from. If None, values are not type-restricted.
+                Defaults to None.
+            *args: Additional positional arguments (ignored in base class, reserved
+                for subclasses).
+            **kwargs: Additional keyword arguments (ignored in base class, reserved
+                for subclasses).
 
         Raises:
             ValueError: If digest_len is negative.
@@ -91,9 +96,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         """Return configuration parameters of this dictionary.
 
         Returns:
-            dict: A sorted dict of parameters used to reconstruct the instance.
+            dict: A sorted dictionary of parameters used to reconstruct the instance.
                 This supports the Parameterizable API and is absent in the
-                builtin dict.
+                built-in dict.
         """
         params =  dict(
             immutable_items=self.immutable_items
@@ -321,20 +326,23 @@ class PersiDict(MutableMapping, ParameterizableClass):
         return self._generic_iter({"keys", "values", "timestamps"})
 
 
-    def setdefault(self, key:PersiDictKey, default:Any=None) -> Any:
-        """Insert key with default if absent; return the value.
+    def setdefault(self, key: PersiDictKey, default: Any = None) -> Any:
+        """Insert key with default value if absent; return the current value.
+
+        Behaves like the built-in dict.setdefault() method: if the key exists,
+        return its current value; otherwise, set the key to the default value
+        and return that default.
 
         Args:
-            key: Key (string or sequence of strings) or SafeStrTuple.
-            default: Value to insert if the key is not present.
+            key (PersiDictKey): Key (string, sequence of strings, or SafeStrTuple).
+            default (Any): Value to insert if the key is not present. Defaults to None.
 
         Returns:
-            Any: Existing value if present; otherwise the provided default.
+            Any: Existing value if key is present; otherwise the provided default value.
 
         Raises:
             TypeError: If default is a Joker command (KEEP_CURRENT/DELETE_CURRENT).
         """
-        # TODO: check edge cases to ensure the same semantics as standard dicts
         key = SafeStrTuple(key)
         if isinstance(default, Joker):
             raise TypeError("default must be a regular value, not a Joker command")
@@ -345,19 +353,20 @@ class PersiDict(MutableMapping, ParameterizableClass):
             return default
 
 
-    def __eq__(self, other:PersiDict) -> bool:
+    def __eq__(self, other: PersiDict) -> bool:
         """Compare dictionaries for equality.
 
-        If other is a PersiDict, compare portable params. Otherwise, attempt to
-        compare as mapping by keys and values.
+        If other is a PersiDict instance, compares portable parameters for equality.
+        Otherwise, attempts to compare as a mapping by comparing all keys and values.
 
         Args:
-            other: Another dictionary-like object.
+            other (PersiDict): Another dictionary-like object to compare against.
 
         Returns:
-            bool: True if considered equal, False otherwise.
+            bool: True if the dictionaries are considered equal, False otherwise.
         """
         if isinstance(other, PersiDict):
+            #TODO: decide whether to keep this semantics
             return self.get_portable_params() == other.get_portable_params()
         try:
             if len(self) != len(other):
@@ -525,15 +534,15 @@ class PersiDict(MutableMapping, ParameterizableClass):
     def oldest_keys(self, max_n=None):
         """Return up to max_n oldest keys in the dictionary.
 
+        This method is absent in the original Python dict API.
+
         Args:
             max_n (int | None): Maximum number of keys to return. If None,
                 return all keys sorted by age (oldest first). Values <= 0
-                yield an empty list.
+                yield an empty list. Defaults to None.
 
         Returns:
             list[SafeStrTuple]: The oldest keys, oldest first.
-
-        This method is absent in the original Python dict API.
         """
         if max_n is None:
             # If we need all keys, sort them all by timestamp
@@ -553,6 +562,8 @@ class PersiDict(MutableMapping, ParameterizableClass):
     def oldest_values(self, max_n=None):
         """Return up to max_n oldest values in the dictionary.
 
+        This method is absent in the original Python dict API.
+
         Args:
             max_n (int | None): Maximum number of values to return. If None,
                 return values for all keys sorted by age (oldest first). Values
@@ -560,8 +571,6 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
         Returns:
             list[Any]: Values corresponding to the oldest keys.
-
-        This method is absent in the original Python dict API.
         """
         return [self[k] for k in self.oldest_keys(max_n)]
 
@@ -569,15 +578,15 @@ class PersiDict(MutableMapping, ParameterizableClass):
     def newest_keys(self, max_n=None):
         """Return up to max_n newest keys in the dictionary.
 
+        This method is absent in the original Python dict API.
+
         Args:
             max_n (int | None): Maximum number of keys to return. If None,
                 return all keys sorted by age (newest first). Values <= 0
-                yield an empty list.
+                yield an empty list. Defaults to None.
 
         Returns:
             list[SafeStrTuple]: The newest keys, newest first.
-
-        This method is absent in the original Python dict API.
         """
         if max_n is None:
             # If we need all keys, sort them all by timestamp in reverse order
@@ -597,6 +606,8 @@ class PersiDict(MutableMapping, ParameterizableClass):
     def newest_values(self, max_n=None):
         """Return up to max_n newest values in the dictionary.
 
+        This method is absent in the original Python dict API.
+
         Args:
             max_n (int | None): Maximum number of values to return. If None,
                 return values for all keys sorted by age (newest first). Values
@@ -604,7 +615,5 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
         Returns:
             list[Any]: Values corresponding to the newest keys.
-
-        This method is absent in the original Python dict API.
         """
         return [self[k] for k in self.newest_keys(max_n)]

persidict/s3_dict.py

@@ -5,6 +5,8 @@ import tempfile
 from typing import Any, Optional
 
 import boto3
+import joblib
+import jsonpickle
 from botocore.exceptions import ClientError
 
 import parameterizable
@@ -15,6 +17,7 @@ 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 .overlapping_multi_dict import OverlappingMultiDict
 
 S3DICT_DEFAULT_BASE_DIR = "__s3_dict__"
 
@@ -70,24 +73,28 @@ class S3Dict(PersiDict):
                 must be "pkl" or "json".
             *args: Ignored; reserved for compatibility.
             **kwargs: Ignored; reserved for compatibility.
-
-        Raises:
-            ValueError: If file_type is "__etag__" (reserved) or configuration
-                is inconsistent with base_class_for_values.
         """
 
-        super().__init__(immutable_items = immutable_items, digest_len = 0)
+        super().__init__(immutable_items = immutable_items, digest_len = digest_len)
         self.file_type = file_type
-        if self.file_type == "__etag__":
-            raise ValueError(
-                "file_type cannot be 'etag' as it is a reserved extension for caching.")
-
-        self.local_cache = FileDirDict(
-            base_dir= base_dir
-            , file_type = file_type
-            , immutable_items = immutable_items
-            , base_class_for_values=base_class_for_values
-            , digest_len = digest_len)
+        self.etag_file_type = f"{file_type}_etag"
+
+        self.local_cache = OverlappingMultiDict(
+            dict_type=FileDirDict,
+            shared_subdicts_params={
+                "base_dir": base_dir,
+                "immutable_items": immutable_items,
+                "base_class_for_values": base_class_for_values,
+                "digest_len": digest_len
+            },
+            **{
+                self.file_type: {},
+                self.etag_file_type: {"base_class_for_values": str}
+            }
+        )
+
+        self.main_cache = getattr(self.local_cache, self.file_type)
+        self.etag_cache = getattr(self.local_cache, self.etag_file_type)
 
         self.region = region
         if region is None:
@@ -96,9 +103,28 @@ class S3Dict(PersiDict):
             self.s3_client = boto3.client('s3', region_name=region)
 
         try:
-            self.s3_client.create_bucket(Bucket=bucket_name)
-        except:
-            pass
+            self.s3_client.head_bucket(Bucket=bucket_name)
+        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.
+                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
+                    if ( create_error_code == 'BucketAlreadyOwnedByYou'
+                        or create_error_code == 'BucketAlreadyExists'):
+                        pass
+                    else:
+                        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.
+                pass
+            else:
+                raise e  # Re-raise other unexpected ClientErrors on head_bucket.
 
         self.bucket_name = bucket_name
 
@@ -118,7 +144,7 @@ class S3Dict(PersiDict):
             including region, bucket_name, and root_prefix combined with
             parameters from the local cache.
         """
-        params = self.local_cache.get_params()
+        params = self.main_cache.get_params()
         params["region"] = self.region
         params["bucket_name"] = self.bucket_name
         params["root_prefix"] = self.root_prefix
@@ -147,7 +173,7 @@ class S3Dict(PersiDict):
         Returns:
             str: Path to the local on-disk cache directory used by S3Dict.
         """
-        return self.local_cache.base_dir
+        return self.main_cache.base_dir
 
 
     def _build_full_objectname(self, key:PersiDictKey) -> str:
@@ -175,50 +201,19 @@ class S3Dict(PersiDict):
             bool: True if the object exists (or is cached when immutable), else False.
         """
         key = SafeStrTuple(key)
-        if self.immutable_items:
-            file_name = self.local_cache._build_full_path(
-                key, create_subdirs=True)
-            if os.path.exists(file_name):
+        if self.immutable_items and key in self.main_cache:
                 return True
         try:
             obj_name = self._build_full_objectname(key)
             self.s3_client.head_object(Bucket=self.bucket_name, Key=obj_name)
             return True
-        except:
-            return False
-
-
-    def _write_etag_file(self, file_name: str, etag: str):
-        """Atomically write the ETag to its cache file.
-
-        Args:
-            file_name (str): Path to the cached data file (without the ETag suffix).
-            etag (str): The S3 ETag value to persist alongside the cached file.
-        """
-        if not etag:
-            return
-        etag_file_name = file_name + ".__etag__"
-        dir_name = os.path.dirname(etag_file_name)
-        # Write to a temporary file and then rename for atomicity
-        fd, temp_path = tempfile.mkstemp(dir=dir_name)
-        try:
-            with os.fdopen(fd, "w") as f:
-                f.write(etag)
-                f.flush()
-                os.fsync(f.fileno())
-            os.replace(temp_path, etag_file_name)
-            try:
-                if os.name == 'posix':
-                    dir_fd = os.open(dir_name, os.O_RDONLY)
-                    try:
-                        os.fsync(dir_fd)
-                    finally:
-                        os.close(dir_fd)
-            except OSError:
-                pass
-        except:
-            os.remove(temp_path)
-            raise
+        except ClientError as e:
+            if e.response['ResponseMetadata']['HTTPStatusCode'] == 404:
+                self.main_cache.delete_if_exists(key)
+                self.etag_cache.delete_if_exists(key)
+                return False
+            else:
+                raise
 
 
     def __getitem__(self, key:PersiDictKey) -> Any:
@@ -236,19 +231,15 @@ class S3Dict(PersiDict):
         """
 
         key = SafeStrTuple(key)
-        file_name = self.local_cache._build_full_path(key, create_subdirs=True)
 
-        if self.immutable_items and os.path.exists(file_name):
-            return self.local_cache._read_from_file(file_name)
+        if self.immutable_items and key in self.main_cache:
+            return self.main_cache[key]
 
         obj_name = self._build_full_objectname(key)
 
         cached_etag = None
-        etag_file_name = file_name + ".__etag__"
-        if not self.immutable_items and os.path.exists(file_name) and os.path.exists(
-                etag_file_name):
-            with open(etag_file_name, "r") as f:
-                cached_etag = f.read()
+        if not self.immutable_items and key in self.main_cache and key in self.etag_cache:
+            cached_etag = self.etag_cache[key]
 
         try:
             get_kwargs = {'Bucket': self.bucket_name, 'Key': obj_name}
@@ -261,37 +252,22 @@ class S3Dict(PersiDict):
             s3_etag = response.get("ETag")
             body = response['Body']
 
-            dir_name = os.path.dirname(file_name)
-            fd, temp_path = tempfile.mkstemp(dir=dir_name, prefix=".__tmp__")
-
-            try:
-                with os.fdopen(fd, 'wb') as f:
-                    # Stream body to file to avoid loading all in memory
-                    for chunk in body.iter_chunks():
-                        f.write(chunk)
-                    f.flush()
-                    os.fsync(f.fileno())
-                os.replace(temp_path, file_name)
-                try:
-                    if os.name == 'posix':
-                        dir_fd = os.open(dir_name, os.O_RDONLY)
-                        try:
-                            os.fsync(dir_fd)
-                        finally:
-                            os.close(dir_fd)
-                except OSError:
-                    pass
-            except:
-                os.remove(temp_path)  # Clean up temp file on failure
-                raise
+            # Read all data into memory and store in cache
 
-            self._write_etag_file(file_name, s3_etag)
+            if self.file_type == 'json':
+                deserialized_value = jsonpickle.loads(body.read().decode('utf-8'))
+            elif self.file_type == 'pkl':
+                deserialized_value = joblib.load(body)
+            else:
+                deserialized_value = body.read().decode('utf-8')
+
+            self.main_cache[key] = deserialized_value
+            self.etag_cache[key] = s3_etag
 
         except ClientError as e:
-            error_code = e.response.get("Error", {}).get("Code")
             if e.response['ResponseMetadata']['HTTPStatusCode'] == 304:
                 # 304 Not Modified: our cached version is up-to-date.
-                # The file will be read from cache at the end of the function.
+                # The value will be read from cache at the end of the function.
                 pass
             elif e.response.get("Error", {}).get("Code") == 'NoSuchKey':
                 raise KeyError(f"Key {key} not found in S3 bucket {self.bucket_name}")
@@ -299,20 +275,21 @@ class S3Dict(PersiDict):
                 # Re-raise other client errors (e.g., permissions, throttling)
                 raise
 
-        return self.local_cache._read_from_file(file_name)
+        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.
 
-        Interprets joker values KEEP_CURRENT and DELETE_CURRENT accordingly.
-        Validates a 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.
+        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.
 
         Args:
             key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
-            value (Any): Value to store, or a joker command.
+            value (Any): 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
@@ -344,23 +321,23 @@ class S3Dict(PersiDict):
         if self.immutable_items and key in self:
             raise KeyError("Can't modify an immutable item")
 
-        file_name = self.local_cache._build_full_path(key, create_subdirs=True)
         obj_name = self._build_full_objectname(key)
 
-        self.local_cache._save_to_file(file_name, value)
-        self.s3_client.upload_file(file_name, self.bucket_name, obj_name)
+        # Store in local cache first
+        self.main_cache[key] = value
+        
+        # Get the file path from the cache to upload to S3
+        file_path = self.main_cache._build_full_path(key)
+        self.s3_client.upload_file(file_path, self.bucket_name, obj_name)
 
         try:
             head = self.s3_client.head_object(
                 Bucket=self.bucket_name, Key=obj_name)
-            s3_etag = head.get("ETag")
-            self._write_etag_file(file_name, s3_etag)
+            self.etag_cache[key] = head.get("ETag")
         except ClientError:
-            # If we can't get ETag, we should remove any existing etag file
+            # If we can't get ETag, we should remove any existing etag
             # to force a re-download on the next __getitem__ call.
-            etag_file_name = file_name + ".__etag__"
-            if os.path.exists(etag_file_name):
-                os.remove(etag_file_name)
+            self.etag_cache.delete_if_exists(key)
 
 
     def __delitem__(self, key:PersiDictKey):
@@ -370,20 +347,22 @@ class S3Dict(PersiDict):
             key (PersiDictKey): Key (string or sequence of strings) or SafeStrTuple.
 
         Raises:
-            KeyError: If immutable_items is True.
+            KeyError: If immutable_items is True, or if the key does not exist in S3.
         """
 
         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}")
+
         obj_name = self._build_full_objectname(key)
+        
         self.s3_client.delete_object(Bucket = self.bucket_name, Key = obj_name)
-        file_name = self.local_cache._build_full_path(key)
-        if os.path.isfile(file_name):
-            os.remove(file_name)
-        etag_file_name = file_name + ".__etag__"
-        if os.path.isfile(etag_file_name):
-            os.remove(etag_file_name)
+        self.etag_cache.delete_if_exists(key)
+        self.main_cache.delete_if_exists(key)
+
 
     def __len__(self) -> int:
         """Return len(self).
@@ -415,7 +394,7 @@ class S3Dict(PersiDict):
         return num_files
 
 
-    def _generic_iter(self, result_type: str):
+    def _generic_iter(self, result_type: set[str]):
         """Underlying implementation for .items()/.keys()/.values() iterators.
 
         Iterates over S3 objects under the configured root_prefix and yields
@@ -529,13 +508,12 @@ class S3Dict(PersiDict):
 
         key = SafeStrTuple(key)
         if len(key):
-            key = SafeStrTuple(key)
             key = sign_safe_str_tuple(key, self.digest_len)
             full_root_prefix = self.root_prefix +  "/".join(key)
         else:
             full_root_prefix = self.root_prefix
 
-        new_dir_path = self.local_cache._build_full_path(
+        new_dir_path = self.main_cache._build_full_path(
             key, create_subdirs = True, is_file_path = False)
 
         new_dict = S3Dict(
@@ -561,9 +539,12 @@ class S3Dict(PersiDict):
 
         Returns:
             float: POSIX timestamp (seconds since the Unix epoch) of the last
-            modification time as reported by S3 for the object.
+            modification time as reported by S3 for the object. The timestamp
+            is timezone-aware and converted to UTC.
+
+        Raises:
+            KeyError: If the key does not exist in S3.
         """
-        # TODO: check work with timezones
         key = SafeStrTuple(key)
         obj_name = self._build_full_objectname(key)
         response = self.s3_client.head_object(Bucket=self.bucket_name, Key=obj_name)

persidict/safe_chars.py

@@ -1,6 +1,17 @@
+"""Safe character handling utilities for URL and filesystem compatibility.
+
+This module defines character sets and length constraints for building strings
+that are safe for use in URLs, filenames, and other contexts where character
+restrictions apply.
+"""
 import string
 
+# Set of characters considered safe for filenames and URL components.
+# Includes ASCII letters (a-z, A-Z), digits (0-9), and special chars: ()_-~.=
 SAFE_CHARS_SET = set(string.ascii_letters + string.digits + "()_-~.=")
+
+# Maximum length for safe strings to ensure compatibility with various filesystems
+# and URL length limitations. Set to 254 to stay well under most system limits.
 SAFE_STRING_MAX_LENGTH = 254
 
 def get_safe_chars() -> set[str]:

persidict/safe_str_tuple_signing.py

@@ -114,7 +114,7 @@ def _add_all_suffixes_if_absent(
 
     new_seq = []
     for s in str_seq:
-        new_seq.append(_add_signature_suffix_if_absent(s,digest_len))
+        new_seq.append(_add_signature_suffix_if_absent(s, digest_len))
 
     new_seq = SafeStrTuple(*new_seq)
 

persidict/write_once_dict.py

@@ -268,7 +268,7 @@ class WriteOnceDict(PersiDict):
         """Delegate iteration to the wrapped dict.
 
         Args:
-            iter_type: tType of iterator: 'items' and/or 'keys' and/or 'timestamps'.
+            iter_type: Type of iterator: 'items' and/or 'keys' and/or 'timestamps'.
 
         Returns:
             Any: Iterator from the wrapped dictionary.
@@ -299,13 +299,21 @@ class WriteOnceDict(PersiDict):
         return getattr(self._wrapped_dict, name)
 
     @property
-    def base_dir(self):
-        """Base directory of the wrapped dict (if applicable)."""
+    def base_dir(self) -> str|None:
+        """Base directory of the wrapped dict (if applicable).
+        
+        Returns:
+            str | None: The base directory path, or None if not applicable.
+        """
         return self._wrapped_dict.base_dir
 
     @property
-    def base_url(self):
-        """Base URL of the wrapped dict (if applicable)."""
+    def base_url(self) -> str|None:
+        """Base URL of the wrapped dict (if applicable).
+        
+        Returns:
+            str | None: The base URL, or None if not applicable.
+        """
         return self._wrapped_dict.base_url
 
     def get_subdict(self, prefix_key: PersiDictKey) -> WriteOnceDict:

{persidict-0.36.8.dist-info → persidict-0.36.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.36.8
+Version: 0.36.10
 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.10.dist-info/RECORD

@@ -0,0 +1,14 @@
+persidict/.DS_Store,sha256=1lFlJ5EFymdzGAUAaI30vcaaLHt3F1LwpG7xILf9jsM,6148
+persidict/__init__.py,sha256=CDOSJGgCnyRTkGUTzaeg3Cqsxwx0-0EFieOtldXwAls,1380
+persidict/file_dir_dict.py,sha256=JJ5oEyaqwTm9g_tUrVfut0IYI7bd5B2lhxrLzadTohA,25541
+persidict/jokers.py,sha256=7ibh0ccfkEm3EvKIOhH9ShfZ0_MBKYMvKa1rwqHg1hk,3010
+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/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.10.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
+persidict-0.36.10.dist-info/METADATA,sha256=iJ9RdvGe3i_xO3yTM8J8iaZ6k2lwd_ezDl8kzqioywc,12388
+persidict-0.36.10.dist-info/RECORD,,

persidict-0.36.8.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=IDRb6a3YQvM7Gf0jbqKkTi4VuSPecTw6Ca6HZ947Qj8,25784
-persidict/jokers.py,sha256=Ow4tWOTTMGKvolJyVuEF-oEgE_u3vDZtA9UFwTdhNV4,2731
-persidict/overlapping_multi_dict.py,sha256=gBiHaCb5pTGNW3ZrakgaiGDid6oCfoP7Vq1rxXGnFWg,5476
-persidict/persi_dict.py,sha256=DIMQaY4gE8NSYTlHlk9rfOJJEYUuLV8kmQ-gc474py4,20052
-persidict/s3_dict.py,sha256=VKDqY9sASffeXtfbavVWk8-umrioIG5Xq57Qqg1wPH4,21522
-persidict/safe_chars.py,sha256=9Qy24fu2dmiJOdmCF8mKZULfQaRp7H4oxfgDXeLgogI,1160
-persidict/safe_str_tuple.py,sha256=YBTcYjUKIffznOawXb9xKjz4HaKdklrgyVtegJFmr5w,7202
-persidict/safe_str_tuple_signing.py,sha256=RQAj4fnpRVaOe0KpwLler1UTaeNOgXCQpU3t80ixtxg,7493
-persidict/write_once_dict.py,sha256=-lPQ_yuU62pczHT0BYO6SFbiZBKFq8Tj9ln3jCzNDzA,11443
-persidict-0.36.8.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
-persidict-0.36.8.dist-info/METADATA,sha256=816s1lWkpNdgJMfVS16sDaYDyHFzaLZRDHVVMs86Slo,12387
-persidict-0.36.8.dist-info/RECORD,,