persidict 0.34.2__py3-none-any.whl → 0.35.0__py3-none-any.whl

persidict/persi_dict.py

@@ -1,21 +1,16 @@
-"""PersiDict: base class used in persistent dictionaries' hierarchy.
+"""Persistent, dict-like API for durable key-value stores.
 
-PersiDict: a base class in the hierarchy, defines unified interface
-of all persistent dictionaries. The interface is similar to the interface of
-Python's built-in Dict, with a few variations
-(e.g. insertion order is not preserved) and additional methods.
+PersiDict defines a unified interface for persistent dictionaries. The API is
+similar to Python's built-in dict with some differences (e.g., insertion order
+is not guaranteed) and several additional convenience methods.
 
-PersiDict persistently stores key-value pairs.
+Keys are sequences of URL/filename-safe strings represented by SafeStrTuple.
+Plain strings or sequences of strings are accepted and automatically coerced to
+SafeStrTuple. Values can be arbitrary Python objects unless an implementation
+restricts them via ``base_class_for_values``.
 
-A key is a sequence of strings in a form of SafeStrTuple.
-Regular strings and their sequences can also be passed to PersiDict as keys,
-in this case they will be automatically converted to SafeStrTuple.
-
-A value can be (virtually) any Python object.
-
-'Persistently' means that key-value pairs are saved in a durable storage,
-such as a local hard-drive or AWS S3 cloud, and can be retrieved
-even after the Python process that created the dictionary has terminated.
+Persistence means items are stored durably (e.g., in local files or cloud
+objects) and remain accessible across process lifetimes.
 """
 
 from __future__ import annotations
@@ -41,43 +36,24 @@ it will be automatically converted into SafeStrTuple.
 """
 
 class PersiDict(MutableMapping, ParameterizableClass):
-    """Dict-like durable store that accepts sequences of strings as keys.
-
-    An abstract base class for key-value stores. It accepts keys in a form of
-    SafeStrSequence - a URL/filename-safe sequence of strings.
-    It assumes no restrictions on types of values in the key-value pairs,
-    but allows users to impose such restrictions.
-
-    The API for the class resembles the API of Python's built-in Dict
-    (see https://docs.python.org/3/library/stdtypes.html#mapping-types-dict)
-    with a few variations (e.g. insertion order is not preserved) and
-    a few additional methods(e.g. .timestamp(key), which returns last
-    modification time for a key).
-
-    Attributes
-    ----------
-    immutable_items : bool
-                      True means an append-only dictionary: items are
-                      not allowed to be modified or deleted from a dictionary.
-                      It enables various distributed cache optimizations
-                      for remote storage.
-                      False means normal dict-like behaviour.
-
-    digest_len : int
-                 Length of a hash signature suffix which PersiDict
-                 automatically adds to each string in a key
-                 while mapping the key to an address of a value
-                 in a persistent storage backend (e.g. a filename
-                 or an S3 objectname). We need it to ensure correct work
-                 of persistent dictionaries with case-insensitive
-                 (even if case-preserving) filesystems, such as MacOS HFS.
-
-    base_class_for_values: Optional[type]
-                    A base class for values stored in the dictionary.
-                    If specified, it will be used to check types of values
-                    in the dictionary. If not specified, no type checking
-                    will be performed and all types will be allowed.
-
+    """Abstract dict-like interface for durable key-value stores.
+
+    Keys are URL/filename-safe sequences of strings (SafeStrTuple). Concrete
+    subclasses implement storage backends (e.g., filesystem, S3). The API is
+    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.
+        base_class_for_values (Optional[type]):
+            Optional base class that all values must inherit from. If None, any
+            type is accepted.
     """
 
     digest_len:int
@@ -89,6 +65,20 @@ class PersiDict(MutableMapping, ParameterizableClass):
                  , digest_len:int = 8
                  , base_class_for_values:Optional[type] = None
                  , *args, **kwargs):
+        """Initialize base parameters shared by all persistent dicts.
+
+        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).
+
+        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")
@@ -98,10 +88,12 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def get_params(self):
-        """Return a dictionary of parameters for the PersiDict object.
+        """Return configuration parameters of this dictionary.
 
