persidict 0.38.0__tar.gz → 0.104.0__tar.gz

{persidict-0.38.0 → persidict-0.104.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.38.0
+Version: 0.104.0
 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
@@ -18,11 +18,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: parameterizable
 Requires-Dist: lz4
 Requires-Dist: joblib
-Requires-Dist: numpy
-Requires-Dist: pandas
 Requires-Dist: jsonpickle
 Requires-Dist: deepdiff
+Requires-Dist: boto3
 Requires-Dist: boto3 ; extra == 'aws'
+Requires-Dist: numpy ; extra == 'dev'
+Requires-Dist: pandas ; extra == 'dev'
 Requires-Dist: boto3 ; extra == 'dev'
 Requires-Dist: moto ; extra == 'dev'
 Requires-Dist: pytest ; extra == 'dev'
@@ -44,7 +45,8 @@ storing each value as its own file or S3 object. Keys are limited to
 text strings or sequences of strings.
 
 In contrast to traditional persistent dictionaries (e.g., Python’s `shelve)`, 
-`persidict` is designed for distributed environments where multiple processes 
+`persidict` is [designed](https://github.com/pythagoras-dev/persidict/blob/master/design_principles.md) 
+for distributed environments where multiple processes 
 on different machines concurrently work with the same store.
 
 ## 2. Why Use It?
@@ -160,8 +162,8 @@ print(f"API Key: {cloud_config['api_key']}")
 You can also constrain values to a specific class.
 * **Order**: Insertion order is not preserved.
 * **Additional Methods**: `PersiDict` provides extra methods not in the standard 
-dict API, such as `timestamp()`, `random_key()`, `newest_keys()`, `subdicts()`
-, `delete_if_exists()`, `get_params()` and more.
+dict API, such as `timestamp()`, `etag()`, `random_key()`, `newest_keys()`
+, `subdicts()`, `discard()`, `get_params()` and more.
 * **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
 and `DELETE_CURRENT` to delete a value during an assignment.
 
@@ -172,13 +174,14 @@ and `DELETE_CURRENT` to delete a value during an assignment.
 * **`PersiDict`**: The abstract base class that defines the common interface 
 for all persistent dictionaries in the package. It's the foundation 
 upon which everything else is built.
-* **`PersiDictKey`**: A type hint that specifies what can be used
-as a key in any `PersiDict`. It can be a `SafeStrTuple`, a single string, 
+* **`NonEmptyPersiDictKey`**: A type hint that specifies what can be used
+as a key in any `PersiDict`. It can be a `NonEmptySafeStrTuple`, a single string, 
 or a sequence of strings. When a `PesiDict` method requires a key as an input,
-it will accept any of these types and convert them to a `SafeStrTuple` internally.
-* **`SafeStrTuple`**: The core data structure for keys. It's an immutable, 
-flat tuple of non-empty, URL/filename-safe strings, ensuring that 
-keys are consistent and safe for various storage backends. 
+it will accept any of these types and convert them to 
+a `NonEmptySafeStrTuple` internally.
+* **`NonEmptySafeStrTuple`**: The core data structure for keys. 
+It's an immutable, flat tuple of non-empty, URL/filename-safe strings, 
+ensuring that keys are consistent and safe for various storage backends. 
 When a `PersiDict` method returns a key, it will always be in this format.
 
 ### 5.2 Main Implementations
@@ -191,24 +194,25 @@ suitable for distributed environments.
 
 ### 5.3 Key Parameters
 
-* **`file_type`**: A key parameter for `FileDirDict` and `S3Dict` that 
-determines the serialization format for values. 
-Common options are `"pkl"` (pickle) and `"json"`. 
-Any other value is treated as plain text for string storage.
+* **`serialization_format`**: A key parameter for `FileDirDict` and `S3Dict` that 
+        determines the serialization format used to store values. 
+        Common options are `"pkl"` (pickle) and `"json"`. 
+        Any other value is treated as plain text for string storage.
 * **`base_class_for_values`**: An optional parameter for any `PersiDict` 
 that enforces type checking on all stored values, ensuring they are 
 instances of a specific class.
-* **`immutable_items`**: A boolean parameter that can make a `PersiDict` 
-"write-once," preventing any modification or deletion of existing items.
+* **`append_only`**: A boolean parameter that makes items inside a `PersiDict` immutable, 
+preventing them from modification or deletion.
 * **`digest_len`**: An integer that specifies the length of a hash suffix 
-added to key components to prevent collisions on case-insensitive file systems.
+added to key components in `FileDirDict` to prevent collisions 
+on case-insensitive file systems.
 * **`base_dir`**: A string specifying the directory path where a `FileDirDict`
 stores its files. For `S3Dict`, this directory is used to cache files locally.
 * **`bucket_name`**: A string specifying the name of the S3 bucket where
 an `S3Dict` stores its objects.
 * **`region`**: An optional string specifying the AWS region for the S3 bucket.
 
-### 5.4 Advanced Classes
+### 5.4 Advanced and Supporting Classes
 
 * **`WriteOnceDict`**: A wrapper that enforces write-once behavior 
 on any `PersiDict`, ignoring subsequent writes to the same key. 
@@ -216,7 +220,13 @@ It also allows for random consistency checks to ensure subsequent
 writes to the same key always match the original value.
 * **`OverlappingMultiDict`**: An advanced container that holds 
 multiple `PersiDict` instances sharing the same storage 
-but with different `file_type`s.
+but with different `serialization_format`s.
+* **`LocalDict`**: An in-memory `PersiDict` backed by 
+a RAM-only hierarchical store.
+* **`EmptyDict`**: A minimal implementation of `PersiDict` that behaves  
+like a null device in OS - accepts all writes but discards them, 
+returns nothing on reads. Always appears empty 
+regardless of operations performed on it.
 
 ### 5.5 Special "Joker" Values
 
@@ -241,7 +251,7 @@ from the dictionary when assigned to a key.
 | `newest_values(max_n=None)` | `list[Any]` | Returns a list of values corresponding to the newest keys. |
 | `get_subdict(prefix_key)` | `PersiDict` | Returns a new `PersiDict` instance that provides a view into a subset of keys sharing a common prefix. |
 | `subdicts()` | `dict[str, PersiDict]` | Returns a dictionary mapping all first-level key prefixes to their corresponding sub-dictionary views. |
-| `delete_if_exists(key)` | `bool` | Deletes a key-value pair if it exists and returns `True`; otherwise, returns `False`. |
+| `discard(key)` | `bool` | Deletes a key-value pair if it exists and returns `True`; otherwise, returns `False`. |
 | `get_params()` | `dict` | Returns a dictionary of the instance's configuration parameters, supporting the `parameterizable` API. |
 
 ## 7. Installation
@@ -278,14 +288,14 @@ pip install persidict[dev]
 * [jsonpickle](https://jsonpickle.github.io)
 * [joblib](https://joblib.readthedocs.io)
 * [lz4](https://python-lz4.readthedocs.io)
-* [pandas](https://pandas.pydata.org)
-* [numpy](https://numpy.org)
 * [deepdiff](https://zepworks.com/deepdiff)
 
 For AWS S3 support (`S3Dict`), you will also need:
 * [boto3](https://boto3.readthedocs.io)
 
 For development and testing, the following packages are used:
+* [pandas](https://pandas.pydata.org)
+* [numpy](https://numpy.org)
 * [pytest](https://pytest.org)
 * [moto](http://getmoto.org)
 

{persidict-0.38.0 → persidict-0.104.0}/README.md

@@ -10,7 +10,8 @@ storing each value as its own file or S3 object. Keys are limited to
 text strings or sequences of strings.
 
 In contrast to traditional persistent dictionaries (e.g., Python’s `shelve)`, 
-`persidict` is designed for distributed environments where multiple processes 
+`persidict` is [designed](https://github.com/pythagoras-dev/persidict/blob/master/design_principles.md) 
+for distributed environments where multiple processes 
 on different machines concurrently work with the same store.
 
 ## 2. Why Use It?
@@ -126,8 +127,8 @@ print(f"API Key: {cloud_config['api_key']}")
 You can also constrain values to a specific class.
 * **Order**: Insertion order is not preserved.
 * **Additional Methods**: `PersiDict` provides extra methods not in the standard 
-dict API, such as `timestamp()`, `random_key()`, `newest_keys()`, `subdicts()`
-, `delete_if_exists()`, `get_params()` and more.
+dict API, such as `timestamp()`, `etag()`, `random_key()`, `newest_keys()`
+, `subdicts()`, `discard()`, `get_params()` and more.
 * **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
 and `DELETE_CURRENT` to delete a value during an assignment.
 
@@ -138,13 +139,14 @@ and `DELETE_CURRENT` to delete a value during an assignment.
 * **`PersiDict`**: The abstract base class that defines the common interface 
 for all persistent dictionaries in the package. It's the foundation 
 upon which everything else is built.
-* **`PersiDictKey`**: A type hint that specifies what can be used
-as a key in any `PersiDict`. It can be a `SafeStrTuple`, a single string, 
+* **`NonEmptyPersiDictKey`**: A type hint that specifies what can be used
+as a key in any `PersiDict`. It can be a `NonEmptySafeStrTuple`, a single string, 
 or a sequence of strings. When a `PesiDict` method requires a key as an input,
-it will accept any of these types and convert them to a `SafeStrTuple` internally.
-* **`SafeStrTuple`**: The core data structure for keys. It's an immutable, 
-flat tuple of non-empty, URL/filename-safe strings, ensuring that 
-keys are consistent and safe for various storage backends. 
+it will accept any of these types and convert them to 
+a `NonEmptySafeStrTuple` internally.
+* **`NonEmptySafeStrTuple`**: The core data structure for keys. 
+It's an immutable, flat tuple of non-empty, URL/filename-safe strings, 
+ensuring that keys are consistent and safe for various storage backends. 
 When a `PersiDict` method returns a key, it will always be in this format.
 
 ### 5.2 Main Implementations
@@ -157,24 +159,25 @@ suitable for distributed environments.
 
 ### 5.3 Key Parameters
 
-* **`file_type`**: A key parameter for `FileDirDict` and `S3Dict` that 
-determines the serialization format for values. 
-Common options are `"pkl"` (pickle) and `"json"`. 
-Any other value is treated as plain text for string storage.
+* **`serialization_format`**: A key parameter for `FileDirDict` and `S3Dict` that 
+        determines the serialization format used to store values. 
+        Common options are `"pkl"` (pickle) and `"json"`. 
+        Any other value is treated as plain text for string storage.
 * **`base_class_for_values`**: An optional parameter for any `PersiDict` 
 that enforces type checking on all stored values, ensuring they are 
 instances of a specific class.
-* **`immutable_items`**: A boolean parameter that can make a `PersiDict` 
-"write-once," preventing any modification or deletion of existing items.
+* **`append_only`**: A boolean parameter that makes items inside a `PersiDict` immutable, 
+preventing them from modification or deletion.
 * **`digest_len`**: An integer that specifies the length of a hash suffix 
-added to key components to prevent collisions on case-insensitive file systems.
+added to key components in `FileDirDict` to prevent collisions 
+on case-insensitive file systems.
 * **`base_dir`**: A string specifying the directory path where a `FileDirDict`
 stores its files. For `S3Dict`, this directory is used to cache files locally.
 * **`bucket_name`**: A string specifying the name of the S3 bucket where
 an `S3Dict` stores its objects.
 * **`region`**: An optional string specifying the AWS region for the S3 bucket.
 
-### 5.4 Advanced Classes
+### 5.4 Advanced and Supporting Classes
 
 * **`WriteOnceDict`**: A wrapper that enforces write-once behavior 
 on any `PersiDict`, ignoring subsequent writes to the same key. 
@@ -182,7 +185,13 @@ It also allows for random consistency checks to ensure subsequent
 writes to the same key always match the original value.
 * **`OverlappingMultiDict`**: An advanced container that holds 
 multiple `PersiDict` instances sharing the same storage 
-but with different `file_type`s.
+but with different `serialization_format`s.
+* **`LocalDict`**: An in-memory `PersiDict` backed by 
+a RAM-only hierarchical store.
+* **`EmptyDict`**: A minimal implementation of `PersiDict` that behaves  
+like a null device in OS - accepts all writes but discards them, 
+returns nothing on reads. Always appears empty 
+regardless of operations performed on it.
 
 ### 5.5 Special "Joker" Values
 
@@ -207,7 +216,7 @@ from the dictionary when assigned to a key.
 | `newest_values(max_n=None)` | `list[Any]` | Returns a list of values corresponding to the newest keys. |
 | `get_subdict(prefix_key)` | `PersiDict` | Returns a new `PersiDict` instance that provides a view into a subset of keys sharing a common prefix. |
 | `subdicts()` | `dict[str, PersiDict]` | Returns a dictionary mapping all first-level key prefixes to their corresponding sub-dictionary views. |
-| `delete_if_exists(key)` | `bool` | Deletes a key-value pair if it exists and returns `True`; otherwise, returns `False`. |
+| `discard(key)` | `bool` | Deletes a key-value pair if it exists and returns `True`; otherwise, returns `False`. |
 | `get_params()` | `dict` | Returns a dictionary of the instance's configuration parameters, supporting the `parameterizable` API. |
 
 ## 7. Installation
@@ -244,14 +253,14 @@ pip install persidict[dev]
 * [jsonpickle](https://jsonpickle.github.io)
 * [joblib](https://joblib.readthedocs.io)
 * [lz4](https://python-lz4.readthedocs.io)
-* [pandas](https://pandas.pydata.org)
-* [numpy](https://numpy.org)
 * [deepdiff](https://zepworks.com/deepdiff)
 
 For AWS S3 support (`S3Dict`), you will also need:
 * [boto3](https://boto3.readthedocs.io)
 
 For development and testing, the following packages are used:
+* [pandas](https://pandas.pydata.org)
+* [numpy](https://numpy.org)
 * [pytest](https://pytest.org)
 * [moto](http://getmoto.org)
 

{persidict-0.38.0 → persidict-0.104.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "persidict"
-version = "0.38.0"
+version = "0.104.0"
 description = "Simple persistent key-value store for Python. Values are stored as files on a disk or as S3 objects on AWS cloud."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -28,10 +28,9 @@ dependencies = [
     "parameterizable",
     "lz4",
     "joblib",
-    "numpy",
-    "pandas",
     "jsonpickle",
-    "deepdiff"
+    "deepdiff",
+    "boto3"
 ]
 
 [project.urls]
@@ -39,6 +38,8 @@ Homepage = "https://github.com/pythagoras-dev/persidict"
 
 [project.optional-dependencies]
 dev = [
+    "numpy",
+    "pandas",
     "boto3",
     "moto",
     "pytest"

persidict-0.104.0/src/persidict/__init__.py

@@ -0,0 +1,50 @@
+"""Persistent dictionaries that store key-value pairs on local disks or AWS S3.
+
+This package provides a unified interface for persistent dictionary-like
+storage with various backends including filesystem and AWS S3.
+
+Classes:
+    PersiDict: Abstract base class defining the unified interface for all
+        persistent dictionaries.
+    NonEmptySafeStrTuple: A flat tuple of URL/filename-safe strings that
+        can be used as a key for PersiDict objects.
+    FileDirDict: A dictionary that stores key-value pairs as files on a
+        local hard drive. Keys compose filenames, values are stored as
+        pickle or JSON objects.
+    S3Dict_Legacy: A dictionary that stores key-value pairs as S3 objects on AWS.
+        Keys compose object names, values are stored as pickle or JSON S3 objects.
+    BasicS3Dict: A basic S3-backed dictionary with direct S3 operations.
+    WriteOnceDict: A write-once wrapper that prevents modification of existing
+        items after initial storage.
+    EmptyDict: Equivalent of null device in OS - accepts all writes but discards
+        them, returns nothing on reads. Always appears empty regardless of
+        operations performed. Useful for testing, debugging, or as a placeholder.
+    OverlappingMultiDict: A dictionary that can handle overlapping key spaces.
+
+Functions:
+    get_safe_chars(): Returns a set of URL/filename-safe characters permitted
+        in keys.
+    replace_unsafe_chars(): Replaces forbidden characters in a string with
+        safe alternatives.
+
+Constants:
+    KEEP_CURRENT, DELETE_CURRENT: Special joker values for conditional operations.
+
+Note:
+    All persistent dictionaries support multiple serialization formats, including
+    pickle and JSON, with automatic type handling and collision-safe key encoding.
+"""
+from .safe_chars import *
+from .safe_str_tuple import *
+from .persi_dict import PersiDict, PersiDictKey
+from .file_dir_dict import FileDirDict
+from .s3_dict_file_dir_cached import S3Dict_FileDirCached, S3Dict
+from .basic_s3_dict import BasicS3Dict
+from .write_once_dict import WriteOnceDict
+from .empty_dict import EmptyDict
+from .singletons import Joker, KeepCurrentFlag, DeleteCurrentFlag
+from .singletons import KEEP_CURRENT, DELETE_CURRENT
+from .overlapping_multi_dict import OverlappingMultiDict
+from .cached_appendonly_dict import AppendOnlyDictCached
+from .cached_mutable_dict import MutableDictCached
+from .local_dict import LocalDict