persidict 0.38.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

persidict/s3_dict_file_dir_cached.py

@@ -0,0 +1,215 @@
+"""S3Dict_FileDirCached implementation that mimics S3Dict_Legacy but uses BasicS3Dict, FileDirDict, and cached classes."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import parameterizable
+from parameterizable import sort_dict_by_keys
+
+from .basic_s3_dict import BasicS3Dict
+from .file_dir_dict import FileDirDict, FILEDIRDICT_DEFAULT_BASE_DIR
+from .cached_appendonly_dict import AppendOnlyDictCached
+from .cached_mutable_dict import MutableDictCached
+from .persi_dict import PersiDict, NonEmptyPersiDictKey, PersiDictKey
+from .safe_str_tuple import NonEmptySafeStrTuple
+from .overlapping_multi_dict import OverlappingMultiDict
+
+
+# Default base directory for S3Dict_FileDirCached local cache
+S3DICT_NEW_DEFAULT_BASE_DIR = "__s3_dict__"
+
+
+class S3Dict_FileDirCached(PersiDict):
+    """S3-backed persistent dictionary using BasicS3Dict with local caching.
+    
+    This class mimics the interface and behavior of S3Dict_Legacy but internally uses
+    BasicS3Dict for S3 operations combined with FileDirDict-based local caching
+    via the cached wrapper classes (AppendOnlyDictCached/MutableDictCached).
+    
+    The architecture layers caching on top of BasicS3Dict to provide:
+    - Fast local access for frequently accessed items
+    - Efficient batch operations
+    - ETag-based change detection for mutable dictionaries
+    - Optimized append-only performance when append_only=True
+    """
+    
+    def __init__(self, bucket_name: str = "my_bucket",
+                 region: str = None,
+                 root_prefix: str = "",
+                 base_dir: str = S3DICT_NEW_DEFAULT_BASE_DIR,
+                 serialization_format: str = "pkl",
+                 digest_len: int = 8,
+                 append_only: bool = False,
+                 base_class_for_values: Optional[type] = None,
+                 *args, **kwargs):
+        """Initialize an S3-backed persistent dictionary with local caching.
+
+        Args:
+            bucket_name: Name of the S3 bucket to use.
+            region: AWS region for the bucket.
+            root_prefix: Common S3 key prefix under which all objects are stored.
+            base_dir: Local directory path for caching.
+            serialization_format: File extension/format for stored values.
+            digest_len: Number of base32 MD5 hash characters for collision prevention.
+            append_only: If True, prevents modification/deletion of existing items.
+            base_class_for_values: Optional base class that all stored values must inherit from.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+        """
+        super().__init__(append_only=append_only,
+                         base_class_for_values=base_class_for_values,
+                         serialization_format=serialization_format)
+        
+        # Create the main S3 storage using BasicS3Dict
+        self._main_dict = BasicS3Dict(
+            bucket_name=bucket_name,
+            region=region,
+            root_prefix=root_prefix,
+            serialization_format=serialization_format,
+            append_only=append_only,
+            base_class_for_values=base_class_for_values
+        )
+        
+        # Set up local cache parameters for FileDirDict
+        individual_subdicts_params = {self.serialization_format: {}}
+        
+        if not append_only:
+            self.etag_serialization_format = f"{self.serialization_format}_etag"
+            individual_subdicts_params[self.etag_serialization_format] = {
+                "base_class_for_values": str}
+        
+        # Create local cache using OverlappingMultiDict with FileDirDict
+        self.local_cache = OverlappingMultiDict(
+            dict_type=FileDirDict,
+            shared_subdicts_params={
+                "base_dir": base_dir,
+                "append_only": append_only,
+                "base_class_for_values": base_class_for_values,
+                "digest_len": digest_len
+            },
+            **individual_subdicts_params)
+        
+        # Get the data cache
+        self._data_cache = getattr(self.local_cache, self.serialization_format)
+        
+        # Create the appropriate cached wrapper
+        if append_only:
+            # Use AppendOnlyDictCached for append-only mode
+            self._cached_dict = AppendOnlyDictCached(
+                main_dict=self._main_dict,
+                data_cache=self._data_cache
+            )
+        else:
+            # Use MutableDictCached for mutable mode with ETag cache
+            self._etag_cache = getattr(self.local_cache, self.etag_serialization_format)
+            self._cached_dict = MutableDictCached(
+                main_dict=self._main_dict,
+                data_cache=self._data_cache,
+                etag_cache=self._etag_cache
+            )
+    
+    @property
+    def digest_len(self) -> int:
+        """Get the digest length used for collision prevention."""
+        return self._data_cache.digest_len
+    
+    def get_params(self):
+        """Return configuration parameters as a dictionary."""
+        # Get params from the main dict and local cache
+        params = self._main_dict.get_params()
+        cache_params = self._data_cache.get_params()
+        
+        # Add cache-specific params
+        params["base_dir"] = cache_params["base_dir"]
+        params["digest_len"] = cache_params["digest_len"]
+
+        params = sort_dict_by_keys(params)
+        
+        return params
+    
+    @property
+    def base_url(self) -> str:
+        """Get the base S3 URL."""
+        return self._main_dict.base_url
+    
+    @property
+    def base_dir(self) -> str:
+        """Get the base directory for local cache."""
+        return self._data_cache.base_dir
+    
+    def __contains__(self, key: NonEmptyPersiDictKey) -> bool:
+        """Check if key exists in the dictionary."""
+        return self._cached_dict.__contains__(key)
+    
+    def __getitem__(self, key: NonEmptyPersiDictKey) -> Any:
+        """Get item from dictionary."""
+        return self._cached_dict.__getitem__(key)
+    
+    def __setitem__(self, key: NonEmptyPersiDictKey, value: Any) -> None:
+        """Set item in dictionary."""
+        self._cached_dict.__setitem__(key, value)
+    
+    def __delitem__(self, key: NonEmptyPersiDictKey) -> None:
+        """Delete item from dictionary."""
+        self._cached_dict.__delitem__(key)
+    
+    def __len__(self) -> int:
+        """Get number of items in dictionary."""
+        return self._cached_dict.__len__()
+    
+    def _generic_iter(self, result_type: set[str]):
+        """Generic iteration over dictionary items."""
+        return self._cached_dict._generic_iter(result_type)
+    
+    def get_subdict(self, key: PersiDictKey):
+        """Get a subdictionary for the given key prefix."""
+        return self._main_dict.get_subdict(key)
+    
+    def timestamp(self, key: NonEmptyPersiDictKey):
+        """Get the timestamp of when the item was last modified."""
+        return self._cached_dict.timestamp(key)
+    
+    # Additional methods that might be needed for ETag support
+    def get_item_if_etag_changed(self, key: NonEmptyPersiDictKey, etag: Optional[str]):
+        """Get item only if ETag has changed (for mutable dicts)."""
+        if hasattr(self._cached_dict, 'get_item_if_etag_changed'):
+            return self._cached_dict.get_item_if_etag_changed(key, etag)
+        else:
+            # For append-only dicts, just get the item
+            return self._cached_dict.__getitem__(key)
+    
+    def set_item_get_etag(self, key: NonEmptyPersiDictKey, value: Any):
+        """Set item and return ETag (for mutable dicts)."""
+        if hasattr(self._cached_dict, 'set_item_get_etag'):
+            return self._cached_dict.set_item_get_etag(key, value)
+        else:
+            # For append-only dicts, just set the item
+            self._cached_dict.__setitem__(key, value)
+            return None
+    
+    def discard(self, key: NonEmptyPersiDictKey) -> bool:
+        """Delete an item without raising an exception if it doesn't exist.
+        
+        This method fixes the issue where cached dictionaries return multiple
+        success counts for a single key deletion.
+        
+        Args:
+            key: Key to delete.
+            
+        Returns:
+            bool: True if the item existed and was deleted; False otherwise.
+        """
+        key = NonEmptySafeStrTuple(key)
+
+        try:
+            del self[key]
+            return True
+        except KeyError:
+            return False
+
+
+S3Dict = S3Dict_FileDirCached # Alias for backward compatibility
+
+
+parameterizable.register_parameterizable_class(S3Dict_FileDirCached)

persidict/{s3_dict.py → s3_dict_legacy.py}

@@ -10,47 +10,55 @@ from botocore.exceptions import ClientError
 import parameterizable
 from parameterizable.dict_sorter import sort_dict_by_keys
 
-from .safe_str_tuple import SafeStrTuple
+from .safe_str_tuple import SafeStrTuple, NonEmptySafeStrTuple
 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, Joker
-from .file_dir_dict import FileDirDict, PersiDictKey, non_empty_persidict_key
+from .persi_dict import PersiDict, NonEmptyPersiDictKey
+from .singletons import Joker, EXECUTION_IS_COMPLETE, ETagHasNotChangedFlag
+from .file_dir_dict import FileDirDict, PersiDictKey
 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.
+class S3Dict_Legacy(PersiDict):
+    """A persistent dictionary that stores key-value pairs as S3 objects with local caching.
     
     Each key-value pair is stored as a separate S3 object in the specified bucket.
