feat: add async guard and improve handling for instance methods in @cachier

- Raise TypeError for async instance methods without `allow_non_static_methods` opt-in.
- Document `allow_non_static_methods` usage in README and config.
- Generalize hashing utilities to reduce redundancy in test code.

Author: Borda

README.rst

@@ -118,7 +118,8 @@ Class and object methods can also be cached. Cachier will automatically ignore t
       return result
 
     # Instance method relies on object attribute, NOT good to cache
-    @cachier(allow_non_static_methods=True)
+    # @cachier() would raise TypeError here -- this is intentional
+    @cachier()
     def bad_usage(self, arg_1, arg_2):
       return arg_1 + arg_2 + self.arg_3
 

src/cachier/config.py

@@ -131,7 +131,9 @@ def set_global_params(**params: Any) -> None:
       'cleanup_interval', and 'caching_enabled'. In some cores, if the
       decorator was created without concrete value for 'wait_for_calc_timeout',
       calls that check calculation timeouts will fall back to the global
-      'wait_for_calc_timeout' as well.
+      'wait_for_calc_timeout' as well. 'allow_non_static_methods'
+      (decoration-time only) controls whether instance methods are
+      permitted; it is read once when @cachier is applied, not on each call.
 
     Note that ``allow_non_static_methods`` is a **decoration-time**
     parameter: it is checked once when the ``@cachier`` decorator is

src/cachier/core.py

@@ -374,11 +374,11 @@ def _cachier_decorator(func):
                 raise TypeError(
                     f"@cachier cannot decorate instance method "
                     f"'{func.__qualname__}' because the 'self' parameter is "
-                    f"excluded from cache-key computation and all instances "
-                    f"would share a single cache. Pass allow_non_static_methods=True "
-                    f"to the decorator or call "
-                    f"set_global_params(allow_non_static_methods=True) if "
-                    f"cross-instance cache sharing is intentional."
+                    "excluded from cache-key computation and all instances "
+                    "would share a single cache. Pass allow_non_static_methods=True "
+                    "to the decorator or call "
+                    "set_global_params(allow_non_static_methods=True) if "
+                    "cross-instance cache sharing is intentional."
                 )
 
         is_coroutine = inspect.iscoroutinefunction(func)

src/cachier/cores/base.py

@@ -62,7 +62,7 @@ def set_func(self, func):
         -----
         Detection is name-based: only ``func_params[0] == "self"`` is
         checked.  ``@classmethod`` functions whose first parameter is
-        conventionally named ``cls`` are **not** detected as methods --
+        conventionally named ``cls`` are not detected as methods --
         this is a known gap.
 
         """

tests/test_async_core.py

@@ -315,6 +315,15 @@ async def async_method(self, x):
 
         obj1.async_method.clear_cache()
 
+    async def test_guard_raises_without_opt_in(self):
+        """Test that @cachier raises TypeError for async instance methods without opt-in."""
+        with pytest.raises(TypeError, match="allow_non_static_methods"):
+
+            class MyClass:
+                @cachier(backend="memory")
+                async def async_method(self, x):
+                    return x
+
 
 # =============================================================================
 # Sync Function Compatibility Tests

tests/test_smoke.py

@@ -1,6 +1,8 @@
 """Smoke tests for cachier - fast, no external service dependencies."""
 
 import datetime
+import hashlib
+import pickle
 
 import pytest
 
@@ -186,9 +188,6 @@ def test_classmethod_not_guarded():
     # ``cls``.
     def _hash_ignore_cls(args, kwds):
         filtered = {k: v for k, v in kwds.items() if k != "cls"}
-        import hashlib
-        import pickle
-
         return hashlib.sha256(pickle.dumps((args, sorted(filtered.items())))).hexdigest()
 
     class Foo: