Support runtime subscripting of ObjectProxy via __class_getitem__.

The type stubs declare ObjectProxy, BaseObjectProxy and their
subclasses (AutoObjectProxy, LazyObjectProxy, CallableObjectProxy,
FunctionWrapper, BoundFunctionWrapper) as generic on the wrapped
type, so users can write annotations like
`proxy: BaseObjectProxy[int] = ...`. The runtime classes did not
implement __class_getitem__, so such annotations failed with
TypeError: type 'ObjectProxy' is not subscriptable on Python
versions that evaluate annotations eagerly. The same error was
raised by subclassing with a subscripted base
(`class MyProxy(ObjectProxy[int]):`) and by typing.get_type_hints()
resolving deferred annotations on any supported version.

Add __class_getitem__ to both the Python and C implementations of
ObjectProxy. The Python side uses classmethod(types.GenericAlias).
The C side adds Py_GenericAlias with METH_O | METH_CLASS to the
WraptObjectProxy methods array. All proxy and wrapper subclasses
inherit the method via MRO so no per-class additions are required.

Author: GrahamDumpleton

docs/typing.rst

@@ -253,3 +253,139 @@ constructor of the class at the point it it is being created.
 
     @ClassDecorator("string") # <-- Invalid error warning.
     def function(): ...
+
+Object Proxies
+--------------
+
+In addition to the decorator factories, the **wrapt** module exposes a family
+of object proxy classes that can be used to build custom wrappers for
+arbitrary objects. The core classes are ``wrapt.BaseObjectProxy``,
+``wrapt.ObjectProxy``, ``wrapt.AutoObjectProxy``, ``wrapt.LazyObjectProxy``
+and ``wrapt.CallableObjectProxy``. Each is generic on a single type
+parameter that stands for the type of the wrapped object.
+
+``wrapt.BaseObjectProxy`` is the recommended base for custom proxy
+subclasses; ``wrapt.ObjectProxy`` is retained for backward compatibility
+and is a thin subclass of ``BaseObjectProxy``. The discussion below applies
+equally to both.
+
+Annotating a proxy with the type of its wrapped value lets the type checker
+reason about ``proxy.__wrapped__``:
+
+::
+
+    import wrapt
+
+    proxy: wrapt.ObjectProxy[int] = wrapt.ObjectProxy(5)
+
+    value: int = proxy.__wrapped__
+
+Subclassing a proxy with a specific wrapped type is also supported, and is
+the idiomatic way to define a proxy for a particular kind of object:
+
+::
+
+    from io import TextIOWrapper
+    from typing import Any
+
+    class FileProxy(wrapt.ObjectProxy[TextIOWrapper[Any]]):
+        pass
+
+    fp = FileProxy(open("/path/to/file"))
+
+    wrapped_file: TextIOWrapper[Any] = fp.__wrapped__
+
+What the type parameter does and does not propagate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The type parameter only affects the ``__wrapped__`` attribute directly.
+Most other access through the proxy is intentionally typed as ``Any``,
+because the runtime forwarding depends on the wrapped object's interface,
+which the stubs cannot claim statically without sacrificing flexibility:
+
+* Attribute access via ``proxy.foo`` returns ``Any``, since the proxy's
+  ``__getattr__`` forwards to the wrapped object.
+* Arithmetic and bitwise operators such as ``proxy + 1`` return ``Any``
+  because the result type depends on the wrapped value's implementation.
+* Container operations (``proxy[key]``, ``len(proxy)``, ...) return
+  permissive types.
+* Context-manager usage ``with proxy as v:`` binds ``v`` as ``Any``,
+  because the wrapped object's ``__enter__`` can return a value of any
+  type (for example, ``threading.Lock.__enter__`` returns ``bool``, not
+  the lock itself).
+
+If you need a statically typed view of a specific attribute or operation,
+access the underlying value via ``proxy.__wrapped__`` where it is typed as
+the wrapped type, or assign the result of an expression to a variable with
+an explicit annotation:
+
+::
+
+    proxy: wrapt.ObjectProxy[int] = wrapt.ObjectProxy(5)
+
+    bits: int = proxy.__wrapped__.bit_length()  # Inferred as int.
+
+Using a proxy class without a type parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Writing ``wrapt.ObjectProxy`` on its own as a type annotation, without a
+``[T]`` parameter, is equivalent to ``wrapt.ObjectProxy[Any]`` from the type
+checker's perspective. It is valid code, but the wrapped object's type is
+unknown and ``proxy.__wrapped__`` is typed as ``Any`` rather than a specific
+type:
+
+::
+
+    proxy: wrapt.ObjectProxy = wrapt.ObjectProxy(5)  # ObjectProxy[Any].
+
+    value = proxy.__wrapped__  # Any.
+
+Strict type checker modes (for example ``mypy --strict``) flag the
+unparameterised form as missing type parameters, and require you to write
+``wrapt.ObjectProxy[Any]`` explicitly if that is what you intend. Under
+default settings the two forms are interchangeable for type checking
+purposes, but subscripting with a concrete type is preferred whenever the
+wrapped type is known.
+
+Function Wrappers
+-----------------
+
+``wrapt.FunctionWrapper`` and ``wrapt.BoundFunctionWrapper`` are the runtime
+types produced by ``@wrapt.decorator`` and ``@wrapt.function_wrapper``. Both
+are generic on two parameters: a ``ParamSpec`` representing the wrapped
+callable's parameter signature, and a ``TypeVar`` representing its return
+type.
+
+In most cases you do not need to annotate a function wrapper at all. The
+decorator machinery infers the type parameters from the signature of the
+wrapped function, so a decorated function continues to appear to the type
+checker as a callable with the same arguments and return type:
+
+::
+
+    @pass_through
+    def add(a: int, b: int) -> int:
+        return a + b
+
+    # Inferred as wrapt.FunctionWrapper[[int, int], int].
+
+If you want to store a reference to a decorated function in a container,
+pass it to another function, or otherwise name the type explicitly, the
+subscripted form can be used:
+
+::
+
+    wrapped_add: wrapt.FunctionWrapper[[int, int], int] = add
+
+As with object proxies, writing ``wrapt.FunctionWrapper`` on its own is
+equivalent to ``wrapt.FunctionWrapper[Any, Any]``: a callable of any
+signature returning any type. The idiomatic spelling for "any signature" is
+``wrapt.FunctionWrapper[..., Any]``, using ``...`` in the parameter-spec
+position. Strict type checker modes will ask for explicit parameters in
+either case.
+
+``wrapt.BoundFunctionWrapper`` is the type produced when a
+``FunctionWrapper`` is accessed via the descriptor protocol on an instance
+or class (for example, a decorated method accessed through ``self``). You
+rarely need to name this type directly; it is produced automatically and
+flows through type inference.