+    S3Dict_Legacy provides intelligent local caching to minimize S3 API calls and improve
+    performance by using conditional requests with ETags to detect changes.
     
     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:
+    S3Dict_Legacy supports multiple serialization formats:
     - Binary storage using pickle ('pkl' format)  
     - Human-readable text using jsonpickle ('json' format)
     - Plain text for string values (other formats)
     
+    Key Features:
+        - Local file-based caching for improved read performance
+        - ETag-based conditional requests to minimize unnecessary downloads
+        - Automatic cache invalidation when S3 objects change
+        - Seamless fallback to S3 when cached data is stale
+    
     Note:
         Unlike native Python dictionaries, insertion order is not preserved.
-        Operations may incur S3 API costs and network latency.
+        Operations may incur S3 API costs and network latency, though caching
+        significantly reduces this overhead for repeated access patterns.
     """
     region: str
     bucket_name: str
     root_prefix: str
-    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,
+                 serialization_format: str = "pkl",
                  digest_len: int = 8,
+                 append_only: bool = False,
                  base_class_for_values: Optional[type] = None,
                  *args, **kwargs):
         """Initialize an S3-backed persistent dictionary.
@@ -64,15 +72,15 @@ class S3Dict(PersiDict):
                 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:
+            serialization_format: 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
+            append_only: 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 inherit from. When specified (and not str), serialization_format
                 must be 'pkl' or 'json' for proper serialization.
             *args: Additional positional arguments (ignored, reserved for compatibility).
             **kwargs: Additional keyword arguments (ignored, reserved for compatibility).
