redis-dict 2.5.1__tar.gz → 2.7.0__tar.gz

redis dict-2.5.1/README.md → redis dict-2.7.0/PKG-INFO

@@ -1,36 +1,76 @@
+Metadata-Version: 2.1
+Name: redis dict
+Version: 2.7.0
+Summary: Dictionary with Redis as storage backend
+Home-page: https://github.com/Attumm/redisdict
+Author: Melvin Bijman
+Author-email: bijman.m.m@gmail.com
+License: MIT
+Keywords: redis python dictionary dict key-value key:value database caching distributed-computing dictionary-interface large-datasets scientific-computing data-persistence high-performance scalable pipelining batching big-data data-types distributed-algorithms encryption data-management
+Platform: any
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Internet
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Object Brokering
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: redis
+
 # Redis-dict
 [![CI](https://github.com/Attumm/redis-dict/actions/workflows/ci.yml/badge.svg)](https://github.com/Attumm/redis-dict/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/Attumm/redis-dict/graph/badge.svg?token=Lqs7McQGEs)](https://codecov.io/gh/Attumm/redis-dict)
 [![Downloads](https://static.pepy.tech/badge/redis-dict/month)](https://pepy.tech/project/redis-dict)
 
-RedisDict is a Python library that provides a convenient and familiar interface for interacting with Redis as if it were a Python dictionary. This simple yet powerful library enables you to manage key-value pairs in Redis using native Python syntax. It supports various data types, including strings, integers, floats, booleans, lists, and dictionaries, and includes additional utility functions for more complex use cases.
-
-By leveraging Redis for efficient key-value storage, RedisDict allows for high-performance data management and is particularly useful for handling large datasets that may exceed local memory capacity.
+RedisDict is a Python library that offers a convenient and familiar interface for interacting with Redis, treating it as if it were a Python dictionary. Its goal is to help developers write clean, Pythonic code while using Redis as a storage solution for seamless distributed computing. This simple yet powerful library utilizes Redis as a key-value store and supports various data types, including strings, integers, floats, booleans, lists, and dictionaries. Additionally, developers can extend RedisDict to work with custom objects.
 
+The library includes utility functions for more complex use cases such as caching, batching, and more. By leveraging Redis for efficient key-value storage, RedisDict enables high-performance data management, maintaining efficiency even with large datasets and Redis instances.
 
 ## Features
 
 * Dictionary-like interface: Use familiar Python dictionary syntax to interact with Redis.
-* Data Type Support: Comprehensive support for various data types, including strings, integers, floats, booleans, lists, dictionaries, sets, and tuples.
+* Data Type Support: Comprehensive support for various data types.
 * Pipelining support: Use pipelines for batch operations to improve performance.
 * Expiration Support: Enables the setting of expiration times either globally or individually per key, through the use of context managers.
 * Efficiency and Scalability: RedisDict is designed for use with large datasets and is optimized for efficiency. It retrieves only the data needed for a particular operation, ensuring efficient memory usage and fast performance.
 * Namespace Management: Provides simple and efficient namespace handling to help organize and manage data in Redis, streamlining data access and manipulation.
 * Distributed Computing: With its ability to seamlessly connect to other instances or servers with access to the same Redis instance, RedisDict enables easy distributed computing.
-* Custom data types: Add custom types and transformations to suit your specific needs.
+* Custom data: types: Add custom types encoding/decoding to store your data types.
+* Encryption: allows for storing data encrypted, while retaining the simple dictionary interface.
 
 ## Example
 Redis is an exceptionally fast database when used appropriately. RedisDict leverages Redis for efficient key-value storage, enabling high-performance data management.
 
-```python
-from redis_dict import RedisDict
+```bash
+pip install redis-dict
+```
 
-dic = RedisDict()
-dic['foo'] = 42
-print(dic['foo'])  # Output: 42
-print('foo' in dic)  # Output: True
-dic["baz"] = "hello world"
-print(dic)  # Output: {'foo': 42, 'baz': 'hello world'}
+```python
+>>> from redis_dict import RedisDict
+>>> dic = RedisDict()
+>>> dic['foo'] = 42
+>>> dic['foo']
+42
+>>> 'foo' in dic
+True
+>>> dic["baz"] = "hello world"
+>>> dic
+{'foo': 42, 'baz': 'hello world'}
 ```
 In Redis our example looks like this.
 ```
@@ -43,12 +83,12 @@ In Redis our example looks like this.
 "str:hello world"
 ```
 
+
 ### Namespaces
-Acting as an identifier for your dictionary across different systems, RedisDict employs namespaces for organized data management. When a namespace isn't specified, "main" becomes the default. Thus allowing for data organization accross systems and projects with the same redis instance.
+Acting as an identifier for your dictionary across different systems, RedisDict employs namespaces for organized data management. When a namespace isn't specified, "main" becomes the default. Thus allowing for data organization across systems and projects with the same redis instance.
 
 This approach also minimizes the risk of key collisions between different applications, preventing hard-to-debug issues. By leveraging namespaces, RedisDict ensures a cleaner and more maintainable data management experience for developers working on multiple projects.
 
-
 ## Advanced Features
 
 ### Expiration
@@ -81,6 +121,8 @@ with dic.expire_at(seconds):
 3. Updating keys while preserving the initial timeout In certain situations, there is a need to update the value while keeping the expiration intact. This is achievable by setting the 'preserve_expiration' to true.
 
 ```python
+import time
+
 dic = RedisDict(expire=10, preserve_expiration=True)
 dic['gone'] = 'in ten seconds'
 
@@ -93,6 +135,7 @@ dic['gone'] = 'gone in 5 seconds'
 Efficiently batch your requests using the Pipeline feature, which can be easily utilized with a context manager.
 
 ```python
+from redis_dict import RedisDict
 dic = RedisDict(namespace="example")
 
 # one round trip to redis
@@ -122,13 +165,14 @@ print(dic["foo"]) # outputs "bar"
 ### Caching made simple
 ```python
 import time
+from datetime import timedelta
 from redis_dict import RedisDict
 
 def expensive_function(x):
-    time.sleep(2)
+    time.sleep(x)
     return x * 2
 
-cache = RedisDict(namespace="cache", expire=10)
+cache = RedisDict(namespace="cache", expire=timedelta(minutes=60))
 
 def cached_expensive_function(x):
     if x not in cache:
@@ -136,7 +180,7 @@ def cached_expensive_function(x):
     return cache[x]
 
 start_time = time.time()
-print(cached_expensive_function(5))  # Takes around 2 seconds to compute and caches the result.
+print(cached_expensive_function(5))  # Takes around 5 seconds to compute and caches the result.
 print(f"Time taken: {time.time() - start_time:.2f} seconds")
 
 start_time = time.time()
@@ -156,7 +200,7 @@ dic["name"] = "John Doe"
 dic["age"] = 32
 dic["city"] = "Amsterdam"
 
-# Get value by key
+# Get value by key, from any instance connected to the same redis/namespace
 print(dic["name"])  # Output: John Doe
 
 # Update value by key, got a year older
@@ -209,10 +253,105 @@ print(dic["d"])  # Output: 4
 For more advanced examples of RedisDict, please refer to the unit-test files in the repository. All features and functionalities are thoroughly tested in [unit tests (here)](https://github.com/Attumm/redis-dict/blob/main/tests.py#L1) Or take a look at load test for batching [load test](https://github.com/Attumm/redis-dict/blob/main/load_test.py#L1).
 The unit-tests can be as used as a starting point.
 
+## Types
+
+### standard types
+RedisDict supports a range of Python data types, from basic types to nested structures.
+Basic types are handled natively, while complex data types like lists and dictionaries, RedisDict uses JSON serialization, specifically avoiding `pickle` due to its [security vulnerabilities](https://docs.python.org/3/library/pickle.html) in distributed computing contexts.
+Although the library supports nested structures, the recommended best practice is to use RedisDict as a shallow dictionary.
+This approach optimizes Redis database performance and efficiency by ensuring that each set and get operation efficiently maps to Redis's key-value storage capabilities, while still preserving the library's Pythonic interface.
+Following types are supported: 
+`str, int, float, bool, NoneType, list, dict, tuple, set, datetime, date, time, timedelta, Decimal, complex, bytes, UUID, OrderedDict, defaultdict, frozenset`
+```python
+from redis_dict import RedisDict
+
+from uuid import UUID
+from decimal import Decimal
+from collections import OrderedDict, defaultdict
+from datetime import datetime, date, time, timedelta
+
+
+dic = RedisDict()
+
+dic["string"] = "Hello World"
+dic["number"] = 42
+dic["float"] = 3.14
+dic["bool"] = True
+dic["None"] = None
+
+dic["list"] = [1, 2, 3]
+dic["dict"] = {"a": 1, "b": 2}
+dic["tuple"] = (1, 2, 3)
+dic["set"] = {1, 2, 3}
+
+dic["datetime"] = datetime.date(2024, 1, 1, 12, 30, 45)
+dic["date"] = date(2024, 1, 1)
+dic["time"] = time(12, 30, 45)
+dic["delta"] = timedelta(days=1, hours=2)
+
+dic["decimal"] = Decimal("3.14159")
+dic["complex"] = complex(1, 2)
+dic["bytes"] = bytes([72, 101, 108, 108, 111])
+dic["uuid"] = UUID('12345678-1234-5678-1234-567812345678')
+
+dic["ordered"] = OrderedDict([('a', 1), ('b', 2)])
+dic["default"] = defaultdict(int, {'a': 1, 'b': 2})
+dic["frozen"] = frozenset([1, 2, 3])
+```
+
+### Extending RedisDict with Custom Types
+
+RedisDict supports custom type serialization. Here's how to add a new type:
+
+
+```python
+import json
+from redis_dict import RedisDict
+
+class Person:
+    def __init__(self, name, age):
+        self.name = name
+        self.age = age
+
+    def encode(self) -> str:
+        return json.dumps(self.__dict__)
+
+    @classmethod
+    def decode(cls, encoded_str: str) -> 'Person':
+        return cls(**json.loads(encoded_str))
+
+redis_dict = RedisDict()
+
+# Extend redis dict with the new type
+redis_dict.extends_type(Person)
+
+# RedisDict can now seamlessly handle Person instances.
+person = Person(name="John", age=32)
+redis_dict["person1"] = person
+
+result = redis_dict["person1"]
+
+assert result.name == person.name
+assert result.age == person.age
+```
+
+```python
+>>> from datetime import datetime
+>>> redis_dict.extends_type(datetime, datetime.isoformat, datetime.fromisoformat)
+>>> redis_dict["now"] = datetime.now()
+>>> redis_dict
+{'now': datetime.datetime(2024, 10, 14, 18, 41, 53, 493775)}
+>>> redis_dict["now"]
+datetime.datetime(2024, 10, 14, 18, 41, 53, 493775)
+```
+
+For more information on [extending types](https://github.com/Attumm/redis-dict/blob/main/extend_types_tests.py).
 ### Redis Encryption
-Setup guide for configuring and utilizing encrypted Redis for redis-dict.
+Setup guide for configuring and utilizing encrypted Redis TLS for redis-dict.
 [Setup guide](https://github.com/Attumm/redis-dict/blob/main/encrypted_redis.MD)
 
+### Redis Storage Encryption
+For storing encrypted data values, it's possible to use extended types. Take a look at this [encrypted test](https://github.com/Attumm/redis-dict/blob/main/encrypt_tests.py).
 
 ### Tests
 The RedisDict library includes a comprehensive suite of tests that ensure its correctness and resilience. The test suite covers various data types, edge cases, and error handling scenarios. It also employs the Hypothesis library for property-based testing, which provides fuzz testing to evaluate the implementation

redis dict-2.5.1/PKG-INFO → redis dict-2.7.0/README.md

@@ -1,61 +1,42 @@
-Metadata-Version: 2.1
-Name: redis dict
-Version: 2.5.1
-Summary: Dictionary with Redis as storage backend
-Home-page: https://github.com/Attumm/redisdict
-Author: Melvin Bijman
-Author-email: bijman.m.m@gmail.com
-License: MIT
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Database
-Classifier: Topic :: System :: Distributed Computing
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: redis
-
 # Redis-dict
 [![CI](https://github.com/Attumm/redis-dict/actions/workflows/ci.yml/badge.svg)](https://github.com/Attumm/redis-dict/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/Attumm/redis-dict/graph/badge.svg?token=Lqs7McQGEs)](https://codecov.io/gh/Attumm/redis-dict)
 [![Downloads](https://static.pepy.tech/badge/redis-dict/month)](https://pepy.tech/project/redis-dict)
 
-RedisDict is a Python library that provides a convenient and familiar interface for interacting with Redis as if it were a Python dictionary. This simple yet powerful library enables you to manage key-value pairs in Redis using native Python syntax. It supports various data types, including strings, integers, floats, booleans, lists, and dictionaries, and includes additional utility functions for more complex use cases.
-
-By leveraging Redis for efficient key-value storage, RedisDict allows for high-performance data management and is particularly useful for handling large datasets that may exceed local memory capacity.
+RedisDict is a Python library that offers a convenient and familiar interface for interacting with Redis, treating it as if it were a Python dictionary. Its goal is to help developers write clean, Pythonic code while using Redis as a storage solution for seamless distributed computing. This simple yet powerful library utilizes Redis as a key-value store and supports various data types, including strings, integers, floats, booleans, lists, and dictionaries. Additionally, developers can extend RedisDict to work with custom objects.
 
+The library includes utility functions for more complex use cases such as caching, batching, and more. By leveraging Redis for efficient key-value storage, RedisDict enables high-performance data management, maintaining efficiency even with large datasets and Redis instances.
 
 ## Features
 
 * Dictionary-like interface: Use familiar Python dictionary syntax to interact with Redis.
-* Data Type Support: Comprehensive support for various data types, including strings, integers, floats, booleans, lists, dictionaries, sets, and tuples.
+* Data Type Support: Comprehensive support for various data types.
 * Pipelining support: Use pipelines for batch operations to improve performance.
 * Expiration Support: Enables the setting of expiration times either globally or individually per key, through the use of context managers.
 * Efficiency and Scalability: RedisDict is designed for use with large datasets and is optimized for efficiency. It retrieves only the data needed for a particular operation, ensuring efficient memory usage and fast performance.
 * Namespace Management: Provides simple and efficient namespace handling to help organize and manage data in Redis, streamlining data access and manipulation.
 * Distributed Computing: With its ability to seamlessly connect to other instances or servers with access to the same Redis instance, RedisDict enables easy distributed computing.
-* Custom data types: Add custom types and transformations to suit your specific needs.
+* Custom data: types: Add custom types encoding/decoding to store your data types.
+* Encryption: allows for storing data encrypted, while retaining the simple dictionary interface.
 
 ## Example
 Redis is an exceptionally fast database when used appropriately. RedisDict leverages Redis for efficient key-value storage, enabling high-performance data management.
 
-```python
-from redis_dict import RedisDict
+```bash
+pip install redis-dict
+```
 
-dic = RedisDict()
-dic['foo'] = 42
-print(dic['foo'])  # Output: 42
-print('foo' in dic)  # Output: True
-dic["baz"] = "hello world"
-print(dic)  # Output: {'foo': 42, 'baz': 'hello world'}
+```python
+>>> from redis_dict import RedisDict
+>>> dic = RedisDict()
+>>> dic['foo'] = 42
+>>> dic['foo']
+42
+>>> 'foo' in dic
+True
+>>> dic["baz"] = "hello world"
+>>> dic
+{'foo': 42, 'baz': 'hello world'}
 ```
 In Redis our example looks like this.
 ```
@@ -68,12 +49,12 @@ In Redis our example looks like this.
 "str:hello world"
 ```
 
+
 ### Namespaces
-Acting as an identifier for your dictionary across different systems, RedisDict employs namespaces for organized data management. When a namespace isn't specified, "main" becomes the default. Thus allowing for data organization accross systems and projects with the same redis instance.
+Acting as an identifier for your dictionary across different systems, RedisDict employs namespaces for organized data management. When a namespace isn't specified, "main" becomes the default. Thus allowing for data organization across systems and projects with the same redis instance.
 
 This approach also minimizes the risk of key collisions between different applications, preventing hard-to-debug issues. By leveraging namespaces, RedisDict ensures a cleaner and more maintainable data management experience for developers working on multiple projects.
 
-
 ## Advanced Features
 
 ### Expiration
@@ -106,6 +87,8 @@ with dic.expire_at(seconds):
 3. Updating keys while preserving the initial timeout In certain situations, there is a need to update the value while keeping the expiration intact. This is achievable by setting the 'preserve_expiration' to true.
 
 ```python
+import time
+
 dic = RedisDict(expire=10, preserve_expiration=True)
 dic['gone'] = 'in ten seconds'
 
@@ -118,6 +101,7 @@ dic['gone'] = 'gone in 5 seconds'
 Efficiently batch your requests using the Pipeline feature, which can be easily utilized with a context manager.
 
 ```python
+from redis_dict import RedisDict
 dic = RedisDict(namespace="example")
 
 # one round trip to redis
@@ -147,13 +131,14 @@ print(dic["foo"]) # outputs "bar"
 ### Caching made simple
 ```python
 import time
+from datetime import timedelta
 from redis_dict import RedisDict
 
 def expensive_function(x):
-    time.sleep(2)
+    time.sleep(x)
     return x * 2
 
-cache = RedisDict(namespace="cache", expire=10)
+cache = RedisDict(namespace="cache", expire=timedelta(minutes=60))
 
 def cached_expensive_function(x):
     if x not in cache:
@@ -161,7 +146,7 @@ def cached_expensive_function(x):
     return cache[x]
 
 start_time = time.time()
-print(cached_expensive_function(5))  # Takes around 2 seconds to compute and caches the result.
+print(cached_expensive_function(5))  # Takes around 5 seconds to compute and caches the result.
 print(f"Time taken: {time.time() - start_time:.2f} seconds")
 
 start_time = time.time()
@@ -181,7 +166,7 @@ dic["name"] = "John Doe"
 dic["age"] = 32
 dic["city"] = "Amsterdam"
 
-# Get value by key
+# Get value by key, from any instance connected to the same redis/namespace
 print(dic["name"])  # Output: John Doe
 
 # Update value by key, got a year older
@@ -234,10 +219,105 @@ print(dic["d"])  # Output: 4
 For more advanced examples of RedisDict, please refer to the unit-test files in the repository. All features and functionalities are thoroughly tested in [unit tests (here)](https://github.com/Attumm/redis-dict/blob/main/tests.py#L1) Or take a look at load test for batching [load test](https://github.com/Attumm/redis-dict/blob/main/load_test.py#L1).
 The unit-tests can be as used as a starting point.
 
+## Types
+
+### standard types
+RedisDict supports a range of Python data types, from basic types to nested structures.
+Basic types are handled natively, while complex data types like lists and dictionaries, RedisDict uses JSON serialization, specifically avoiding `pickle` due to its [security vulnerabilities](https://docs.python.org/3/library/pickle.html) in distributed computing contexts.
+Although the library supports nested structures, the recommended best practice is to use RedisDict as a shallow dictionary.
+This approach optimizes Redis database performance and efficiency by ensuring that each set and get operation efficiently maps to Redis's key-value storage capabilities, while still preserving the library's Pythonic interface.
+Following types are supported: 
+`str, int, float, bool, NoneType, list, dict, tuple, set, datetime, date, time, timedelta, Decimal, complex, bytes, UUID, OrderedDict, defaultdict, frozenset`
+```python
+from redis_dict import RedisDict
+
+from uuid import UUID
+from decimal import Decimal
+from collections import OrderedDict, defaultdict
+from datetime import datetime, date, time, timedelta
+
+
+dic = RedisDict()
+
+dic["string"] = "Hello World"
+dic["number"] = 42
+dic["float"] = 3.14
+dic["bool"] = True
+dic["None"] = None
+
+dic["list"] = [1, 2, 3]
+dic["dict"] = {"a": 1, "b": 2}
+dic["tuple"] = (1, 2, 3)
+dic["set"] = {1, 2, 3}
+
+dic["datetime"] = datetime.date(2024, 1, 1, 12, 30, 45)
+dic["date"] = date(2024, 1, 1)
+dic["time"] = time(12, 30, 45)
+dic["delta"] = timedelta(days=1, hours=2)
+
+dic["decimal"] = Decimal("3.14159")
+dic["complex"] = complex(1, 2)
+dic["bytes"] = bytes([72, 101, 108, 108, 111])
+dic["uuid"] = UUID('12345678-1234-5678-1234-567812345678')
+
+dic["ordered"] = OrderedDict([('a', 1), ('b', 2)])
+dic["default"] = defaultdict(int, {'a': 1, 'b': 2})
+dic["frozen"] = frozenset([1, 2, 3])
+```
+
+### Extending RedisDict with Custom Types
+
+RedisDict supports custom type serialization. Here's how to add a new type:
+
+
+```python
+import json
+from redis_dict import RedisDict
+
+class Person:
+    def __init__(self, name, age):
+        self.name = name
+        self.age = age
+
+    def encode(self) -> str:
+        return json.dumps(self.__dict__)
+
+    @classmethod
+    def decode(cls, encoded_str: str) -> 'Person':
+        return cls(**json.loads(encoded_str))
+
+redis_dict = RedisDict()
+
+# Extend redis dict with the new type
+redis_dict.extends_type(Person)
+
+# RedisDict can now seamlessly handle Person instances.
+person = Person(name="John", age=32)
+redis_dict["person1"] = person
+
+result = redis_dict["person1"]
+
+assert result.name == person.name
+assert result.age == person.age
+```
+
+```python
+>>> from datetime import datetime
+>>> redis_dict.extends_type(datetime, datetime.isoformat, datetime.fromisoformat)
+>>> redis_dict["now"] = datetime.now()
+>>> redis_dict
+{'now': datetime.datetime(2024, 10, 14, 18, 41, 53, 493775)}
+>>> redis_dict["now"]
+datetime.datetime(2024, 10, 14, 18, 41, 53, 493775)
+```
+
+For more information on [extending types](https://github.com/Attumm/redis-dict/blob/main/extend_types_tests.py).
 ### Redis Encryption
-Setup guide for configuring and utilizing encrypted Redis for redis-dict.
+Setup guide for configuring and utilizing encrypted Redis TLS for redis-dict.
 [Setup guide](https://github.com/Attumm/redis-dict/blob/main/encrypted_redis.MD)
 
+### Redis Storage Encryption
+For storing encrypted data values, it's possible to use extended types. Take a look at this [encrypted test](https://github.com/Attumm/redis-dict/blob/main/encrypt_tests.py).
 
 ### Tests
 The RedisDict library includes a comprehensive suite of tests that ensure its correctness and resilience. The test suite covers various data types, edge cases, and error handling scenarios. It also employs the Hypothesis library for property-based testing, which provides fuzz testing to evaluate the implementation