-        This method is needed to support Parameterizable API.
-        The method is absent in the original dict API.
+        Returns:
+            dict: A sorted dict of parameters used to reconstruct the instance.
+                This supports the Parameterizable API and is absent in the
+                builtin dict.
         """
         params =  dict(
             immutable_items=self.immutable_items
@@ -115,9 +107,13 @@ class PersiDict(MutableMapping, ParameterizableClass):
     @property
     @abstractmethod
     def base_url(self):
-        """Return dictionary's URL
+        """Base URL identifying the storage location.
+
+        Returns:
+            str: A URL-like string (e.g., s3://bucket/prefix or file://...).
 
-        This property is absent in the original dict API.
+        Raises:
+            NotImplementedError: Must be provided by subclasses.
         """
         raise NotImplementedError
 
@@ -125,39 +121,79 @@ class PersiDict(MutableMapping, ParameterizableClass):
     @property
     @abstractmethod
     def base_dir(self):
-        """Return dictionary's base directory in the local filesystem.
+        """Base directory on the local filesystem, if applicable.
 
-        This property is absent in the original dict API.
+        Returns:
+            str: Path to a local base directory used by the store.
+
+        Raises:
+            NotImplementedError: Must be provided by subclasses that use local
+                storage.
         """
         raise NotImplementedError
 
 
     def __repr__(self) -> str:
-        """Return repr(self)"""
+        """Return a reproducible string representation.
+
+        Returns:
+            str: Representation including class name and constructor parameters.
+        """
         params = self.get_params()
         params_str = ', '.join(f'{k}={v!r}' for k, v in params.items())
         return f'{self.__class__.__name__}({params_str})'
 
 
     def __str__(self) -> str:
-        """Return str(self)"""
+        """Return a user-friendly string with all items.
+
+        Returns:
+            str: Stringified dict of items.
+        """
         return str(dict(self.items()))
 
 
     @abstractmethod
     def __contains__(self, key:PersiDictKey) -> bool:
-        """True if the dictionary has the specified key, else False."""
+        """Check whether a key exists in the store.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+
+        Returns:
+            bool: True if key exists, False otherwise.
+        """
         raise NotImplementedError
 
 
     @abstractmethod
     def __getitem__(self, key:PersiDictKey) -> Any:
-        """X.__getitem__(y) is an equivalent to X[y]"""
+        """Retrieve the value for a key.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+
+        Returns:
+            Any: The stored value.
+        """
         raise NotImplementedError
 
 
     def __setitem__(self, key:PersiDictKey, value:Any):
-        """Set self[key] to value."""
+        """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 attempting to modify an existing key when
+                immutable_items is True.
+            NotImplementedError: Subclasses must implement actual writing.
+        """
         if value is KEEP_CURRENT:
             return
         elif value is DELETE_CURRENT:
@@ -169,71 +205,139 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def __delitem__(self, key:PersiDictKey):
-        """Delete self[key]."""
-        if self.immutable_items: # TODO: change to exceptions
+        """Delete a key and its value.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+
+        Raises:
+            KeyError: If immutable_items is True.
+            NotImplementedError: Subclasses must implement deletion.
+        """
+        if self.immutable_items:
             raise KeyError("Can't delete an immutable key-value pair")
         raise NotImplementedError
 
 
     @abstractmethod
     def __len__(self) -> int:
-        """Return len(self)."""
+        """Return the number of stored items.
+
+        Returns:
+            int: Number of key-value pairs.
+        """
         raise NotImplementedError
 
 
     @abstractmethod
     def _generic_iter(self, result_type: set[str]) -> Any:
-        """Underlying implementation for items/keys/values/... iterators"""
-        assert isinstance(result_type, set)
-        assert 1 <= len(result_type) <= 3
-        assert len(result_type | {"keys", "values", "timestamps"}) == 3
-        assert 1 <= len(result_type & {"keys", "values", "timestamps"}) <= 3
+        """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.
+        """
+        if not isinstance(result_type, set):
+            raise TypeError("result_type must be a set of strings")
+        if not (1 <= len(result_type) <= 3):
+            raise ValueError("result_type must contain between 1 and 3 elements")
+        allowed = {"keys", "values", "timestamps"}
+        if (result_type | allowed) != allowed:
+            raise ValueError("result_type can only contain 'keys', 'values', 'timestamps'")
+        if not (1 <= len(result_type & allowed) <= 3):
+            raise ValueError("result_type must include at least one of 'keys', 'values', 'timestamps'")
         raise NotImplementedError
 
 
     def __iter__(self):
-        """Implement iter(self)."""
+        """Iterate over keys.
+
+        Returns:
+            Iterator[SafeStrTuple]: Iterator of keys.
+        """
         return self._generic_iter({"keys"})
 
 
     def keys(self):
-        """iterator object that provides access to keys"""
+        """Return an iterator over keys.
+
+        Returns:
+            Iterator[SafeStrTuple]: Keys iterator.
+        """
         return  self._generic_iter({"keys"})
 
 
     def keys_and_timestamps(self):
-        """iterator object that provides access to keys and timestamps"""
+        """Return an iterator over (key, timestamp) pairs.
+
+        Returns:
+            Iterator[tuple[SafeStrTuple, float]]: Keys and POSIX timestamps.
+        """
         return self._generic_iter({"keys", "timestamps"})
 
 
     def values(self):
-        """D.values() -> iterator object that provides access to D's values"""
+        """Return an iterator over values.
+
+        Returns:
+            Iterator[Any]: Values iterator.
+        """
         return self._generic_iter({"values"})
 
 
     def values_and_timestamps(self):
