gh-91002: Support __annotate__ for functools.partial and functools.partialmethod

Doc/library/annotationlib.rst

@@ -383,6 +383,10 @@ Functions
      doesn't have its own annotations dict, returns an empty dict.
    * All accesses to object members and dict values are done
      using ``getattr()`` and ``dict.get()`` for safety.
+   * Supports objects that provide their own :attr:`~object.__annotate__` descriptor,
+     such as :class:`functools.partial` and :class:`functools.partialmethod`.
+     See the :mod:`functools` module documentation for details on how these
+     objects support annotations.
 
    *eval_str* controls whether or not values of type :class:`!str` are
    replaced with the result of calling :func:`eval` on those values:
@@ -404,10 +408,12 @@ Functions
      ``sys.modules[obj.__module__].__dict__`` and *locals* defaults
      to the *obj* class namespace.
    * If *obj* is a callable, *globals* defaults to
-     :attr:`obj.__globals__ <function.__globals__>`,
-     although if *obj* is a wrapped function (using
-     :func:`functools.update_wrapper`) or a :class:`functools.partial` object,
-     it is unwrapped until a non-wrapped function is found.
+     :attr:`obj.__globals__ <function.__globals__>`.
+     If *obj* has a ``__wrapped__`` attribute (such as functions
+     decorated with :func:`functools.update_wrapper`), or if it is a
+     :class:`functools.partial` object, it is unwrapped by following the
+     ``__wrapped__`` attribute or :attr:`~functools.partial.func` attribute
+     repeatedly to find the underlying wrapped function's globals.
 
    Calling :func:`!get_annotations` is best practice for accessing the
    annotations dict of any object. See :ref:`annotations-howto` for
@@ -436,6 +442,36 @@ Functions
 
    .. versionadded:: 3.14
 
+.. _support-annotations-custom-objects:
+
+Supporting annotations in custom objects
+-------------------------------------------
+
+Objects can support annotation introspection by implementing the :attr:`~object.__annotate__`
+protocol. When an object's class provides an :attr:`!__annotate__` descriptor, :func:`get_annotations`
+will call it to retrieve the annotations for that object. The :attr:`!__annotate__` function
+should accept a single argument, a member of the :class:`Format` enum, and return a dictionary
+mapping annotation names to their values in the requested format.
+
+This mechanism allows objects to dynamically compute their annotations based on their state.
+For example, :class:`functools.partial` and :class:`functools.partialmethod` objects use
+:attr:`!__annotate__` to provide annotations that reflect only the unbound parameters,
+excluding parameters that have been filled by the partial application. See the
+:mod:`functools` module documentation for details on how these specific objects handle
+annotations.
+
+Other examples of objects that implement :attr:`!__annotate__` include:
+
+* :class:`typing.TypedDict` classes created through the functional syntax
+* Generic classes and functions with type parameters
+
+When implementing :attr:`!__annotate__` for custom objects, the function should handle
+all three primary formats (:attr:`~Format.VALUE`, :attr:`~Format.FORWARDREF`, and
+:attr:`~Format.STRING`) by either returning appropriate values or raising
+:exc:`NotImplementedError` to fall back to default behavior. Helper functions like
+:func:`annotations_to_string` and :func:`call_annotate_function` can assist with
+implementing format support.
+
 
 Recipes
 -------

Doc/library/functools.rst

@@ -828,3 +828,94 @@ have three read-only attributes:
 callable, weak referenceable, and can have attributes.  There are some important
 differences.  For instance, the :attr:`~definition.__name__` and :attr:`~definition.__doc__` attributes
 are not created automatically.
