persidict 0.36.3__tar.gz → 0.36.5__tar.gz

{persidict-0.36.3 → persidict-0.36.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.36.3
+Version: 0.36.5
 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
@@ -38,15 +38,14 @@ Simple persistent dictionaries for distributed applications in Python.
 
 ## 1. What Is It?
 
-`persidict` offers a simple persistent key-value store for Python. 
-It saves the content of the dictionary in a folder on a disk 
-or in an S3 bucket on AWS. Each value is stored as a separate file / S3 object.
-Only text strings or sequences of strings are allowed as keys.
+`persidict` is a lightweight persistent key-value store for Python. 
+It saves a dictionary to either a local directory or an AWS S3 bucket, 
+storing each value as its own file or S3 object. Keys are limited to 
+text strings or sequences of strings.
 
-Unlike other persistent dictionaries (e.g. Python's native `shelve`), 
-`persidict` is designed for use in highly **distributed environments**, 
-where multiple instances of a program run concurrently across many machines,
-accessing the same dictionary via a shared storage.
+In contrast to traditional persistent dictionaries (e.g., Python’s `shelve)`, 
+`persidict` is designed for distributed environments where multiple processes 
+on different machines concurrently work with the same store.
 
 ## 2. Features
 * **Persistent Storage**: Save dictionaries to the local filesystem 
@@ -120,21 +119,49 @@ print(f"API Key: {cloud_config['api_key']}")
 # >>> API Key: ABC-123-XYZ
 ```
 
-## 4. Glossary
+## 4. Comparison With Python Built-in Dictionaries
 
-### 4.1 Core Concepts
+### 4.1 Similarities 
+
+`PersiDict` subclasses can be used like regular Python dictionaries, supporting: 
+
+* Get, set, and delete operations with square brackets (`[]`).
+* Iteration over keys, values, and items.
+* Membership testing with `in`.
+* Length checking with `len()`.
+* Standard methods like `keys()`, `values()`, `items()`, `get()`, `clear()`
+, `setdefault()`, and `update()`.
+
+### 4.2 Differences 
+
+* **Persistence**: Data is saved between program executions.
+* **Keys**: Keys must be strings or sequences of URL/filename-safe strings.
+* **Values**: Values must be pickleable. 
+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.
+* **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
+and `DELETE_CURRENT` to delete a value during an assignment.
+
+## 5. Glossary
+
+### 5.1 Core Concepts
 
 * **`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, or a sequence of strings.
+as a key in any `PersiDict`. It can be a `SafeStrTuple`, 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.
+keys are consistent and safe for various storage backends. 
+When a `PersiDict` method returns a key, it will always be in this format.
 
-### 4.2 Main Implementations
+### 5.2 Main Implementations
 
 * **`FileDirDict`**: A primary, concrete implementation of `PersiDict` 
 that stores each key-value pair as a separate file in a local directory.
@@ -142,7 +169,7 @@ that stores each key-value pair as a separate file in a local directory.
 which stores each key-value pair as an object in an AWS S3 bucket, 
 suitable for distributed environments.
 
-### 4.3 Key Parameters
+### 5.3 Key Parameters
 
 * **`file_type`**: A key parameter for `FileDirDict` and `S3Dict` that 
 determines the serialization format for values. 
@@ -161,7 +188,7 @@ stores its files. For `S3Dict`, this directory is used to cache files locally.
 an `S3Dict` stores its objects.
 * **`region`**: An optional string specifying the AWS region for the S3 bucket.
 
-### 4.4 Advanced Classes
+### 5.4 Advanced Classes
 
 * **`WriteOnceDict`**: A wrapper that enforces write-once behavior 
 on any `PersiDict`, ignoring subsequent writes to the same key. 
@@ -171,7 +198,7 @@ writes to the same key always match the original value.
 multiple `PersiDict` instances sharing the same storage 
 but with different `file_type`s.
 
-### 4.5 Special "Joker" Values
+### 5.5 Special "Joker" Values
 
 * **`Joker`**: The base class for special command-like values that 
 can be assigned to a key to trigger an action instead of storing a value.
@@ -180,33 +207,24 @@ ensures the existing value is not changed.
 * **`DELETE_CURRENT`**: A "joker" value that deletes the key-value pair 
 from the dictionary when assigned to a key.
 
-## 5. Comparison With Python Built-in Dictionaries
-
-### 5.1 Similarities 
-
-`PersiDict` subclasses can be used like regular Python dictionaries, supporting: 
-
-* Get, set, and delete operations with square brackets (`[]`).
-* Iteration over keys, values, and items.
-* Membership testing with `in`.
-* Length checking with `len()`.
-* Standard methods like `keys()`, `values()`, `items()`, `get()`, `clear()`
-, `setdefault()`, and `update()`.
+## 6. API Highlights
 
-### 5.2 Differences 
+`PersiDict` subclasses support the standard Python dictionary API, plus these additional methods for advanced functionality:
 
-* **Persistence**: Data is saved between program executions.
-* **Keys**: Keys must be strings or sequences of URL/filename-safe strings.
-* **Values**: Values must be pickleable. 
-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.
-* **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
-and `DELETE_CURRENT` to delete a value during an assignment.
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `timestamp(key)` | `float` | Returns the POSIX timestamp (seconds since epoch) of a key's last modification. |
+| `random_key()` | `SafeStrTuple \| None` | Selects and returns a single random key, useful for sampling from the dataset. |
+| `oldest_keys(max_n=None)` | `list[SafeStrTuple]` | Returns a list of keys sorted by their modification time, from oldest to newest. |
+| `newest_keys(max_n=None)` | `list[SafeStrTuple]` | Returns a list of keys sorted by their modification time, from newest to oldest. |
+| `oldest_values(max_n=None)` | `list[Any]` | Returns a list of values corresponding to the oldest keys. |
+| `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`. |
+| `get_params()` | `dict` | Returns a dictionary of the instance's configuration parameters, supporting the `parameterizable` API. |
 
-## 6. Installation
+## 7. Installation
 
 The source code is hosted on GitHub at:
 [https://github.com/pythagoras-dev/persidict](https://github.com/pythagoras-dev/persidict) 
@@ -232,7 +250,7 @@ For development, including test dependencies:
 pip install persidict[dev]
 ```
 
-## 7. Dependencies
+## 8. Dependencies
 
 `persidict` has the following core dependencies:
 
@@ -251,13 +269,13 @@ For development and testing, the following packages are used:
 * [pytest](https://pytest.org)
 * [moto](http://getmoto.org)
 
-## 8. Contributing
+## 9. Contributing
 Contributions are welcome! Please see the contributing [guide](https://github.com/pythagoras-dev/persidict?tab=contributing-ov-file) for more details 
 on how to get started, run tests, and submit pull requests.
 
-## 9. License
+## 10. License
 `persidict` is licensed under the MIT License. See the [LICENSE](https://github.com/pythagoras-dev/persidict?tab=MIT-1-ov-file) file for more details.
 
-## 10. Key Contacts
+## 11. Key Contacts
 
 * [Vlad (Volodymyr) Pavlov](https://www.linkedin.com/in/vlpavlov/)

{persidict-0.36.3 → persidict-0.36.5}/README.md

@@ -4,15 +4,14 @@ Simple persistent dictionaries for distributed applications in Python.
 
 ## 1. What Is It?
 
-`persidict` offers a simple persistent key-value store for Python. 
-It saves the content of the dictionary in a folder on a disk 
-or in an S3 bucket on AWS. Each value is stored as a separate file / S3 object.
-Only text strings or sequences of strings are allowed as keys.
+`persidict` is a lightweight persistent key-value store for Python. 
+It saves a dictionary to either a local directory or an AWS S3 bucket, 
+storing each value as its own file or S3 object. Keys are limited to 
+text strings or sequences of strings.
 
-Unlike other persistent dictionaries (e.g. Python's native `shelve`), 
-`persidict` is designed for use in highly **distributed environments**, 
-where multiple instances of a program run concurrently across many machines,
-accessing the same dictionary via a shared storage.
+In contrast to traditional persistent dictionaries (e.g., Python’s `shelve)`, 
+`persidict` is designed for distributed environments where multiple processes 
+on different machines concurrently work with the same store.
 
 ## 2. Features
 * **Persistent Storage**: Save dictionaries to the local filesystem 
@@ -86,21 +85,49 @@ print(f"API Key: {cloud_config['api_key']}")
 # >>> API Key: ABC-123-XYZ
 ```
 
-## 4. Glossary
+## 4. Comparison With Python Built-in Dictionaries
 
-### 4.1 Core Concepts
+### 4.1 Similarities 
+
+`PersiDict` subclasses can be used like regular Python dictionaries, supporting: 
+
+* Get, set, and delete operations with square brackets (`[]`).
+* Iteration over keys, values, and items.
+* Membership testing with `in`.
+* Length checking with `len()`.
+* Standard methods like `keys()`, `values()`, `items()`, `get()`, `clear()`
+, `setdefault()`, and `update()`.
+
+### 4.2 Differences 
+
+* **Persistence**: Data is saved between program executions.
+* **Keys**: Keys must be strings or sequences of URL/filename-safe strings.
+* **Values**: Values must be pickleable. 
+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.
+* **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
+and `DELETE_CURRENT` to delete a value during an assignment.
+
+## 5. Glossary
+
+### 5.1 Core Concepts
 
 * **`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, or a sequence of strings.
+as a key in any `PersiDict`. It can be a `SafeStrTuple`, 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.
+keys are consistent and safe for various storage backends. 
+When a `PersiDict` method returns a key, it will always be in this format.
 
-### 4.2 Main Implementations
+### 5.2 Main Implementations
 
 * **`FileDirDict`**: A primary, concrete implementation of `PersiDict` 
 that stores each key-value pair as a separate file in a local directory.
@@ -108,7 +135,7 @@ that stores each key-value pair as a separate file in a local directory.
 which stores each key-value pair as an object in an AWS S3 bucket, 
 suitable for distributed environments.
 
-### 4.3 Key Parameters
+### 5.3 Key Parameters
 
 * **`file_type`**: A key parameter for `FileDirDict` and `S3Dict` that 
 determines the serialization format for values. 
@@ -127,7 +154,7 @@ stores its files. For `S3Dict`, this directory is used to cache files locally.
 an `S3Dict` stores its objects.
 * **`region`**: An optional string specifying the AWS region for the S3 bucket.
 
-### 4.4 Advanced Classes
+### 5.4 Advanced Classes
 
 * **`WriteOnceDict`**: A wrapper that enforces write-once behavior 
 on any `PersiDict`, ignoring subsequent writes to the same key. 
@@ -137,7 +164,7 @@ writes to the same key always match the original value.
 multiple `PersiDict` instances sharing the same storage 
 but with different `file_type`s.
 
-### 4.5 Special "Joker" Values
+### 5.5 Special "Joker" Values
 
 * **`Joker`**: The base class for special command-like values that 
 can be assigned to a key to trigger an action instead of storing a value.
@@ -146,33 +173,24 @@ ensures the existing value is not changed.
 * **`DELETE_CURRENT`**: A "joker" value that deletes the key-value pair 
 from the dictionary when assigned to a key.
 
-## 5. Comparison With Python Built-in Dictionaries
-
-### 5.1 Similarities 
-
-`PersiDict` subclasses can be used like regular Python dictionaries, supporting: 
-
-* Get, set, and delete operations with square brackets (`[]`).
-* Iteration over keys, values, and items.
-* Membership testing with `in`.
-* Length checking with `len()`.
-* Standard methods like `keys()`, `values()`, `items()`, `get()`, `clear()`
-, `setdefault()`, and `update()`.
+## 6. API Highlights
 
-### 5.2 Differences 
+`PersiDict` subclasses support the standard Python dictionary API, plus these additional methods for advanced functionality:
 
-* **Persistence**: Data is saved between program executions.
-* **Keys**: Keys must be strings or sequences of URL/filename-safe strings.
-* **Values**: Values must be pickleable. 
-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.
-* **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
-and `DELETE_CURRENT` to delete a value during an assignment.
+| Method | Return Type | Description |
+| :--- | :--- | :--- |
+| `timestamp(key)` | `float` | Returns the POSIX timestamp (seconds since epoch) of a key's last modification. |
+| `random_key()` | `SafeStrTuple \| None` | Selects and returns a single random key, useful for sampling from the dataset. |
+| `oldest_keys(max_n=None)` | `list[SafeStrTuple]` | Returns a list of keys sorted by their modification time, from oldest to newest. |
+| `newest_keys(max_n=None)` | `list[SafeStrTuple]` | Returns a list of keys sorted by their modification time, from newest to oldest. |
+| `oldest_values(max_n=None)` | `list[Any]` | Returns a list of values corresponding to the oldest keys. |
+| `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`. |
+| `get_params()` | `dict` | Returns a dictionary of the instance's configuration parameters, supporting the `parameterizable` API. |
 
-## 6. Installation
+## 7. Installation
 
 The source code is hosted on GitHub at:
 [https://github.com/pythagoras-dev/persidict](https://github.com/pythagoras-dev/persidict) 
@@ -198,7 +216,7 @@ For development, including test dependencies:
 pip install persidict[dev]
 ```
 
-## 7. Dependencies
+## 8. Dependencies
 
 `persidict` has the following core dependencies:
 
@@ -217,13 +235,13 @@ For development and testing, the following packages are used:
 * [pytest](https://pytest.org)
 * [moto](http://getmoto.org)
 
-## 8. Contributing
+## 9. Contributing
 Contributions are welcome! Please see the contributing [guide](https://github.com/pythagoras-dev/persidict?tab=contributing-ov-file) for more details 
 on how to get started, run tests, and submit pull requests.
 
-## 9. License
+## 10. License
 `persidict` is licensed under the MIT License. See the [LICENSE](https://github.com/pythagoras-dev/persidict?tab=MIT-1-ov-file) file for more details.
 
-## 10. Key Contacts
+## 11. Key Contacts
 
 * [Vlad (Volodymyr) Pavlov](https://www.linkedin.com/in/vlpavlov/)

{persidict-0.36.3 → persidict-0.36.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "persidict"
-version = "0.36.3"
+version = "0.36.5"
 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"