-        """iterator object that provides access to values and timestamps"""
+        """Return an iterator over (value, timestamp) pairs.
+
+        Returns:
+            Iterator[tuple[Any, float]]: Values and POSIX timestamps.
+        """
         return self._generic_iter({"values", "timestamps"})
 
 
     def items(self):
-        """D.items() -> iterator object that provides access to D's items"""
+        """Return an iterator over (key, value) pairs.
+
+        Returns:
+            Iterator[tuple[SafeStrTuple, Any]]: Items iterator.
+        """
         return self._generic_iter({"keys", "values"})
 
 
     def items_and_timestamps(self):
-        """iterator object that provides access to keys, values, and timestamps"""
+        """Return an iterator over (key, value, timestamp) triples.
+
+        Returns:
+            Iterator[tuple[SafeStrTuple, Any, float]]: Items and timestamps.
+        """
         return self._generic_iter({"keys", "values", "timestamps"})
 
 
     def setdefault(self, key:PersiDictKey, default:Any=None) -> Any:
-        """Insert key with a value of default if key is not in the dictionary.
+        """Insert key with default if absent; return the value.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+            default: Value to insert if the key is not present.
+
+        Returns:
+            Any: Existing value if present; otherwise the provided default.
 
-        Return the value for key if key is in the dictionary, else default.
+        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)
-        assert not isinstance(default, Joker)
+        if isinstance(default, Joker):
+            raise TypeError("default must be a regular value, not a Joker command")
         if key in self:
             return self[key]
         else:
@@ -241,8 +345,18 @@ class PersiDict(MutableMapping, ParameterizableClass):
             return default
 
 
-    def __eq__(self, other) -> bool:
-        """Return self==other. """
+    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.
+
+        Args:
+            other: Another dictionary-like object.
+
+        Returns:
+            bool: True if considered equal, False otherwise.
+        """
         if isinstance(other, PersiDict):
             return self.get_portable_params() == other.get_portable_params()
         try:
@@ -257,16 +371,30 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def __getstate__(self):
+        """Prevent pickling of PersiDict instances.
+
+        Raises:
+            TypeError: Always raised; PersiDict instances are not pickleable.
+        """
         raise TypeError("PersiDict is not picklable.")
 
 
     def __setstate__(self, state):
+        """Prevent unpickling of PersiDict instances.
+
+        Raises:
+            TypeError: Always raised; PersiDict instances are not pickleable.
+        """
         raise TypeError("PersiDict is not picklable.")
 
 
     def clear(self) -> None:
-        """Remove all items from the dictionary. """
-        if self.immutable_items: # TODO: change to exceptions
+        """Remove all items from the dictionary.
+
+        Raises:
+            KeyError: If items are immutable (immutable_items is True).
+        """
+        if self.immutable_items:
             raise KeyError("Can't delete an immutable key-value pair")
 
         for k in self.keys():
@@ -277,14 +405,21 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def delete_if_exists(self, key:PersiDictKey) -> bool:
-        """ Delete an item without raising an exception if it doesn't exist.
-
-        Returns True if the item existed and was deleted, False otherwise.
+        """Delete an item without raising an exception if it doesn't exist.
 
         This method is absent in the original dict API.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+
+        Returns:
+            bool: True if the item existed and was deleted; False otherwise.
+
+        Raises:
+            KeyError: If items are immutable (immutable_items is True).
         """
 
