Restructure code and rename internal classes for consistency.

Split decorators.py into topic-focused modules:

- caching.py for lru_cache and its supporting classes.
- synchronization.py for synchronized, mark_as_sync, mark_as_async,
  async_to_sync, sync_to_async, and their supporting classes.

decorators.py now holds only the decorator factory, adapter machinery,
and bind_state_to_wrapper.

Renamed non-public classes so they all follow the same convention:
Qualifier + FunctionWrapper for unbound wrappers, with Bound prefix for
the corresponding bound wrapper. Six previously-unprefixed internal
classes gained underscore prefixes (AdapterFunctionWrapper and the
Sync/Async FunctionWrapper pairs, plus DelegatedAdapterFactory). The
two internal PartialDecorator classes in the synchronized lock path
were renamed to SynchronizedLockProxy for clarity.

StateBindingWrapper removed from the public API; the snake-case alias
bind_state_to_wrapper is retained as the sole public name.

Author: GrahamDumpleton

docs/changes.rst

@@ -1210,14 +1210,14 @@ Version 1.10.0
 
   ::
 
-      class DelegatedAdapterFactory(wrapt.AdapterFactory):
+      class _DelegatedAdapterFactory(wrapt.AdapterFactory):
           def __init__(self, factory):
-              super(DelegatedAdapterFactory, self).__init__()
+              super(_DelegatedAdapterFactory, self).__init__()
               self.factory = factory
           def __call__(self, wrapped):
               return self.factory(wrapped)
 
-      adapter_factory = DelegatedAdapterFactory
+      adapter_factory = _DelegatedAdapterFactory
 
 **Bugs Fixed**
 

docs/decorators.rst

@@ -562,14 +562,14 @@ example, ``wrapt.adapter_factory()`` is itself implemented as:
 
 ::
 
-  class DelegatedAdapterFactory(wrapt.AdapterFactory):
+  class _DelegatedAdapterFactory(wrapt.AdapterFactory):
       def __init__(self, factory):
-          super(DelegatedAdapterFactory, self).__init__()
+          super(_DelegatedAdapterFactory, self).__init__()
           self.factory = factory
       def __call__(self, wrapped):
           return self.factory(wrapped)
 
-  adapter_factory = DelegatedAdapterFactory
+  adapter_factory = _DelegatedAdapterFactory
 
 Decorating Functions
 --------------------

src/wrapt/__init__.py

@@ -13,14 +13,15 @@
     PartialCallableObjectProxy,
     partial,
 )
+from .caching import lru_cache
 from .decorators import (
     AdapterFactory,
-    StateBindingWrapper,
     adapter_factory,
-    async_to_sync,
     bind_state_to_wrapper,
     decorator,
-    lru_cache,
+)
+from .synchronization import (
+    async_to_sync,
     mark_as_async,
     mark_as_sync,
     sync_to_async,
@@ -57,7 +58,6 @@
     "PartialCallableObjectProxy",
     "partial",
     "AdapterFactory",
-    "StateBindingWrapper",
     "adapter_factory",
     "bind_state_to_wrapper",
     "async_to_sync",

src/wrapt/__init__.pyi

@@ -403,45 +403,47 @@ if sys.version_info >= (3, 10):
 
     # bind_state_to_wrapper()
 
-    class StateBindingWrapper:
+    class _StateBindingWrapper:
         name: str
         wrapper_factory: Descriptor | None
         def __init__(self, *, name: str = "state") -> None: ...
-        def __call__(self, wrapper_factory: Descriptor) -> StateBindingWrapper: ...
+        def __call__(self, wrapper_factory: Descriptor) -> _StateBindingWrapper: ...
         def __get__(
             self, instance: Any, owner: type[Any] | None = None
         ) -> (
-            StateBindingWrapper
+            _StateBindingWrapper
             | Callable[[Callable[..., Any]], FunctionWrapper[..., Any]]
         ): ...
 
-    bind_state_to_wrapper = StateBindingWrapper
+    bind_state_to_wrapper = _StateBindingWrapper
 
     # lru_cache()
 
-    class _LRUCacheBoundWrapper(BoundFunctionWrapper[P1, R1]):
+    class _BoundLRUCacheFunctionWrapper(BoundFunctionWrapper[P1, R1]):
         def cache_info(self) -> Any | None: ...
         def cache_clear(self) -> None: ...
         def cache_parameters(self) -> dict[str, Any] | None: ...
 
-    class _LRUCacheWrapper(FunctionWrapper[P1, R1]):
-        __bound_function_wrapper__: type[_LRUCacheBoundWrapper[P1, R1]]
+    class _LRUCacheFunctionWrapper(FunctionWrapper[P1, R1]):
+        __bound_function_wrapper__: type[_BoundLRUCacheFunctionWrapper[P1, R1]]
         def cache_info(self) -> Any | None: ...
         def cache_clear(self) -> None: ...
         def cache_parameters(self) -> dict[str, Any] | None: ...
 
     @overload
-    def lru_cache(func: Callable[P, R], /) -> _LRUCacheWrapper[P, R]: ...
+    def lru_cache(func: Callable[P, R], /) -> _LRUCacheFunctionWrapper[P, R]: ...
     @overload
     def lru_cache(
         func: None = None, /, **kwargs: Any
-    ) -> Callable[[Callable[P, R]], _LRUCacheWrapper[P, R]]: ...
+    ) -> Callable[[Callable[P, R]], _LRUCacheFunctionWrapper[P, R]]: ...
 
     # with_signature()
 
     def with_signature(
         *,
         prototype: Callable[..., Any] | None = None,
         signature: Signature | None = None,
-        factory: Callable[[Callable[..., Any]], Signature | Callable[..., Any]] | None = None,
+        factory: (
+            Callable[[Callable[..., Any]], Signature | Callable[..., Any]] | None
+        ) = None,
     ) -> Callable[[Callable[P, R]], FunctionWrapper[P, R]]: ...