@@ -82,28 +90,29 @@ class S3Dict(PersiDict):
             allow. Network connectivity and valid AWS credentials are required.
         """
 
-        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"
+        super().__init__(append_only=append_only,
+                         base_class_for_values=base_class_for_values,
+                         serialization_format=serialization_format)
+        individual_subdicts_params = {self.serialization_format: {}}
+
+        if not append_only:
+            self.etag_serialization_format = f"{self.serialization_format}_etag"
+            individual_subdicts_params[self.etag_serialization_format] = {
+                "base_class_for_values": str}
 
         self.local_cache = OverlappingMultiDict(
             dict_type=FileDirDict,
             shared_subdicts_params={
                 "base_dir": base_dir,
-                "immutable_items": immutable_items,
+                "append_only": append_only,
                 "base_class_for_values": base_class_for_values,
                 "digest_len": digest_len
             },
-            **{
-                self.file_type: {},
-                self.etag_file_type: {"base_class_for_values": str}
-            }
-        )
+            **individual_subdicts_params)
 
-        self.main_cache = getattr(self.local_cache, self.file_type)
-        self.etag_cache = getattr(self.local_cache, self.etag_file_type)
+        self.main_cache = getattr(self.local_cache, self.serialization_format)
+        if not self.append_only:
+            self.etag_cache = getattr(self.local_cache, self.etag_serialization_format)
 
         self.region = region
         if region is None:
@@ -138,10 +147,14 @@ class S3Dict(PersiDict):
 
         self.bucket_name = bucket_name
 
-        self.root_prefix=root_prefix
+        self.root_prefix = root_prefix
         if len(self.root_prefix) and self.root_prefix[-1] != "/":
             self.root_prefix += "/"
 
+    @property
+    def digest_len(self) -> int:
+        return self.main_cache.digest_len
+
 
     def get_params(self):
         """Return configuration parameters as a dictionary.