+
+Annotation support
+^^^^^^^^^^^^^^^^^^
+
+:class:`partial` and :class:`partialmethod` objects support the :attr:`~object.__annotate__` protocol for
+annotation introspection. This allows tools like :func:`annotationlib.get_annotations` to retrieve
+annotations that accurately reflect the signature of the partial or partialmethod object.
+
+For :class:`partial` objects, :func:`annotationlib.get_annotations` returns only the annotations
+for parameters that have not been bound by the partial application, along with the return annotation
+if present. Positional arguments bind to parameters in order, and the annotations for those parameters
+are excluded from the result:
+
+.. doctest::
+
+   >>> from functools import partial
+   >>> from annotationlib import get_annotations
+   >>> def func(a: int, b: str, c: float) -> bool:
+   ...     return True
+   >>> partial_func = partial(func, 1)  # Binds 'a'
+   >>> get_annotations(partial_func)
+   {'b': <class 'str'>, 'c': <class 'float'>, 'return': <class 'bool'>}
+
+Keyword arguments in :class:`partial` set default values but do not remove parameters from the
+signature, so their annotations are retained:
+
+.. doctest::
+
+   >>> partial_func_kw = partial(func, b="hello")  # Sets default for 'b'
+   >>> get_annotations(partial_func_kw)
+   {'a': <class 'int'>, 'b': <class 'str'>, 'c': <class 'float'>, 'return': <class 'bool'>}
+
+For :class:`partialmethod` objects accessed through a class (unbound), the first parameter
+(usually ``self`` or ``cls``) is preserved, and subsequent parameters are handled similarly
+to :class:`partial`:
+
+.. doctest::
+
+   >>> from functools import partialmethod
+   >>> class MyClass:
+   ...     def method(self, a: int, b: str) -> bool:
+   ...         return True
+   ...     partial_method = partialmethod(method, 1)  # Binds 'a'
+   >>> get_annotations(MyClass.partial_method)
+   {'b': <class 'str'>, 'return': <class 'bool'>}
+
+When a :class:`partialmethod` is accessed through an instance (bound), it becomes a
+:class:`partial` object and is handled accordingly:
+
+.. doctest::
+
+   >>> obj = MyClass()
+   >>> get_annotations(obj.partial_method)  # Same as above, 'self' is also bound
+   {'b': <class 'str'>, 'return': <class 'bool'>}
+
+This behavior ensures that :func:`annotationlib.get_annotations` returns annotations that
+accurately reflect the signature of the partial or partialmethod object, as determined by
+:func:`inspect.signature`.
+
+If :func:`annotationlib.get_annotations` cannot reliably determine which parameters are bound
+(for example, if :func:`inspect.signature` raises an error), it will raise a :exc:`TypeError`
+rather than returning incorrect annotations. This ensures that you either get correct annotations
+or a clear error, never incorrect annotations:
+
+.. doctest::
+
+   >>> from functools import partial
+   >>> import inspect
+   >>> def func(a: int, b: str) -> bool:
+   ...     return True
+   >>> partial_func = partial(func, 1)
+   >>> # Simulate a case where signature inspection fails
+   >>> original_sig = inspect.signature
+   >>> def broken_signature(obj):
+   ...     if isinstance(obj, partial):
+   ...         raise ValueError("Cannot inspect signature")
+   ...     return original_sig(obj)
+   >>> inspect.signature = broken_signature
+   >>> try:
+   ...     get_annotations(partial_func)
+   ... except TypeError as e:
+   ...     print(f"Got expected error: {e}")
+   ... finally:
+   ...     inspect.signature = original_sig
+   Got expected error: Cannot compute annotations for ...: unable to determine signature
+
+This design prevents the common error of returning annotations that include parameters which
+have already been bound by the partial application.
+
+.. versionadded:: next
+   Added :attr:`~object.__annotate__` support to :class:`partial` and :class:`partialmethod`.

Lib/functools.py

@@ -365,6 +365,152 @@ def _partial_repr(self):
     args.extend(f"{k}={v!r}" for k, v in self.keywords.items())
     return f"{module}.{qualname}({', '.join(args)})"
 