-        if self.immutable_items: # TODO: change to exceptions
+        if self.immutable_items:
             raise KeyError("Can't delete an immutable key-value pair")
 
         key = SafeStrTuple(key)
@@ -300,19 +435,37 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def get_subdict(self, prefix_key:PersiDictKey) -> PersiDict:
-        """Get a sub-dictionary containing items with the same prefix key.
+        """Get a sub-dictionary containing items with the given prefix key.
 
-        For non-existing prefix key, an empty sub-dictionary is returned.
+        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.
 
         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.
+
+        Returns:
+            PersiDict: A dictionary-like view restricted to keys under the
+                provided prefix.
+
+        Raises:
+            NotImplementedError: Must be implemented by subclasses that support
+                hierarchical key spaces.
         """
         raise NotImplementedError
 
 
     def subdicts(self) -> dict[str, PersiDict]:
-        """Get a dictionary of sub-dictionaries.
+        """Return a mapping of first-level keys to sub-dictionaries.
 
         This method is absent in the original dict API.
+
+        Returns:
+            dict[str, PersiDict]: A mapping from a top-level key segment to a
+                sub-dictionary restricted to the corresponding keyspace.
         """
         all_keys = {k[0] for k in self.keys()}
         result_subdicts = {k: self.get_subdict(k) for k in all_keys}
@@ -322,13 +475,14 @@ class PersiDict(MutableMapping, ParameterizableClass):
     def random_key(self) -> PersiDictKey | None:
         """Return a random key from the dictionary.
 
-        Returns a single random key if the dictionary is not empty.
-        Returns None if the dictionary is empty.
-
         This method is absent in the original Python dict API.
 
         Implementation uses reservoir sampling to select a uniformly random key
         in streaming time, without loading all keys into memory or using len().
+
+        Returns:
+            SafeStrTuple | None: A random key if the dictionary is not empty;
+                None if the dictionary is empty.
         """
         iterator = iter(self.keys())
         try:
@@ -351,17 +505,33 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
     @abstractmethod
     def timestamp(self, key:PersiDictKey) -> float:
-        """Get last modification time (in seconds, Unix epoch time).
+        """Return the last modification time of a key.
 
         This method is absent in the original dict API.
+
+        Args:
+            key: Key (string or sequence of strings) or SafeStrTuple.
+
+        Returns:
+            float: POSIX timestamp (seconds since Unix epoch) of the last
+                modification of the item.
+
+        Raises:
+            NotImplementedError: Must be implemented by subclasses.
         """
         raise NotImplementedError
 
 
     def oldest_keys(self, max_n=None):
-        """Return max_n the oldest keys in the dictionary.
+        """Return up to max_n oldest keys in the dictionary.
 
-        If max_n is None, return all keys.
+        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.
+
+        Returns:
+            list[SafeStrTuple]: The oldest keys, oldest first.
 
         This method is absent in the original Python dict API.
         """
@@ -381,9 +551,15 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def oldest_values(self, max_n=None):
-        """Return max_n the oldest values in the dictionary.
+        """Return up to max_n oldest values in the dictionary.
+
+        Args:
+            max_n (int | None): Maximum number of values to return. If None,
+                return values for all keys sorted by age (oldest first). Values
+                <= 0 yield an empty list.
 
-        If max_n is None, return all values.
+        Returns:
+            list[Any]: Values corresponding to the oldest keys.
 
         This method is absent in the original Python dict API.
         """
@@ -391,9 +567,15 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def newest_keys(self, max_n=None):
-        """Return max_n the newest keys in the dictionary.
+        """Return up to max_n newest keys in the dictionary.
 
-        If max_n is None, return all keys.
+        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.
+
+        Returns:
+            list[SafeStrTuple]: The newest keys, newest first.
 
         This method is absent in the original Python dict API.
         """
@@ -413,9 +595,15 @@ class PersiDict(MutableMapping, ParameterizableClass):
 
 
     def newest_values(self, max_n=None):
-        """Return max_n the newest values in the dictionary.
+        """Return up to max_n newest values in the dictionary.
+
+        Args:
+            max_n (int | None): Maximum number of values to return. If None,
+                return values for all keys sorted by age (newest first). Values
+                <= 0 yield an empty list.
 
-        If max_n is None, return all values.
+        Returns:
+            list[Any]: Values corresponding to the newest keys.
 
         This method is absent in the original Python dict API.
         """