redis-dict 2.6.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

redis_dict/type_management.py

@@ -0,0 +1,273 @@
+"""Type management module."""
+
+import json
+import base64
+from collections import OrderedDict, defaultdict
+from datetime import datetime, date, time, timedelta
+
+from typing import Callable, Any, Dict, Tuple, Set
+
+from uuid import UUID
+from decimal import Decimal
+
+
+SENTINEL = object()
+
+EncodeFuncType = Callable[[Any], str]
+DecodeFuncType = Callable[[str], Any]
+EncodeType = Dict[str, EncodeFuncType]
+DecodeType = Dict[str, DecodeFuncType]
+
+
+def _create_default_encode(custom_encode_method: str) -> EncodeFuncType:
+    def default_encode(obj: Any) -> str:
+        return getattr(obj, custom_encode_method)()  # type: ignore[no-any-return]
+    return default_encode
+
+
+def _create_default_decode(cls: type, custom_decode_method: str) -> DecodeFuncType:
+    def default_decode(encoded_str: str) -> Any:
+        return getattr(cls, custom_decode_method)(encoded_str)
+    return default_decode
+
+
+def _decode_tuple(val: str) -> Tuple[Any, ...]:
+    """
+    Deserialize a JSON-formatted string to a tuple.
+
+    This function takes a JSON-formatted string, deserializes it to a list, and
+    then converts the list to a tuple.
+
+    Args:
+        val (str): A JSON-formatted string representing a list.
+
+    Returns:
+        Tuple[Any, ...]: A tuple with the deserialized values from the input string.
+    """
+    return tuple(json.loads(val))
+
+
+def _encode_tuple(val: Tuple[Any, ...]) -> str:
+    """
+    Serialize a tuple to a JSON-formatted string.
+
+    This function takes a tuple, converts it to a list, and then serializes
+    the list to a JSON-formatted string.
+
+    Args:
+        val (Tuple[Any, ...]): A tuple with values to be serialized.
+
+    Returns:
+        str: A JSON-formatted string representing the input tuple.
+    """
+    return json.dumps(list(val))
+
+
+def _decode_set(val: str) -> Set[Any]:
+    """
+    Deserialize a JSON-formatted string to a set.
+
+    This function takes a JSON-formatted string, deserializes it to a list, and
+    then converts the list to a set.
+
+    Args:
+        val (str): A JSON-formatted string representing a list.
+
+    Returns:
+        set[Any]: A set with the deserialized values from the input string.
+    """
+    return set(json.loads(val))
+
+
+def _encode_set(val: Set[Any]) -> str:
+    """
+    Serialize a set to a JSON-formatted string.
+
+    This function takes a set, converts it to a list, and then serializes the
+    list to a JSON-formatted string.
+
+    Args:
+        val (set[Any]): A set with values to be serialized.
+
+    Returns:
+        str: A JSON-formatted string representing the input set.
+    """
+    return json.dumps(list(val))
+
+
+decoding_registry: DecodeType = {
+    type('').__name__: str,
+    type(1).__name__: int,
+    type(0.1).__name__: float,
+    type(True).__name__: lambda x: x == "True",
+    type(None).__name__: lambda x: None,
+
+    "list": json.loads,
+    "dict": json.loads,
+    "tuple": _decode_tuple,
+    type(set()).__name__: _decode_set,
+
+    datetime.__name__: datetime.fromisoformat,
+    date.__name__: date.fromisoformat,
+    time.__name__: time.fromisoformat,
+    timedelta.__name__: lambda x: timedelta(seconds=float(x)),
+
+    Decimal.__name__: Decimal,
+    complex.__name__: lambda x: complex(*map(float, x.split(','))),
+    bytes.__name__: base64.b64decode,
+
+    UUID.__name__: UUID,
+    OrderedDict.__name__: lambda x: OrderedDict(json.loads(x)),
+    defaultdict.__name__: lambda x: defaultdict(type(None), json.loads(x)),
+    frozenset.__name__: lambda x: frozenset(json.loads(x)),
+}
+
+
+encoding_registry: EncodeType = {
+    "list": json.dumps,
+    "dict": json.dumps,
+    "tuple": _encode_tuple,
+    type(set()).__name__: _encode_set,
+
+    datetime.__name__: datetime.isoformat,
+    date.__name__: date.isoformat,
+    time.__name__: time.isoformat,
+    timedelta.__name__: lambda x: str(x.total_seconds()),
+
+    complex.__name__: lambda x: f"{x.real},{x.imag}",
+    bytes.__name__: lambda x: base64.b64encode(x).decode('ascii'),
+    OrderedDict.__name__: lambda x: json.dumps(list(x.items())),
+    defaultdict.__name__: lambda x: json.dumps(dict(x)),
+    frozenset.__name__: lambda x: json.dumps(list(x)),
+}
+
+
+class RedisDictJSONEncoder(json.JSONEncoder):
+    """Extends JSON encoding capabilities by reusing RedisDict type conversion.
+
+    Uses existing decoding_registry to know which types to handle specially and
+    encoding_registry (falls back to str) for converting to JSON-compatible formats.
+
+    Example:
+        The encoded format looks like::
+
+            {
+                "__type__": "TypeName",
+                "value": <encoded value>
+            }
+
+    Notes:
+
+        Uses decoding_registry (containing all supported types) to check if type
+        needs special handling. For encoding, defaults to str() if no encoder exists
+        in encoding_registry.
+    """
+    def default(self, o: Any) -> Any:
+        """Overwrite default from json encoder.
+
+        Args:
+            o (Any): Object to be serialized.
+
+        Raises:
+            TypeError: If the object `o` cannot be serialized.
+
+        Returns:
+            Any: Serialized value.
+        """
+        type_name = type(o).__name__
+        if type_name in decoding_registry:
+            return {
+                "__type__": type_name,
+                "value": encoding_registry.get(type_name, _default_encoder)(o)
+            }
+        try:
+            return json.JSONEncoder.default(self, o)
+        except TypeError as e:
+            raise TypeError(f"Object of type {type_name} is not JSON serializable") from e
+
+
+class RedisDictJSONDecoder(json.JSONDecoder):
+    """JSON decoder leveraging RedisDict existing type conversion system.
+
+    Works with RedisDictJSONEncoder to reconstruct Python objects from JSON using
+    RedisDict decoding_registry.
+
+    Still needs work but allows for more types than without.
+    """
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Overwrite the __init__ method from JSON decoder.
+
+        Args:
+            *args (Any): Positional arguments for initialization.
+            **kwargs (Any): Keyword arguments for initialization.
+
+        """
+        def _object_hook(obj: Dict[Any, Any]) -> Any:
+            if "__type__" in obj and "value" in obj:
+                type_name = obj["__type__"]
+                if type_name in decoding_registry:
+                    return decoding_registry[type_name](obj["value"])
+            return obj
+
+        super().__init__(object_hook=_object_hook, *args, **kwargs)
+
+
+def encode_json(obj: Any) -> str:
+    """
+    Encode a Python object to a JSON string using the existing encoding registry.
+
+    Args:
+        obj (Any): The Python object to be encoded.
+
+    Returns:
+        str: The JSON-encoded string representation of the object.
+    """
+    return json.dumps(obj, cls=RedisDictJSONEncoder)
+
+
+def decode_json(s: str) -> Any:
+    """
+    Decode a JSON string to a Python object using the existing decoding registry.
+
+    Args:
+        s (str): The JSON string to be decoded.
+
+    Returns:
+        Any: The decoded Python object.
+    """
+    return json.loads(s, cls=RedisDictJSONDecoder)
+
+
+def _default_decoder(x: str) -> str:
+    """
+    Pass-through decoder that returns the input string unchanged.
+
+    Args:
+        x (str): The input string.
+
+    Returns:
+        str: The same input string.
+    """
+    return x
+
+
+def _default_encoder(x: Any) -> str:
+    """
+    Takes x and returns the result str of the object.
+
+    Args:
+        x (Any): The input object
+
+    Returns:
+        str: output of str of the object
+    """
+    return str(x)
+
+
+encoding_registry["dict"] = encode_json
+decoding_registry["dict"] = decode_json
+
+
+encoding_registry["list"] = encode_json
+decoding_registry["list"] = decode_json

{redis_dict-2.6.0.dist-info → redis_dict-3.0.0.dist-info}/METADATA

@@ -1,13 +1,14 @@
 Metadata-Version: 2.1
 Name: redis-dict
-Version: 2.6.0
+Version: 3.0.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
+Author-email: Melvin Bijman <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
+Project-URL: Homepage, https://github.com/Attumm/redisdict
+Project-URL: Documentation, https://github.com/Attumm/redisdict#readme
+Project-URL: Repository, https://github.com/Attumm/redisdict.git
+Project-URL: Changelog, https://github.com/Attumm/redisdict/releases
+Keywords: redis,python,dictionary,dict,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
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
@@ -21,18 +22,51 @@ 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
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: redis
+Requires-Dist: redis>=4.0.0
+Provides-Extra: dev
+Requires-Dist: coverage==5.5; extra == "dev"
+Requires-Dist: hypothesis==6.70.1; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: mypy-extensions>=1.0.0; extra == "dev"
+Requires-Dist: types-pyOpenSSL>=24.0.0.0; extra == "dev"
+Requires-Dist: types-redis>=4.6.0; extra == "dev"
+Requires-Dist: typing-extensions>=4.5.0; extra == "dev"
+Requires-Dist: pylama>=8.4.1; extra == "dev"
+Requires-Dist: pycodestyle==2.10.0; extra == "dev"
+Requires-Dist: pydocstyle==6.3.0; extra == "dev"
+Requires-Dist: pyflakes==3.0.1; extra == "dev"
+Requires-Dist: pylint==3.2.7; extra == "dev"
+Requires-Dist: mccabe==0.7.0; extra == "dev"
+Requires-Dist: attrs==22.2.0; extra == "dev"
+Requires-Dist: cffi==1.15.1; extra == "dev"
+Requires-Dist: cryptography==43.0.1; extra == "dev"
+Requires-Dist: exceptiongroup==1.1.1; extra == "dev"
+Requires-Dist: future==0.18.3; extra == "dev"
+Requires-Dist: pycparser==2.21; extra == "dev"
+Requires-Dist: snowballstemmer==2.2.0; extra == "dev"
+Requires-Dist: sortedcontainers==2.4.0; extra == "dev"
+Requires-Dist: tomli==2.0.1; extra == "dev"
+Requires-Dist: setuptools>=68.0.0; extra == "dev"
+Requires-Dist: darglint; extra == "dev"
+Requires-Dist: pydocstyle; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: tomli; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
 
 # Redis-dict
+[![PyPI](https://img.shields.io/pypi/v/redis-dict.svg)](https://pypi.org/project/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)
@@ -44,7 +78,7 @@ The library includes utility functions for more complex use cases such as cachin
 ## 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.
@@ -86,7 +120,6 @@ In Redis our example looks like this.
 
 ### 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 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
@@ -135,7 +168,6 @@ 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
@@ -253,16 +285,82 @@ 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.
 
-### Extending Types
+## 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 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])
+```
+
+
+
+### Nested types
+Nested Types
+RedisDict supports nested structures with mixed types through JSON serialization. The feature works by utilizing JSON encoding and decoding under the hood. While this represents an upgrade in functionality, the feature is not fully implemented and should be used with caution. For optimal performance, using shallow dictionaries is recommended.
+```python
+from datetime import datetime, timedelta
+
+dic["mixed"] = [1, "foobar", 3.14, [1, 2, 3], datetime.now()]
+
+dic['dic'] = {"elapsed_time": timedelta(hours=60)}
+```
+
+### JSON Encoding - Decoding
+The nested type support in RedisDict is implemented using custom JSON encoders and decoders. These JSON encoders and decoders are built on top of RedisDict's own encoding and decoding functionality, extending it for JSON compatibility. Since JSON serialization was a frequently requested feature, these enhanced encoders and decoders are available for use in other projects:
+```python
+import json
+from datetime import datetime
+from redis_dict import RedisDictJSONDecoder, RedisDictJSONEncoder
+
+data = [1, "foobar", 3.14, [1, 2, 3], datetime.now()]
+encoded = json.dumps(data, cls=RedisDictJSONEncoder)
+result = json.loads(encoded, cls=RedisDictJSONDecoder)
+```
+
 
-## Extending RedisDict with Custom Types
+### 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):
@@ -291,23 +389,13 @@ 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).
+For more information on [extending types](https://github.com/Attumm/redis-dict/blob/main/tests/unit/extend_types_tests.py).
 ### Redis Encryption
 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)
+[Setup guide](https://github.com/Attumm/redis-dict/blob/main/docs/tutorials/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).
+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/tests/unit/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
@@ -315,19 +403,16 @@ The RedisDict library includes a comprehensive suite of tests that ensure its co
 ### Redis config
 To configure RedisDict using your Redis config.
 
-Configure both the host and port.
+Configure both the host and port. Or configuration with a setting dictionary.
 ```python
 dic = RedisDict(host='127.0.0.1', port=6380)
-```
 
-Configuration with a dictionary.
-```python
 redis_config = {
     'host': '127.0.0.1',
     'port': 6380,
 }
 
-dic = RedisDict(**redis_config)
+confid_dic = RedisDict(**redis_config)
 ```
 
 ## Installation
@@ -338,4 +423,3 @@ pip install redis-dict
 ### Note
 * Please be aware that this project is currently being utilized by various organizations in their production environments. If you have any questions or concerns, feel free to raise issues
 * This project only uses redis as dependency
-

redis_dict-3.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+redis_dict/__init__.py,sha256=fksonUr5DetzwFDEkT7lpmAaV3Jhmp2IQ12t62LwFb4,476
+redis_dict/core.py,sha256=iLVTzpR4HmMPqcgZQWMgdAgwRepLEhTbdxP-tfA13ts,34698
+redis_dict/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+redis_dict/type_management.py,sha256=U3aP_EtHByApRdHvpr-zSOjok6r9BVZ0g3YnpVCVt8Y,7690
+redis_dict-3.0.0.dist-info/LICENSE,sha256=-QiLwYznh_vNUSz337k0faP9Jl0dgtCIHVZ39Uyl6cA,1070
+redis_dict-3.0.0.dist-info/METADATA,sha256=8Zn6a75THLjxiCGfRdFuz675RwSsLrBf0JQE8fH-Kfo,16873
+redis_dict-3.0.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+redis_dict-3.0.0.dist-info/top_level.txt,sha256=Wyp5Xvq_imoxvu-c-Le1rbTZ3pYM5BF440H9YAcgBZ8,11
+redis_dict-3.0.0.dist-info/RECORD,,

{redis_dict-2.6.0.dist-info → redis_dict-3.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.2.0)
+Generator: setuptools (75.3.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

redis_dict-2.6.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-redis_dict.py,sha256=50CSZ5dMBBbr-UU9BSvoGgBItD7uce8F5ty1lphaiUw,36901
-redis_dict-2.6.0.dist-info/LICENSE,sha256=-QiLwYznh_vNUSz337k0faP9Jl0dgtCIHVZ39Uyl6cA,1070
-redis_dict-2.6.0.dist-info/METADATA,sha256=6QJ93NO1RrVKSYbmbgtFKOazqtKrauPstB-H0hI1vDs,12564
-redis_dict-2.6.0.dist-info/WHEEL,sha256=OVMc5UfuAQiSplgO0_WdW7vXVGAt9Hdd6qtN4HotdyA,91
-redis_dict-2.6.0.dist-info/top_level.txt,sha256=Wyp5Xvq_imoxvu-c-Le1rbTZ3pYM5BF440H9YAcgBZ8,11
-redis_dict-2.6.0.dist-info/RECORD,,