+
+################################################################################
+### _partial_annotate() - compute annotations for partial objects
+################################################################################
+
+def _partial_annotate(partial_obj, format):
+    """Helper function to compute annotations for a partial object.
+
+    This is called by the __annotate__ descriptor defined in C.
+    Returns annotations for the wrapped function, but only for parameters
+    that haven't been bound by the partial application.
+    """
+    import inspect
+    from annotationlib import get_annotations
+
+    # Get annotations from the wrapped function
+    func_annotations = get_annotations(partial_obj.func, format=format)
+
+    if not func_annotations:
+        return {}
+
+    # Get the signature to determine which parameters are bound
+    try:
+        sig = inspect.signature(partial_obj, annotation_format=format)
+    except (ValueError, TypeError) as e:
+        # If we can't get signature, we can't reliably determine which
+        # parameters are bound. Raise an error rather than returning
+        # incorrect annotations.
+        raise TypeError(
+            f"Cannot compute annotations for {partial_obj!r}: "
+            f"unable to determine signature"
+        ) from e
+
+    # Build new annotations dict with only unbound parameters
+    # (parameters first, then return)
+    new_annotations = {}
+
+    # Only include annotations for parameters that still exist in partial's signature
+    for param_name in sig.parameters:
+        if param_name in func_annotations:
+            new_annotations[param_name] = func_annotations[param_name]
+
+    # Add return annotation at the end
+    if 'return' in func_annotations:
+        new_annotations['return'] = func_annotations['return']
+
+    return new_annotations
+
+
+################################################################################
+### _partialmethod_annotate() - compute annotations for partialmethod objects
+################################################################################
+
+def _partialmethod_annotate(partialmethod_obj, format):
+    """Helper function to compute annotations for a partialmethod object.
+
+    This is called when accessing annotations on an unbound partialmethod
+    (via the __partialmethod__ attribute).
+    Returns annotations for the wrapped function, but only for parameters
+    that haven't been bound by the partial application. The first parameter
+    (usually 'self' or 'cls') is kept since partialmethod is unbound.
+    """
+    import inspect
+    from annotationlib import get_annotations
+
+    # Get annotations from the wrapped function
+    func_annotations = get_annotations(partialmethod_obj.func, format=format)
+
+    if not func_annotations:
+        return {}
+
+    # For partialmethod, we need to simulate the signature calculation
+    # The first parameter (self/cls) should remain, but bound args should be removed
+    try:
+        # Get the function signature
+        func_sig = inspect.signature(partialmethod_obj.func, annotation_format=format)
+        func_params = list(func_sig.parameters.keys())
+
+        if not func_params:
+            return func_annotations
+
+        # Calculate which parameters are bound by the partialmethod
+        partial_args = partialmethod_obj.args or ()
+        partial_keywords = partialmethod_obj.keywords or {}
+
+        # Build new annotations dict in proper order
+        # (parameters first, then return)
+        new_annotations = {}
+
+        # The first parameter (self/cls) is always kept for unbound partialmethod
+        first_param = func_params[0]
+        if first_param in func_annotations:
+            new_annotations[first_param] = func_annotations[first_param]
+
+        # For partialmethod, positional args bind to parameters AFTER the first one
+        # So if func is (self, a, b, c) and partialmethod.args=(1,)
+        # Then 'self' stays, 'a' is bound, 'b' and 'c' remain
+
+        # We need to account for Placeholders which create "holes"
+        # For example: partialmethod(func, 1, Placeholder, 3) binds 'a' and 'c' but not 'b'
+
+        remaining_params = func_params[1:]
+
+        # Track which positions are filled by Placeholder
+        placeholder_positions = set()
+        for i, arg in enumerate(partial_args):
+            if arg is Placeholder:
+                placeholder_positions.add(i)
+
+        # Number of non-Placeholder positional args
+        # This doesn't directly tell us which params are bound due to Placeholders
+
+        for i, param_name in enumerate(remaining_params):
+            # Check if this position has a Placeholder
+            if i in placeholder_positions:
+                # This parameter is deferred by Placeholder, keep it
+                if param_name in func_annotations:
+                    new_annotations[param_name] = func_annotations[param_name]
+                continue
+
+            # Check if this position is beyond the partial_args
+            if i >= len(partial_args):
+                # This parameter is not bound at all, keep it
+                if param_name in func_annotations:
+                    new_annotations[param_name] = func_annotations[param_name]
+                continue
+
+            # Otherwise, this position is bound (not a Placeholder and within bounds)
+            # Skip it
+
+        # Add return annotation at the end
+        if 'return' in func_annotations:
+            new_annotations['return'] = func_annotations['return']
+
+        return new_annotations
+
+    except (ValueError, TypeError) as e:
+        # If we can't process the signature, we can't reliably determine
+        # which parameters are bound. Raise an error rather than returning
+        # incorrect annotations (which would include bound parameters).
+        raise TypeError(
+            f"Cannot compute annotations for {partialmethod_obj!r}: "
+            f"unable to determine which parameters are bound"
+        ) from e
+
+
 # Purely functional, no descriptor behaviour
 class partial:
     """New function with partial application of the given arguments
@@ -467,6 +613,8 @@ def _method(cls_or_self, /, *args, **keywords):
             return self.func(cls_or_self, *pto_args, *args, **keywords)
         _method.__isabstractmethod__ = self.__isabstractmethod__
         _method.__partialmethod__ = self
+        # Set __annotate__ to delegate to the partialmethod's __annotate__
+        _method.__annotate__ = self.__annotate__
         return _method
 
     def __get__(self, obj, cls=None):
@@ -492,6 +640,8 @@ def __get__(self, obj, cls=None):
     def __isabstractmethod__(self):
         return getattr(self.func, "__isabstractmethod__", False)
 
+    __annotate__  =  _partialmethod_annotate
+
     __class_getitem__ = classmethod(GenericAlias)