@@ -187,23 +200,23 @@ class S3Dict(PersiDict):
         return self.main_cache.base_dir
 
 
-    def _build_full_objectname(self, key: PersiDictKey) -> str:
+    def _build_full_objectname(self, key: NonEmptyPersiDictKey) -> str:
         """Convert a key into a full S3 object key.
 
         Args:
             key: Dictionary key (string or sequence of strings) or SafeStrTuple.
 
         Returns:
-            str: The complete S3 object key including root_prefix and file_type
+            str: The complete S3 object key including root_prefix and serialization_format
             extension, with digest-based collision prevention applied if enabled.
         """
-        key = non_empty_persidict_key(key)
-        key = sign_safe_str_tuple(key, self.digest_len)
-        objectname = self.root_prefix +  "/".join(key)+ "." + self.file_type
+        key = NonEmptySafeStrTuple(key)
+        key = sign_safe_str_tuple(key, 0)
+        objectname = self.root_prefix + "/".join(key) + "." + self.serialization_format
         return objectname
 
 
-    def __contains__(self, key: PersiDictKey) -> bool:
+    def __contains__(self, key: NonEmptyPersiDictKey) -> bool:
         """Check if the specified key exists in the dictionary.
 
         For immutable dictionaries, checks the local cache first. Otherwise,
@@ -216,8 +229,8 @@ class S3Dict(PersiDict):
             bool: True if the key exists in S3 (or local cache for immutable
             items), False otherwise.
         """
-        key = non_empty_persidict_key(key)
-        if self.immutable_items and key in self.main_cache:
+        key = NonEmptySafeStrTuple(key)
+        if self.append_only and key in self.main_cache:
                 return True
         try:
             obj_name = self._build_full_objectname(key)
@@ -225,14 +238,14 @@ class S3Dict(PersiDict):
             return True
         except ClientError as e:
             if e.response['ResponseMetadata']['HTTPStatusCode'] == 404:
-                self.main_cache.delete_if_exists(key)
-                self.etag_cache.delete_if_exists(key)
+                self.main_cache.discard(key)
+                self.etag_cache.discard(key)
                 return False
             else:
                 raise
 
 
-    def __getitem__(self, key: PersiDictKey) -> Any:
+    def __getitem__(self, key: NonEmptyPersiDictKey) -> Any:
         """Retrieve the value stored for a key.
 
         For immutable dictionaries with cached values, returns the cached copy.
@@ -249,15 +262,15 @@ class S3Dict(PersiDict):
             KeyError: If the key does not exist in S3.
         """
 
-        key = non_empty_persidict_key(key)
+        key = NonEmptySafeStrTuple(key)
 
-        if self.immutable_items and key in self.main_cache:
+        if self.append_only and key in self.main_cache:
             return self.main_cache[key]
 
         obj_name = self._build_full_objectname(key)
 
         cached_etag = None
-        if not self.immutable_items and key in self.main_cache and key in self.etag_cache:
+        if not self.append_only and key in self.main_cache and key in self.etag_cache:
             cached_etag = self.etag_cache[key]
 
         try:
@@ -268,19 +281,22 @@ class S3Dict(PersiDict):
             response = self.s3_client.get_object(**get_kwargs)
 
             # 200 OK: object was downloaded, either because it's new or changed.
-            s3_etag = response.get("ETag")
             body = response['Body']
 
             # Deserialize and cache the S3 object content
