Merge branch 'release/2.4.1'

Author: GrahamDumpleton

docs/api.rst

@@ -339,7 +339,10 @@ Object Proxies
 ``wrapt.PartialCallableObjectProxy``
     A proxy that combines a callable with a set of pre-bound positional
     and keyword arguments, analogous to ``functools.partial`` but
-    implemented as an object proxy.
+    implemented as an object proxy. The bound arguments are available as
+    the ``_self_args`` and ``_self_kwargs`` attributes, and
+    ``inspect.signature()`` reports the signature of the callable with
+    the bound parameters removed, as it does for ``functools.partial``.
 
 ``wrapt.partial``
     Factory function that returns a ``PartialCallableObjectProxy``,

docs/changes.rst

@@ -1,6 +1,56 @@
 Release Notes
 =============
 
+Version 2.4.1
+-------------
+
+**Bugs Fixed**
+
+* The C extension implementation of ``PartialCallableObjectProxy`` did not
+  expose the bound positional and keyword arguments supplied when the proxy
+  was created, whereas the pure Python implementation makes them available
+  as the ``_self_args`` and ``_self_kwargs`` attributes. The C extension
+  implementation now provides read only ``_self_args`` and ``_self_kwargs``
+  attributes so that both implementations behave the same.
+
+* ``inspect.signature()`` applied to a ``PartialCallableObjectProxy`` reported
+  the full signature of the wrapped callable, including the parameters that
+  the bound positional and keyword arguments already supply, whereas for
+  ``functools.partial`` those parameters are removed. The proxy did not
+  define ``__signature__``, so ``inspect`` followed ``__wrapped__`` back to
+  the callable and reported its signature unchanged. The proxy now provides
+  ``__signature__`` on instances, in both the pure Python and C extension
+  implementations, giving the same result as for an equivalent
+  ``functools.partial``, including a ``ValueError`` when more positional
+  arguments are bound than the callable accepts.
+
+  This also affected wrapper functions used with ``FunctionWrapper`` and
+  ``@wrapt.decorator``. When a wrapped method is called via its class with
+  the instance passed explicitly, the wrapper function receives a
+  ``PartialCallableObjectProxy`` with the instance bound, and ``args``
+  without the instance. A wrapper which bound ``args`` and ``kwargs``
+  against ``inspect.signature(wrapped)`` would fail for such calls with a
+  ``TypeError`` about a missing argument, while working for calls made via
+  the instance. The reported signature now omits the bound instance so
+  the binding succeeds.
+
+  The signature of a partial whose wrapped callable is itself an already
+  bound method is still reported incorrectly, for reasons outside of the
+  control of ``wrapt``. See the "Known Issues" documentation for details.
+
+* The C extension intercepts the ``__module__`` and ``__doc__`` attributes
+  by name in its attribute get and set slots so that they are forwarded to
+  the wrapped object. The name was compared by identity against an interned
+  string, which relied on the attribute name having been interned. Names
+  originating from Python source code always are, but a name constructed at
+  runtime, for example by string concatenation or by decoding, is not, and
+  for such a name the interception was skipped. Getting the attribute then
+  returned the value captured when the proxy was created rather than the
+  current value on the wrapped object, and setting it stored the value on
+  the proxy rather than the wrapped object. The comparison now falls back to
+  comparing by value when the identity check fails, guarded by a length
+  check so that the cost for non matching names is unchanged.
+
 Version 2.4.0
 -------------
 

docs/issues.rst

@@ -1124,3 +1124,63 @@ into an ordinary helper method that the hook calls, or into a
 through normal attribute access and therefore honour decorators applied
 via ``@wrapt.decorator``.
 
+
+
+Signature of PartialCallableObjectProxy over a bound method
+-----------------------------------------------------------
+
+``inspect.signature()`` applied to a ``PartialCallableObjectProxy``, or to
+the result of ``wrapt.partial()``, reports the signature of the wrapped
+callable with the bound positional and keyword arguments removed, in the
+same way as it does for ``functools.partial``. There is one case where
+this does not hold, which is when the callable being wrapped is itself an
+already bound method.
+
+::
+
+    import inspect
+    import functools
+    import wrapt
+
+    class Database:
+        def query(self, sql, *args, timeout=None):
+            pass
+
+    db = Database()
+
+    inspect.signature(functools.partial(db.query, "SELECT 1"))
+    # <Signature (*args, timeout=None)>
+
+    inspect.signature(wrapt.partial(db.query, "SELECT 1"))
+    # <Signature (sql, *args, timeout=None)>
+
+For the ``wrapt`` proxy the parameter filled by the bound argument is
+still present. This happens because ``inspect.signature()`` first checks
+whether the object it was given is an instance of ``types.MethodType``,
+before it looks for a ``__signature__`` attribute. An object proxy
+reports the class of the object it wraps, so for a proxy around a bound
+method that check succeeds. ``inspect`` then reads the ``__func__``
+attribute, which the proxy also forwards to the bound method, takes the
+signature of the underlying function, and removes only its first
+parameter. The ``__signature__`` attribute of the proxy, which would
+give the correct result, is never consulted.
+
+This cannot be corrected within ``wrapt``. Not reporting the class of the
+wrapped object would break the fundamental contract of an object proxy,
+and returning a different object from ``__func__`` would mislead the
+many other consumers of that attribute in order to satisfy one. The
+appropriate fix is for ``inspect`` to consult ``__signature__`` before
+relying on the class of the object.
+
+Partials over a plain function are unaffected, including the partial
+created by ``FunctionWrapper`` when a wrapped method is called via the
+class with the instance passed explicitly, since in that case the
+wrapped callable is the plain function and the instance is one of the
+bound arguments. Where the signature of a partial over a bound method is
+needed, pass the underlying function and the instance instead of the
+bound method.
+
+::
+
+    inspect.signature(wrapt.partial(Database.query, db, "SELECT 1"))
+    # <Signature (*args, timeout=None)>

src/wrapt-stubs/__init__.pyi

@@ -317,6 +317,10 @@ if sys.version_info >= (3, 10):
     # PartialCallableObjectProxy
 
     class PartialCallableObjectProxy(BaseObjectProxy[Callable[..., Any]]):
+        _self_args: tuple[Any, ...]
+        _self_kwargs: dict[str, Any]
+        @property
+        def __signature__(self) -> Signature: ...
         def __init__(
             self, func: Callable[..., Any], *args: Any, **kwargs: Any
         ) -> None: ...

src/wrapt/__init__.py

@@ -13,7 +13,7 @@ def _format_version(parts):
     )
 
 
-__version_info__ = ("2", "4", "0")
+__version_info__ = ("2", "4", "1")
 __version__ = _format_version(__version_info__)
 
 from .__wrapt__ import (