src/wrapt/caching.py

@@ -0,0 +1,212 @@
+"""Caching decorators. Currently provides ``lru_cache``, a drop-in
+replacement for ``functools.lru_cache`` with correct handling of instance
+methods: a separate cache is maintained per instance, stored as an
+attribute on the instance itself so it is cleaned up with the instance
+by the garbage collector. For plain functions, class methods, and static
+methods a single shared cache is used, matching ``functools.lru_cache``.
+"""
+
+from functools import lru_cache as _functools_lru_cache
+from functools import partial
+
+from .__wrapt__ import BoundFunctionWrapper, FunctionWrapper
+from .decorators import decorator
+from .synchronization import synchronized
+
+# Decorator that applies functools.lru_cache to the wrapped function.
+# Unlike using functools.lru_cache directly, this works correctly with
+# instance methods and class methods by maintaining a separate cache
+# per instance or class. Each per-instance cache is stored as an
+# attribute on the instance itself, so it is automatically cleaned up
+# when the instance is garbage collected. For plain functions and
+# static methods, a single cache is stored on the wrapper itself.
+# The underlying caches are created lazily on first call, with
+# double-checked locking via synchronized to avoid races in
+# multi-threaded code.
+#
+# Custom FunctionWrapper and BoundFunctionWrapper subclasses are used
+# so that cache_info() and cache_clear() are available directly on
+# the decorated function. For bound methods, the BoundFunctionWrapper
+# uses _self_instance to locate the per-instance cache.
+
+
+class _BoundLRUCacheFunctionWrapper(BoundFunctionWrapper):
+
+    def _is_instance_method(self):
+        return self._self_binding == "function"
+
+    def __call__(self, *args, **kwargs):
+        parent = self._self_parent
+
+        # For class methods and static methods, use a single shared
+        # cache stored on the parent wrapper. The cache is created
+        # from the bound __wrapped__ since the parent's __wrapped__
+        # is the raw classmethod/staticmethod descriptor.
+
+        if not self._is_instance_method():
+            if parent._self_cache is None:
+                with synchronized(parent):
+                    if parent._self_cache is None:
+                        parent._self_cache = _functools_lru_cache(
+                            **parent._self_lru_kwargs
+                        )(self.__wrapped__)
+
+            return parent._self_cache(*args, **kwargs)
+
+        # Instance method — per-instance cache stored as an attribute
+        # on the instance so it is cleaned up with the instance by the
+        # garbage collector.
+
+        instance = self._self_instance
+        cache_attr = parent._self_cache_attr
+
+        cache = getattr(instance, cache_attr, None)
+
+        if cache is None:
+            with synchronized(parent):
+                cache = getattr(instance, cache_attr, None)
+
+                if cache is None:
+                    cache = _functools_lru_cache(**parent._self_lru_kwargs)(
+                        self.__wrapped__
+                    )
+
+                    setattr(instance, cache_attr, cache)
+
+        return cache(*args, **kwargs)
+
+    def cache_info(self):
+        """Return the cache statistics for this binding's cache, or
+        ``None`` if the cache has not yet been created.
+        """
+
+        if not self._is_instance_method():
+            return self._self_parent.cache_info()
+
+        cache = getattr(self._self_instance, self._self_parent._self_cache_attr, None)
+
+        if cache is not None:
+            return cache.cache_info()
+
+        return None
+
+    def cache_clear(self):
+        """Clear this binding's cache."""
+
+        if not self._is_instance_method():
+            self._self_parent.cache_clear()
+            return
+
+        cache = getattr(self._self_instance, self._self_parent._self_cache_attr, None)
+
+        if cache is not None:
+            cache.cache_clear()
+
+    def cache_parameters(self):
+        """Return the parameters used to create the cache."""
+
+        if not self._is_instance_method():
+            return self._self_parent.cache_parameters()
+
+        cache = getattr(self._self_instance, self._self_parent._self_cache_attr, None)
+
+        if cache is not None:
+            return cache.cache_parameters()
+
+        return None
+
+
+class _LRUCacheFunctionWrapper(FunctionWrapper):
+
+    __bound_function_wrapper__ = _BoundLRUCacheFunctionWrapper
+
+    def __init__(self, wrapped, wrapper, **kwargs):
+        super().__init__(wrapped, wrapper, **kwargs)
+
+        # Extract the LRU cache configuration that was attached to the
+        # wrapper function before it was passed to the decorator.
+
+        self._self_lru_kwargs = wrapper._self_lru_kwargs
+        self._self_cache = None
+
+        # Use __func__ to get the name for classmethod/staticmethod
+        # descriptors which lack __name__ on Python < 3.10.
+
+        name = getattr(wrapped, "__name__", None)
+
+        if name is None:
+            name = wrapped.__func__.__name__
+
+        self._self_cache_attr = "_lru_cache_" + name
+
+    def __call__(self, *args, **kwargs):
+        # Plain function or static method — single cache stored
+        # on the wrapper itself.
+
+        if self._self_cache is None:
+            with synchronized(self):
+                if self._self_cache is None:
+                    self._self_cache = _functools_lru_cache(**self._self_lru_kwargs)(
+                        self.__wrapped__
+                    )
+
+        return self._self_cache(*args, **kwargs)
+
+    def cache_info(self):
+        """Return the cache statistics, or ``None`` if the cache has
+        not yet been created.
+        """
+
+        if self._self_cache is not None:
+            return self._self_cache.cache_info()
+
+        return None
+
+    def cache_clear(self):
+        """Clear the cache and reset the statistics."""
+
+        if self._self_cache is not None:
+            self._self_cache.cache_clear()
+
+    def cache_parameters(self):
+        """Return the parameters used to create the cache, or ``None``
+        if the cache has not yet been created.
+        """
+
+        if self._self_cache is not None:
+            return self._self_cache.cache_parameters()
+
+        return None
+
+
+def lru_cache(func=None, /, **kwargs):
+    """A decorator that applies ``functools.lru_cache`` to the wrapped
+    function, with correct handling for instance methods, class methods,
+    and static methods.
+
+    For instance methods, a separate ``functools.lru_cache`` is
+    maintained per instance. The cache is stored as an attribute on the
+    instance itself, so it is automatically cleaned up when the instance
+    is garbage collected. This means instances do not need to be
+    hashable, each instance gets its own full ``maxsize`` budget, and
+    no external mapping prevents garbage collection.
+
+    For plain functions, class methods, and static methods, a single
+    shared cache is used.
+
+    All keyword arguments are passed through to ``functools.lru_cache``.
+
+    Cache management methods ``cache_info()`` and ``cache_clear()`` are
+    available directly on the decorated function. For bound methods,
+    these operate on the per-instance cache for the bound instance.
+    """
+
+    if func is None:
+        return partial(lru_cache, **kwargs)
+
+    def _wrapper(wrapped, instance, args, _kwargs):
+        return wrapped(*args, **_kwargs)
+
+    _wrapper._self_lru_kwargs = kwargs
+
+    return decorator(_wrapper, proxy=_LRUCacheFunctionWrapper)(func)