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

persidict/persi_dict.py

@@ -23,37 +23,24 @@ from parameterizable import ParameterizableClass, sort_dict_by_keys
 from typing import Any, Sequence, Optional
 from collections.abc import MutableMapping
 
-from .jokers import KEEP_CURRENT, DELETE_CURRENT, Joker
+from . import NonEmptySafeStrTuple
+from .singletons import (KEEP_CURRENT, DELETE_CURRENT, Joker,
+                         CONTINUE_NORMAL_EXECUTION, StatusFlag, EXECUTION_IS_COMPLETE,
+                         ETagHasNotChangedFlag, ETAG_HAS_NOT_CHANGED)
+from .safe_chars import contains_unsafe_chars
 from .safe_str_tuple import SafeStrTuple
 
 PersiDictKey = SafeStrTuple | Sequence[str] | str
+NonEmptyPersiDictKey = NonEmptySafeStrTuple | Sequence[str] | str
 """A value which can be used as a key for PersiDict.
 
-PersiDict instances accept keys in the form of SafeStrTuple,
-or a string, or a sequence of strings.
+PersiDict instances accept keys in the form of (NonEmpty)SafeStrTuple,
+or a string, or a (non-empty) 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,
 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.
 
@@ -62,52 +49,65 @@ class PersiDict(MutableMapping, ParameterizableClass):
     similar to Python's dict but does not guarantee insertion order and adds
     persistence-specific helpers (e.g., timestamp()).
 
-    Attributes:
-        immutable_items (bool):
-            If True, items are write-once: existing values cannot be modified or
-            deleted.
-        digest_len (int):
-            Length of a base32 MD5 digest fragment used to suffix each key
-            component to avoid collisions on case-insensitive filesystems. 0
-            disables suffixing.
+    Attributes (can't be changed after initialization):
+        append_only (bool):
+            If True, items are immutable and non-removable: existing values 
+            cannot be modified or deleted.
         base_class_for_values (Optional[type]):
             Optional base class that all values must inherit from. If None, any
             type is accepted.
+        serialization_format (str):
+            File extension/format for stored values (e.g., "pkl", "json").
     """
 
-    digest_len:int
-    immutable_items:bool
+    append_only:bool
     base_class_for_values:Optional[type]
+    serialization_format:str
 
     def __init__(self,
-                 immutable_items: bool = False,
-                 digest_len: int = 8,
-                 base_class_for_values: Optional[type] = None,
+                 append_only: bool = False,
+                 base_class_for_values: type|None = None,
+                 serialization_format: str = "pkl",
                  *args, **kwargs):
         """Initialize base parameters shared by all persistent dictionaries.
 
         Args:
-            immutable_items (bool): If True, items cannot be modified or deleted.
+            append_only (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.
+            serialization_format (str): File extension/format for stored values.
+                Defaults to "pkl".
             *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.
-        """
-        self.digest_len = int(digest_len)
-        if digest_len < 0:
-            raise ValueError("digest_len must be non-negative")
-        self.immutable_items = bool(immutable_items)
+            ValueError: If serialization_format is an empty string,
+            or contains unsafe characters, or not 'jason' or 'pkl'
+            for non-string values.
+
+            TypeError: If base_class_for_values is not a type or None.
+        """
+        
+        self._append_only = bool(append_only)
+        
+        if len(serialization_format) == 0:
+            raise ValueError("serialization_format must be a non-empty string")
+        if contains_unsafe_chars(serialization_format):
+            raise ValueError("serialization_format must contain only URL/filename-safe characters")
+        self.serialization_format = str(serialization_format)
+
+        if not isinstance(base_class_for_values, (type, type(None))):
+            raise TypeError("base_class_for_values must be a type or None")
+        if (base_class_for_values is None or
+                not issubclass(base_class_for_values, str)):
+            if serialization_format not in {"json", "pkl"}:
+                raise ValueError("For non-string values serialization_format must be either 'pkl' or 'json'.")
         self.base_class_for_values = base_class_for_values
+
         ParameterizableClass.__init__(self)
 
 
@@ -120,41 +120,38 @@ class PersiDict(MutableMapping, ParameterizableClass):
                 built-in dict.
         """
         params = dict(
-            immutable_items=self.immutable_items,
-            digest_len=self.digest_len,
-            base_class_for_values=self.base_class_for_values
+            append_only=self.append_only,
+            base_class_for_values=self.base_class_for_values,
+            serialization_format=self.serialization_format
         )
         sorted_params = sort_dict_by_keys(params)
         return sorted_params
 
+    def __copy__(self) -> 'PersiDict':
+        """Return a shallow copy of the dictionary.
 
-    @property
-    @abstractmethod
-    def base_url(self):
-        """Base URL identifying the storage location.
+        This creates a new PersiDict instance with the same parameters, pointing
+        to the same underlying storage. This is analogous to `dict.copy()`.
 
         Returns:
-            str: A URL-like string (e.g., s3://bucket/prefix or file://...).
-
-        Raises:
-            NotImplementedError: Must be provided by subclasses.
+            PersiDict: A new PersiDict instance that is a shallow copy of this one.
         """
-        raise NotImplementedError
+        if type(self) is PersiDict:
+            raise NotImplementedError("PersiDict is an abstract base class"
+                                      " and cannot be copied directly")
+        params = self.get_params()
+        return self.__class__(**params)
 
 
     @property
-    @abstractmethod
-    def base_dir(self):
-        """Base directory on the local filesystem, if applicable.
+    def append_only(self) -> bool:
+        """Whether the store is append-only.
 
         Returns:
-            str: Path to a local base directory used by the store.
-
-        Raises:
-            NotImplementedError: Must be provided by subclasses that use local
-                storage.
+            bool: True if the store is append-only (contains immutable items
+            that cannot be modified or deleted), False otherwise.
         """
-        raise NotImplementedError
+        return self._append_only
 
 
     def __repr__(self) -> str:
@@ -178,7 +175,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     @abstractmethod
-    def __contains__(self, key:PersiDictKey) -> bool:
+    def __contains__(self, key:NonEmptyPersiDictKey) -> bool:
         """Check whether a key exists in the store.
 
         Args:
@@ -187,13 +184,40 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             bool: True if key exists, False otherwise.
         """
-        if type(self) is PersiDict:
-            raise NotImplementedError("PersiDict is an abstract base class"
-                                        " and cannot check items directly")
+        raise NotImplementedError("PersiDict is an abstract base class"
+                                    " and cannot check items directly")
+
+
+    def get_item_if_etag_changed(self, key: NonEmptyPersiDictKey, etag: str | None
+                                 ) -> tuple[Any, str|None]|ETagHasNotChangedFlag:
+        """Retrieve the value for a key only if its ETag has changed.
+
+        This method is absent in the original dict API.
+        By default, the timestamp is used in lieu of ETag.
+
+        Args:
+            key: Dictionary key (string or sequence of strings)
+                or NonEmptySafeStrTuple.
+            etag: The ETag value to compare against.
+
+        Returns:
+            tuple[Any, str|None] | ETagHasNotChangedFlag: The deserialized
+                value if the ETag has changed, along with the new ETag,
+                or ETAG_HAS_NOT_CHANGED if it matches the provided etag.
+
+        Raises:
+            KeyError: If the key does not exist.
+        """
+        key = NonEmptySafeStrTuple(key)
+        current_etag = self.etag(key)
+        if etag == current_etag:
+            return ETAG_HAS_NOT_CHANGED
+        else:
+            return self[key], current_etag
 
 
     @abstractmethod
-    def __getitem__(self, key:PersiDictKey) -> Any:
+    def __getitem__(self, key:NonEmptyPersiDictKey) -> Any:
         """Retrieve the value for a key.
 
         Args:
@@ -202,98 +226,167 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             Any: The stored value.
         """
-        if type(self) is PersiDict:
-            raise NotImplementedError("PersiDict is an abstract base class"
-                                        " and cannot retrieve items directly")
+        raise NotImplementedError("PersiDict is an abstract base class"
+                                  " and cannot retrieve items directly")
 
 
-    def __setitem__(self, key:PersiDictKey, value:Any):
-        """Set the value for a key.
 
-        Special values KEEP_CURRENT and DELETE_CURRENT are interpreted as
-        commands to keep or delete the current value respectively.
+    def _process_setitem_args(self, key: NonEmptyPersiDictKey, value: Any
+                              ) -> StatusFlag:
+        """Perform the first steps for setting an item.
 
         Args:
-            key: Key (string or sequence of strings) or SafeStrTuple.
-            value: Value to store, or a Joker command.
+            key: Dictionary key (string or sequence of strings
+                or NonEmptySafeStrTuple).
+            value: Value to store, or a joker command (KEEP_CURRENT or
+                DELETE_CURRENT).
 
         Raises:
-            KeyError: If attempting to modify an existing key when
-                immutable_items is True.
-            NotImplementedError: Subclasses must implement actual writing.
+            KeyError: If attempting to modify an existing item when
+                append_only is True.
+            TypeError: If the value is a PersiDict instance or does not match
+                the required base_class_for_values when specified.
+
+        Returns:
+            StatusFlag: CONTINUE_NORMAL_EXECUTION if the caller should
+                proceed with storing the value; EXECUTION_IS_COMPLETE if a
+                joker command was processed and no further action is needed.
         """
+
         if value is KEEP_CURRENT:
-            return
-        elif self.immutable_items:
-            if key in self:
-                raise KeyError("Can't modify an immutable key-value pair")
+            return EXECUTION_IS_COMPLETE
+        elif self.append_only and (value is DELETE_CURRENT or key in self):
+            raise KeyError("Can't modify an immutable key-value pair")
+        elif isinstance(value, PersiDict):
+            raise TypeError("Cannot store a PersiDict instance directly")
 
-        key = non_empty_persidict_key(key)
+        key = NonEmptySafeStrTuple(key)
 
         if value is DELETE_CURRENT:
-            self.delete_if_exists(key)
-            return
+            self.discard(key)
+            return EXECUTION_IS_COMPLETE
 
         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")
+        return CONTINUE_NORMAL_EXECUTION
 
 
-    def __delitem__(self, key:PersiDictKey):
-        """Delete a key and its value.
+    def set_item_get_etag(self, key: NonEmptyPersiDictKey, value: Any) -> str|None:
+        """Store a value for a key directly in the dict and return the new ETag.
+
+        Handles special joker values (KEEP_CURRENT, DELETE_CURRENT) for
+        conditional operations. Validates value types against base_class_for_values
+        if specified, then serializes and uploads directly to S3.
+
+        This method is absent in the original dict API.
+        By default, the timestamp is used in lieu of ETag.
+
+        Args:
+            key: Dictionary key (string or sequence of strings)
+                or NonEmptySafeStrTuple.
+            value: Value to store, or a joker command (KEEP_CURRENT or
+                DELETE_CURRENT).
+
+        Returns:
+            str|None: The ETag of the newly stored object,
+            or None if the ETag was not provided as a result of the operation.
+
+        Raises:
+            KeyError: If attempting to modify an existing item when
+                append_only is True.
+            TypeError: If the value is a PersiDict instance or does not match
+                the required base_class_for_values when specified.
+        """
+
+        key = NonEmptySafeStrTuple(key)
+        if self._process_setitem_args(key, value) is EXECUTION_IS_COMPLETE:
+            return None
+        self[key] = value
+        return self.etag(key)
+
+    @abstractmethod
+    def __setitem__(self, key:NonEmptyPersiDictKey, value:Any):
+        """Set the value for a key.
+
+        Special values KEEP_CURRENT and DELETE_CURRENT are interpreted as
+        commands to keep or delete the current value respectively.
 
         Args:
             key: Key (string or sequence of strings) or SafeStrTuple.
+            value: Value to store, or a Joker command.
 
         Raises:
-            KeyError: If immutable_items is True.
-            NotImplementedError: Subclasses must implement deletion.
+            KeyError: If attempting to modify an existing key when
+                append_only is True.
+            NotImplementedError: Subclasses must implement actual writing.
         """
-        if self.immutable_items:
+        if self._process_setitem_args(key, value) is EXECUTION_IS_COMPLETE:
+            return
+
+        raise NotImplementedError("PersiDict is an abstract base class"
+                                  " and cannot store items directly")
+
+
+    def _process_delitem_args(self, key: NonEmptyPersiDictKey) -> None:
+        """Perform the first steps for deleting an item.
+
+        Args:
+            key: Dictionary key (string or sequence of strings
+                or NonEmptySafeStrTuple).
+        Raises:
+            KeyError: If attempting to delete an item when
+                append_only is True or if the key does not exist.
+        """
+        if self.append_only:
             raise KeyError("Can't delete an immutable key-value pair")
-        if type(self) is PersiDict:
-            raise NotImplementedError("PersiDict is an abstract base class"
-                                      " and cannot delete items directly")
 
-        key = non_empty_persidict_key(key)
+        key = NonEmptySafeStrTuple(key)
 
         if key not in self:
             raise KeyError(f"Key {key} not found")
 
 
+    @abstractmethod
+    def __delitem__(self, key:NonEmptyPersiDictKey):
+        """Delete a key and its value.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+
+        Raises:
+            KeyError: If append_only is True or if the key does not exist.
+            NotImplementedError: Subclasses must implement deletion.
+        """
+        self._process_delitem_args(key)
+        raise NotImplementedError("PersiDict is an abstract base class"
+                                  " and cannot delete items directly")
+
+
     @abstractmethod
     def __len__(self) -> int:
         """Return the number of stored items.
 
         Returns:
             int: Number of key-value pairs.
+        Raises:
+            NotImplementedError: Subclasses must implement counting.
         """
-        if type(self) is PersiDict:
-            raise NotImplementedError("PersiDict is an abstract base class"
-                                        " and cannot count items directly")
+        raise NotImplementedError("PersiDict is an abstract base class"
+                                    " and cannot count items directly")
 
 
-    @abstractmethod
-    def _generic_iter(self, result_type: set[str]) -> Any:
-        """Underlying implementation for iterator helpers.
+    def _process_generic_iter_args(self, result_type: set[str]) -> None:
+        """Validate arguments for iterator helpers.
 
         Args:
             result_type: A set indicating desired fields among {'keys',
                 'values', 'timestamps'}.
-
-        Returns:
-            Any: An iterator yielding keys, values, and/or timestamps based on
-                result_type.
-
         Raises:
             TypeError: If result_type is not a set.
             ValueError: If result_type contains invalid entries or an invalid number of items.
-            NotImplementedError: Subclasses must implement the concrete iterator.
         """
         if not isinstance(result_type, set):
             raise TypeError("result_type must be a set of strings")
@@ -304,9 +397,28 @@ 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'")
-        if type(self) is PersiDict:
-            raise NotImplementedError("PersiDict is an abstract base class"
-                                        " and cannot iterate items directly")
+
+
+    @abstractmethod
+    def _generic_iter(self, result_type: set[str]) -> Any:
+        """Underlying implementation for iterator helpers.
+
+        Args:
+            result_type: A set indicating desired fields among {'keys',
+                'values', 'timestamps'}.
+
+        Returns:
+            Any: An iterator yielding keys, values, and/or timestamps based on
+                result_type.
+
+        Raises:
+            TypeError: If result_type is not a set.
+            ValueError: If result_type contains invalid entries or an invalid number of items.
+            NotImplementedError: Subclasses must implement the concrete iterator.
+        """
+        self._process_generic_iter_args(result_type)
+        raise NotImplementedError("PersiDict is an abstract base class"
+                                  " and cannot iterate items directly")
 
 
     def __iter__(self):
@@ -372,7 +484,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         return self._generic_iter({"keys", "values", "timestamps"})
 
 
-    def setdefault(self, key: PersiDictKey, default: Any = None) -> Any:
+    def setdefault(self, key: NonEmptyPersiDictKey, 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,
@@ -389,20 +501,19 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Raises:
             TypeError: If default is a Joker command (KEEP_CURRENT/DELETE_CURRENT).
         """
-        key = SafeStrTuple(key)
+        key = NonEmptySafeStrTuple(key)
         if isinstance(default, Joker):
             raise TypeError("default must be a regular value, not a Joker command")
-        if key in self:
+        try:
             return self[key]
-        else:
+        except KeyError:
             self[key] = default
             return default
 
-
     def __eq__(self, other: PersiDict) -> bool:
         """Compare dictionaries for equality.
 
-        If other is a PersiDict instance, compares portable parameters for equality.
+        If other is a PersiDict instance, compares parameters for equality.
         Otherwise, attempts to compare as a mapping by comparing all keys and values.
 
         Args:
@@ -411,17 +522,21 @@ class PersiDict(MutableMapping, ParameterizableClass):
         Returns:
             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 type(self) is type(other) :
+                if self.get_params() == other.get_params():
+                    return True
+        except:
+            pass
+
+        try: #TODO: refactor to improve performance
             if len(self) != len(other):
                 return False
             for k in other.keys():
                 if self[k] != other[k]:
                     return False
             return True
-        except:
+        except KeyError:
             return False
 
 
@@ -451,9 +566,9 @@ class PersiDict(MutableMapping, ParameterizableClass):
         """Remove all items from the dictionary.
 
         Raises:
-            KeyError: If items are immutable (immutable_items is True).
+            KeyError: If the dictionary is append-only.
         """
-        if self.immutable_items:
+        if self.append_only:
             raise KeyError("Can't delete an immutable key-value pair")
 
         for k in self.keys():
@@ -463,7 +578,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
                 pass
 
 
-    def delete_if_exists(self, key:PersiDictKey) -> bool:
+    def discard(self, key: NonEmptyPersiDictKey) -> bool:
         """Delete an item without raising an exception if it doesn't exist.
 
         This method is absent in the original dict API.
@@ -475,36 +590,42 @@ class PersiDict(MutableMapping, ParameterizableClass):
             bool: True if the item existed and was deleted; False otherwise.
 
         Raises:
-            KeyError: If items are immutable (immutable_items is True).
+            KeyError: If the dictionary is append-only.
         """
 
-        if self.immutable_items:
+        if self.append_only:
             raise KeyError("Can't delete an immutable key-value pair")
 
-        key = non_empty_persidict_key(key)
+        key = NonEmptySafeStrTuple(key)
 
-        if key in self:
-            try:
-                del self[key]
-                return True
-            except:
-                return False
-        else:
+        try:
+            del self[key]
+            return True
+        except KeyError:
             return False
 
 
+    def delete_if_exists(self, key: NonEmptyPersiDictKey) -> bool:
+        """Backward-compatible wrapper for discard().
+
+        This method is kept for backward compatibility; new code should use
+        discard(). Behavior is identical to discard().
+        """
+        return self.discard(key)
+
     def get_subdict(self, prefix_key:PersiDictKey) -> PersiDict:
         """Get a sub-dictionary containing items with the given prefix key.
 
         Items whose keys start with the provided prefix are visible through the
         returned sub-dictionary. If the prefix does not exist, an empty
-        sub-dictionary is returned.
+        sub-dictionary is returned. If the prefix is empty, the entire
+        dictionary is returned.
 
         This method is absent in the original Python dict API.
 
         Args:
             prefix_key: Key prefix (string, sequence of strings, or SafeStrTuple)
-                identifying the sub-namespace to expose.
+                identifying the sub-dict to expose.
 
         Returns:
             PersiDict: A dictionary-like view restricted to keys under the
@@ -514,6 +635,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
             NotImplementedError: Must be implemented by subclasses that support
                 hierarchical key spaces.
         """
+
         if type(self) is PersiDict:
             raise NotImplementedError("PersiDict is an abstract base class"
                 " and cannot create sub-dictionaries directly")
@@ -533,7 +655,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         return result_subdicts
 
 
-    def random_key(self) -> PersiDictKey | None:
+    def random_key(self) -> NonEmptySafeStrTuple | None:
         """Return a random key from the dictionary.
 
         This method is absent in the original Python dict API.
@@ -556,7 +678,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         # Reservoir sampling algorithm
         i = 2
         for key in iterator:
-            # Select current key with probability 1/i
+            # Select the current key with probability 1/i
             if random.random() < 1/i:
                 result = key
             i += 1
@@ -565,7 +687,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     @abstractmethod
-    def timestamp(self, key:PersiDictKey) -> float:
+    def timestamp(self, key:NonEmptyPersiDictKey) -> float:
         """Return the last modification time of a key.
 
         This method is absent in the original dict API.
@@ -584,8 +706,19 @@ class PersiDict(MutableMapping, ParameterizableClass):
             raise NotImplementedError("PersiDict is an abstract base class"
                                       " and cannot provide timestamps directly")
 
+    def etag(self, key:NonEmptyPersiDictKey) -> str|None:
+        """Return the ETag of a key.
+
+        By default, this returns a stringified timestamp of the last
+        modification time. Subclasses may override to provide true
+        backend-specific ETags (e.g., S3).
+
+        This method is absent in the original Python dict API.
+        """
+        return f"{self.timestamp(key):.6f}"
+
 
-    def oldest_keys(self, max_n=None):
+    def oldest_keys(self, max_n=None) -> list[NonEmptySafeStrTuple]:
         """Return up to max_n oldest keys in the dictionary.
 
         This method is absent in the original Python dict API.
@@ -613,7 +746,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
             return [key for key,_ in smallest_pairs]
 
 
-    def oldest_values(self, max_n=None):
+    def oldest_values(self, max_n=None) -> list[Any]:
         """Return up to max_n oldest values in the dictionary.
 
         This method is absent in the original Python dict API.
@@ -629,7 +762,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
         return [self[k] for k in self.oldest_keys(max_n)]
 
 
-    def newest_keys(self, max_n=None):
+    def newest_keys(self, max_n=None)  -> list[NonEmptySafeStrTuple]:
         """Return up to max_n newest keys in the dictionary.
 
         This method is absent in the original Python dict API.
@@ -657,7 +790,7 @@ class PersiDict(MutableMapping, ParameterizableClass):
             return [key for key,_ in largest_pairs]
 
 
-    def newest_values(self, max_n=None):
+    def newest_values(self, max_n=None) -> list[Any]:
         """Return up to max_n newest values in the dictionary.
 
         This method is absent in the original Python dict API.