-            if self.file_type == 'json':
+            if self.serialization_format == 'json':
                 deserialized_value = jsonpickle.loads(body.read().decode('utf-8'))
-            elif self.file_type == 'pkl':
+            elif self.serialization_format == '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
+
+            if not self.append_only:
+                # Cache the S3 ETag for future conditional requests
+                s3_etag = response.get("ETag")
+                self.etag_cache[key] = s3_etag
 
         except ClientError as e:
             if e.response['ResponseMetadata']['HTTPStatusCode'] == 304:
@@ -295,7 +311,7 @@ class S3Dict(PersiDict):
         return self.main_cache[key]
 
 
-    def __setitem__(self, key: PersiDictKey, value: Any):
+    def __setitem__(self, key: NonEmptyPersiDictKey, value: Any):
         """Store a value for a key in both S3 and local cache.
 
         Handles special joker values (KEEP_CURRENT, DELETE_CURRENT) for
@@ -304,22 +320,20 @@ class S3Dict(PersiDict):
         the S3 ETag for efficient future retrievals.
 
         Args:
-            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings) or NonEmptyPersiDictKey.
             value: Value to store, or a joker command (KEEP_CURRENT or 
-                DELETE_CURRENT from the jokers module).
+                DELETE_CURRENT).
 
         Raises:
             KeyError: If attempting to modify an existing item when
-                immutable_items is True.
+                append_only is True.
             TypeError: If value is a PersiDict instance or does not match
                 the required base_class_for_values when specified.
         """
 
-        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
+        key = NonEmptySafeStrTuple(key)
+        if self._process_setitem_args(key, value) is EXECUTION_IS_COMPLETE:
+            return None
 
         obj_name = self._build_full_objectname(key)
 
@@ -330,6 +344,11 @@ class S3Dict(PersiDict):
         file_path = self.main_cache._build_full_path(key)
         self.s3_client.upload_file(file_path, self.bucket_name, obj_name)
 
