persidict 0.36.3__py3-none-any.whl → 0.36.4__py3-none-any.whl

{persidict-0.36.3.dist-info → persidict-0.36.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: persidict
-Version: 0.36.3
+Version: 0.36.4
 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 
@@ -206,7 +205,24 @@ dict API, such as `timestamp()`, `random_key()`, `newest_keys()`, `subdicts()`
 * **Special Values**: Use `KEEP_CURRENT` to avoid updating a value 
 and `DELETE_CURRENT` to delete a value during an assignment.
 
-## 6. Installation
+## 6. API Highlights
+
+`PersiDict` subclasses support the standard Python dictionary API, plus these additional methods for advanced functionality:
+
+| 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. |
+
+## 7. Installation
 
 The source code is hosted on GitHub at:
 [https://github.com/pythagoras-dev/persidict](https://github.com/pythagoras-dev/persidict) 
@@ -232,7 +248,7 @@ For development, including test dependencies:
 pip install persidict[dev]
 ```
 
-## 7. Dependencies
+## 8. Dependencies
 
 `persidict` has the following core dependencies:
 
@@ -251,13 +267,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.dist-info → persidict-0.36.4.dist-info}/RECORD

@@ -9,6 +9,6 @@ persidict/safe_chars.py,sha256=9Qy24fu2dmiJOdmCF8mKZULfQaRp7H4oxfgDXeLgogI,1160
 persidict/safe_str_tuple.py,sha256=YBTcYjUKIffznOawXb9xKjz4HaKdklrgyVtegJFmr5w,7202
 persidict/safe_str_tuple_signing.py,sha256=RQAj4fnpRVaOe0KpwLler1UTaeNOgXCQpU3t80ixtxg,7493
 persidict/write_once_dict.py,sha256=-lPQ_yuU62pczHT0BYO6SFbiZBKFq8Tj9ln3jCzNDzA,11443
-persidict-0.36.3.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
-persidict-0.36.3.dist-info/METADATA,sha256=ZbokDXpJCfLHSKJZdSkJf96h6Q30IUl8DHWEr19zoNU,10023
-persidict-0.36.3.dist-info/RECORD,,
+persidict-0.36.4.dist-info/WHEEL,sha256=Pi5uDq5Fdo_Rr-HD5h9BiPn9Et29Y9Sh8NhcJNnFU1c,79
+persidict-0.36.4.dist-info/METADATA,sha256=TiSOXzkrZlAggOFeug0QIdBYl66obEUJwIU-ukwRS_E,11437
+persidict-0.36.4.dist-info/RECORD,,