[functools] Support binding wrapped methods (#16515)

Author: AlexWaygood

stdlib/@tests/test_cases/check_functools.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from functools import cache, cached_property, lru_cache, wraps
+from functools import cache, cached_property, lru_cache, update_wrapper, wraps
 from typing import Callable, ParamSpec, TypeVar
 from typing_extensions import assert_type
 
@@ -33,9 +33,26 @@ def wrapped(x: int) -> None: ...
     def identical_wrapper(x: int) -> None: ...
     @wraps(wrapped)
     def other_signature_wrapper(x: str, y: float) -> None: ...
+    @wraps(wrapped)
+    def no_args_wrapper() -> None: ...
+    @wraps(wrapped)
+    def keyword_only_wrapper(*, x: int) -> None: ...
 
     identical_wrapper(3)
+    identical_wrapper(x=3)
     other_signature_wrapper("parrot", 42.0)
+    no_args_wrapper()
+    keyword_only_wrapper(x=3)
+
+
+def check_update_wrapper() -> None:
+    def wrapped(x: int) -> None: ...
+    def wrapper(*, text: str) -> int:
+        return len(text)
+
+    updated = update_wrapper(wrapper, wrapped)
+    assert_type(updated(text="parrot"), int)
+    assert_type(updated.__wrapped__(3), None)
 
 
 def check_wraps_method() -> None:
@@ -44,18 +61,19 @@ def wrapped(self, x: int) -> None: ...
         @wraps(wrapped)
         def wrapper(self, x: int) -> None: ...
 
-    class Wrapper:  # pyright: ignore[reportUnusedClass]
+    class Wrapper:
         @wraps(Wrapped.wrapped)
         def method(self, x: int) -> None: ...
 
     @wraps(Wrapped.wrapped)
     def func_wrapper(x: int) -> None: ...
 
-    # TODO: The following should work, but currently don't.
-    # https://github.com/python/typeshed/issues/10653
-    # Wrapped().wrapper(3)
-    # Wrapper().method(3)
+    assert_type(Wrapped.wrapper(Wrapped(), x=3), None)
+    assert_type(Wrapped().wrapper(3), None)
+    assert_type(Wrapped().wrapper(x=3), None)
+    assert_type(Wrapper().method(3), None)
     func_wrapper(3)
+    func_wrapper(x=3)
 
 
 #

stdlib/functools.pyi

@@ -5,6 +5,7 @@ from collections.abc import Callable, Hashable, Iterable, Sized
 from types import GenericAlias
 from typing import (
     Any,
+    Concatenate,
     Final,
     Generic,
     Literal,
@@ -43,6 +44,8 @@ _PWrapped = ParamSpec("_PWrapped")
 _RWrapped = TypeVar("_RWrapped")
 _PWrapper = ParamSpec("_PWrapper")
 _RWrapper = TypeVar("_RWrapper")
+_WrapperSelfT = TypeVar("_WrapperSelfT")
+_PBound = ParamSpec("_PBound")
 
 if sys.version_info >= (3, 14):
     @overload
@@ -117,10 +120,17 @@ WRAPPER_UPDATES: Final[tuple[Literal["__dict__"]]]
 class _Wrapped(Generic[_PWrapped, _RWrapped, _PWrapper, _RWrapper]):
     __wrapped__: Callable[_PWrapped, _RWrapped]
     def __call__(self, *args: _PWrapper.args, **kwargs: _PWrapper.kwargs) -> _RWrapper: ...
-    # as with ``Callable``, we'll assume that these attributes exist
+    # as with ``Callable``, we'll assume that these attributes/methods exist
     __name__: str
     __qualname__: str
 
+    @overload
+    def __get__(self, instance: None, owner: type, /) -> Self: ...
+    @overload
+    def __get__(
+        self: Callable[Concatenate[_WrapperSelfT, _PBound], _RWrapper], instance: _WrapperSelfT, owner: type | None = None, /
+    ) -> Callable[_PBound, _RWrapper]: ...
+
 @type_check_only
 class _Wrapper(Generic[_PWrapped, _RWrapped]):
     def __call__(self, f: Callable[_PWrapper, _RWrapper]) -> _Wrapped[_PWrapped, _RWrapped, _PWrapper, _RWrapper]: ...