src/wrapt-stubs/__init__.pyi

@@ -93,12 +93,13 @@ if sys.version_info >= (3, 10):
     # AutoObjectProxy based on the wrapped interface) are intentionally
     # NOT claimed statically on BaseObjectProxy.
     #
-    # `__enter__`/`__aenter__` return `_T` rather than `Any` because the
-    # runtime forwards to the wrapped object's `__enter__`, which for the
-    # common "wrap a context manager" use case returns the wrapped object
-    # itself -- this preserves type information through `with proxy as x`.
-    # Other operator dunders return `Any` since the result depends on the
-    # wrapped type.
+    # `__enter__`/`__aenter__` return `Any` because the runtime forwards to
+    # the wrapped object's `__enter__`, which may return a value of any type
+    # (for example, `threading.Lock.__enter__` returns `bool`, not the lock
+    # itself). Returning `_T` would be a false claim that the value bound by
+    # `with proxy as x` is the wrapped type, which is only sometimes true.
+    # Other operator dunders return `Any` for the same reason: the result
+    # depends on the wrapped type.
 
     class BaseObjectProxy(Generic[_T]):
         __wrapped__: _T
@@ -111,14 +112,14 @@ if sys.version_info >= (3, 10):
         def __mro_entries__(self, bases: tuple[type, ...]) -> tuple[type, ...]: ...
 
         # Context managers.
-        def __enter__(self) -> _T: ...
+        def __enter__(self) -> Any: ...
         def __exit__(
             self,
             exc_type: type[BaseException] | None,
             exc_value: BaseException | None,
             traceback: TracebackType | None,
         ) -> bool | None: ...
-        async def __aenter__(self) -> _T: ...
+        async def __aenter__(self) -> Any: ...
         async def __aexit__(
             self,
             exc_type: type[BaseException] | None,

src/wrapt/_wrappers.c

@@ -3155,6 +3155,7 @@ static PyMethodDef WraptObjectProxy_methods[] = {
      METH_O, 0},
     {"__subclasscheck__", (PyCFunction)WraptObjectProxy_subclasscheck,
      METH_VARARGS, 0},
+    {"__class_getitem__", Py_GenericAlias, METH_O | METH_CLASS, 0},
     {NULL, NULL},
 };
 

src/wrapt/wrappers.py

@@ -3,6 +3,7 @@
 import inspect
 import operator
 import sys
+import types
 
 
 class WrapperNotInitializedError(ValueError):
@@ -163,6 +164,8 @@ class ObjectProxy(_ObjectProxyDictBase, metaclass=_ObjectProxyMetaType):
     """A transparent object proxy that delegates attribute access to a
     wrapped object."""
 
+    __class_getitem__ = classmethod(types.GenericAlias)
+
     def __init__(self, wrapped):
         """Create an object proxy around the given object."""
 

tests/core/test_object_proxy.py

@@ -53,16 +53,27 @@ def test_init_called_wrapped_deleted(self):
 
         del a.__wrapped_factory__
 
+        # Removing the class-level __wrapped_factory__ is necessary to
+        # observe the post-init / pre-wrapped state, but the attribute
+        # must be restored so later tests in the suite that construct a
+        # LazyObjectProxy do not see it missing.
+
+        restore = []
         for cls in type(a).__mro__:
             if "__wrapped_factory__" in cls.__dict__:
+                restore.append((cls, cls.__dict__["__wrapped_factory__"]))
                 delattr(cls, "__wrapped_factory__")
                 break
 
-        with self.assertRaises(wrapt.wrappers.WrapperNotInitializedError):
-            a.__wrapped__
-
-        with self.assertRaises(ValueError):
-            a.__wrapped__
+        try:
+            with self.assertRaises(wrapt.wrappers.WrapperNotInitializedError):
+                a.__wrapped__
+
+            with self.assertRaises(ValueError):
+                a.__wrapped__
+        finally:
+            for cls, attr in restore:
+                setattr(cls, "__wrapped_factory__", attr)
 
     def test_attributes(self):
         def function1(*args, **kwargs):