Merge branch 'release/0.5.0'

Author: tanbro

.vscode/tasks.json

@@ -3,30 +3,6 @@
     // for the documentation about the tasks.json format
     "version": "2.0.0",
     "tasks": [
-        {
-            "label": "build",
-            "type": "shell",
-            "command": "${command:python.interpreterPath} -m build",
-            "problemMatcher": [
-                "$python"
-            ],
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            }
-        },
-        {
-            "label": "test",
-            "type": "shell",
-            "command": "${command:python.interpreterPath} -m unittest",
-            "problemMatcher": [
-                "$python"
-            ],
-            "group": {
-                "kind": "test",
-                "isDefault": true
-            }
-        },
         {
             "label": "docs: build",
             "type": "shell",

CHANGELOG.md

@@ -2,18 +2,19 @@
 
 ## v0.5
 
-> 📅 developing (beta-2)
+> 📅 2025-08-26
 
 - ✨ **New Features:**
   - Added arguments excluding support for the `RedisFuncCache` class, which makes it possible to cache functions with arguments that cannot be serialized.
   - Added support for controlling cache TTL update behavior with `update_ttl` parameter.
-  - Enhanced cache mode control with context managers:
+  - Enhanced cache mode control with mode context managers:
     - `RedisFuncCache.mode_context()` for applying mode contextually
     - `RedisFuncCache.disable_rw()` as an alias for completely disabling cache read and write operations
     - `RedisFuncCache.read_only()` for read-only cache mode
     - `RedisFuncCache.write_only()` for write-only cache mode
-  - Added new `RedisFuncCache.Stats` class for cache statistics, and `RedisFuncCache.stats_context()` for retrieving cache statistics.
+  - Added new `RedisFuncCache.Stats` class for cache statistics, and `RedisFuncCache.stats_context()` for retrieving cache statistics in a context manager.
   - Added support for per-invocation's cache TTL(experimental).
+  - Added `use_bytecode` attribute to `HashConfig` class.
 
 - 💔 **Breaking Changes:**
   - Rename `redis_func_cache.mixins.policies` to `redis_func_cache.mixins.scripts`.

README.md

@@ -948,21 +948,33 @@ def some_func(*args, **kwargs):
 
 - Compatibility with other [decorator][]s is not guaranteed.
 
-- The built-in policies in `redis_func_cache.policies` use [`pickle`][] to serialize function arguments, then calculate the cache key by hashing the serialized data with `md5`. [`pickle`][] is chosen because only the hash bytes are stored in Redis, not the serialized data itself, so this is safe. However, [`pickle`][] causes **incompatibility between different Python versions**. If your application needs to be compatible across Python versions, you should use a [json][] based hash mixer, or define your own hash policy using a version-compatible serialization method, for example:
+- It cannot hit cache across different Python versions by default. Because:
 
-    ```python
-    from redis_func_cache import RedisFuncCache
-    from redis_func_cache.policies.abstract import BaseSinglePolicy
-    from redis_func_cache.mixins.hash import JsonMd5HashMixin
-    from redis_func_cache.mixins.scripts import LfuScriptsMixin
+  - The built-in policies in `policies` use [`pickle`][] to serialize function arguments and then calculate the cache key by hashing the serialized data with `md5` by default.
 
-    class MyLfuPolicy(LfuScriptsMixin, JsonMd5HashMixin, BaseSinglePolicy):
-        __key__ = "my-lfu"
+    [`pickle`][] is chosen because only the hash bytes are stored in Redis, not the serialized data itself, making this approach safe. However, [`pickle`][] causes **incompatibility between different Python versions**.
 
-    my_cache = RedisFuncCache(__name__, policy=MyLfuPolicy, client=redis_client_factory)
-    ```
+  - The key calculation defined in `mixins.hash.AbstractHashMixin.calc_hash()` uses the function's bytecode as part of the hash computation by default. So it cannot hit cache across different Python versions.
+
+  If your application needs to be compatible across Python versions, you should disable `use_bytecode` attribute of the mixin's `__hash_config__`, and use a [json][] based hash mixer. Or define your own hash policy using a version-compatible serialization method. For example:
+
+  ```python
+  from dataclasses import replace
+  from redis_func_cache import RedisFuncCache as Cache
+  from redis_func_cache.policies.abstract import BaseSinglePolicy
+  from redis_func_cache.mixins.hash import JsonMd5HashMixin
+  from redis_func_cache.mixins.scripts import LfuScriptsMixin
+
+  class MyLfuPolicy(LfuScriptsMixin, JsonMd5HashMixin, BaseSinglePolicy):
+      __key__ = "my-lfu"
+
+      # Override hash config here !!!
+      __hash_config__ = replace(JsonMd5HashMixin.__hash_config__, use_bytecode=False)
+
+  cache = Cache(__name__, policy=MyLfuPolicy, client=redis_client_factory)
+  ```
 
-    As shown above, the `JsonMd5HashMixin` uses [json][], which can be used across different Python versions, rather than [`pickle`][].
+  As shown above, the `JsonMd5HashMixin` uses [json][], which can be used across different Python versions, rather than [`pickle`][]. `use_bytecode` is set to `False` to avoid version compatible problems caused by bytecode.
 
 - The cache eviction policies are mainly based on [Redis][] sorted set's score ordering. For most policies, the score is a positive integer. Its maximum value is `2^32-1` in [Redis][], which limits the number of times of eviction replacement. [Redis][] will return an `overflow` error when the score overflows.
 

docs/README.rst

@@ -25,7 +25,7 @@ How to Build the Documentation
 
    .. code:: sh
 
-      sphinx-apidoc -o docs/apidocs -f -e -H APIs src
+      sphinx-apidoc -H "" -feo docs/apidocs src
 
 #. Build HTML documentation:
 

docs/conf.py

@@ -109,7 +109,7 @@
     "redis": ("https://redis.readthedocs.io/en/stable/", None),
     "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
     "msgpack": ("https://msgpack-python.readthedocs.io/en/stable/", None),
-    "pygments": ("https://pygments.org/docs/", None),
+    "pygments": ("https://pygments.org/", None),
 }
 
 # -- Options for Napoleon settings ---------------------------------------