+        if self.append_only:
+            # For immutable items, the local cache is authoritative; no need to
+            # verify ETag from S3 as the item cannot change after initial upload
+            return
+
         try:
             # Cache the S3 ETag for efficient conditional requests on future reads
             head = self.s3_client.head_object(
@@ -337,24 +356,25 @@ class S3Dict(PersiDict):
             self.etag_cache[key] = head.get("ETag")
         except ClientError:
             # Remove stale ETag on failure to force fresh downloads later
-            self.etag_cache.delete_if_exists(key)
+            self.etag_cache.discard(key)
 
 
-    def __delitem__(self, key: PersiDictKey):
+    def __delitem__(self, key: NonEmptyPersiDictKey):
         """Delete the stored value for a key from both S3 and local cache.
 
         Args:
-            key: Dictionary key (string or sequence of strings) or SafeStrTuple.
+            key: Dictionary key (string or sequence of strings)
+                or NonEmptyPersiDictKey.
 
         Raises:
-            KeyError: If immutable_items is True, or if the key does not exist.
+            KeyError: If append_only is True, or if the key does not exist.
         """
-        key = non_empty_persidict_key(key)
-        PersiDict.__delitem__(self, key)
+        key = NonEmptySafeStrTuple(key)
+        self._process_delitem_args(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)
+        self.s3_client.delete_object(Bucket=self.bucket_name, Key=obj_name)
+        self.etag_cache.discard(key)
+        self.main_cache.discard(key)
 
 
     def __len__(self) -> int:
@@ -370,11 +390,11 @@ class S3Dict(PersiDict):
         """
 
         num_files = 0
-        suffix = "." + self.file_type
+        suffix = "." + self.serialization_format
 
         paginator = self.s3_client.get_paginator("list_objects_v2")
         page_iterator = paginator.paginate(
-            Bucket=self.bucket_name, Prefix = self.root_prefix)
+            Bucket=self.bucket_name, Prefix=self.root_prefix)
 
         for page in page_iterator:
             contents = page.get("Contents")
@@ -412,10 +432,10 @@ class S3Dict(PersiDict):
                 unsupported field names).
         """
 
-        PersiDict._generic_iter(self, result_type)
+        self._process_generic_iter_args(result_type)
 
-        suffix = "." + self.file_type
-        ext_len = len(self.file_type) + 1
+        suffix = "." + self.serialization_format
+        ext_len = len(self.serialization_format) + 1
         prefix_len = len(self.root_prefix)
 
         def splitter(full_name: str) -> SafeStrTuple:
@@ -446,7 +466,7 @@ class S3Dict(PersiDict):
             """
             paginator = self.s3_client.get_paginator("list_objects_v2")
             page_iterator = paginator.paginate(
-                Bucket=self.bucket_name, Prefix = self.root_prefix)
+                Bucket=self.bucket_name, Prefix=self.root_prefix)
 
             for page in page_iterator:
                 contents = page.get("Contents")
@@ -462,7 +482,7 @@ class S3Dict(PersiDict):
 
                     if "keys" in result_type:
                         key_to_return = unsign_safe_str_tuple(
-                            obj_key, self.digest_len)
+                            obj_key, 0)
                         to_return.append(key_to_return)
 
                     if "values" in result_type:
@@ -480,10 +500,11 @@ class S3Dict(PersiDict):
         return step()
 
 
-    def get_subdict(self, key: PersiDictKey) -> S3Dict:
+    def get_subdict(self, key: PersiDictKey) -> S3Dict_Legacy:
         """Create a subdictionary scoped to items with the specified prefix.
 
         Returns an empty subdictionary if no items exist under the prefix.
+        If the prefix is empty, the entire dictionary is returned.
         This method is not part of the standard Python dictionary interface.
 
         Args:
@@ -491,35 +512,34 @@ class S3Dict(PersiDict):
                 used to scope items stored under this dictionary.
 
         Returns:
-            S3Dict: A new S3Dict instance with root_prefix extended by the given
-            key, sharing the parent's bucket, region, file_type, and other
+            S3Dict_Legacy: A new S3Dict instance with root_prefix extended by the given
+            key, sharing the parent's bucket, region, serialization_format, and other
             configuration settings.
         """
 
         key = SafeStrTuple(key)
         if len(key):
-            key = sign_safe_str_tuple(key, self.digest_len)
-            full_root_prefix = self.root_prefix +  "/".join(key)
+            key = sign_safe_str_tuple(key, 0)
+            full_root_prefix = self.root_prefix + "/".join(key)
         else:
             full_root_prefix = self.root_prefix
 
         new_dir_path = self.main_cache._build_full_path(
-            key, create_subdirs = True, is_file_path = False)
-
-        new_dict = S3Dict(
-            bucket_name = self.bucket_name
-            , region = self.region
-            , root_prefix = full_root_prefix
-            , base_dir = new_dir_path
-            , file_type = self.file_type
-            , immutable_items = self.immutable_items
-            , digest_len = self.digest_len
-            , base_class_for_values = self.base_class_for_values)
+            key, create_subdirs=True, is_file_path=False)
+
+        new_dict = S3Dict_Legacy(
+            bucket_name=self.bucket_name,
+            region=self.region,
+            root_prefix=full_root_prefix,
+            base_dir=new_dir_path,
+            serialization_format=self.serialization_format,
+            append_only=self.append_only,
+            base_class_for_values=self.base_class_for_values)
 
         return new_dict
 
 
-    def timestamp(self, key: PersiDictKey) -> float:
+    def timestamp(self, key: NonEmptyPersiDictKey) -> float:
         """Get the last modification timestamp for a key.
 
         This method is not part of the standard Python dictionary interface.
@@ -535,10 +555,11 @@ class S3Dict(PersiDict):
         Raises:
             KeyError: If the key does not exist in S3.
         """
-        key = non_empty_persidict_key(key)
+        key = NonEmptySafeStrTuple(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()
 
 
-parameterizable.register_parameterizable_class(S3Dict)
+parameterizable.register_parameterizable_class(S3Dict_Legacy)
+