gh-89263: Add typing.get_overloads

Doc/library/typing.rst

@@ -2254,6 +2254,32 @@ Functions and decorators
 
    See :pep:`484` for details and comparison with other typing semantics.
 
+   .. versionchanged:: 3.11
+      Overloaded functions can now be introspected at runtime using :func:`get_overloads`.
+
+
+.. function:: get_overloads(func)
+
+   Return a sequence of :func:`@overload <overload>`-decorated definitions for *func*. *func* is
+   the function object for the implementation of the overloaded function.
+   For example, given the definition of ``process`` in the documentation for
+   :func:`@overload <overload>`, ``get_overloads(process)`` will return a sequence of three
+   function objects for the three defined overloads.
+
+   This function can be used for introspecting an overloaded function at runtime.
+
+   .. versionadded:: 3.11
+
+
+.. function:: clear_overloads(func=None)
+
+   Clear all registered overloads for the given *func*. If *func* is None, clear
+   all overloads stored in the internal registry. This can be used to reclaim the
+   memory used by the registry.
+
+   .. versionadded:: 3.11
+
+
 .. decorator:: final
 
    A decorator to indicate to type checkers that the decorated method

Lib/test/test_typing.py

@@ -10,6 +10,7 @@
 from copy import copy, deepcopy
 
 from typing import Any, NoReturn, Never, assert_never
+from typing import overload, get_overloads, clear_overloads
 from typing import TypeVar, TypeVarTuple, Unpack, AnyStr
 from typing import T, KT, VT  # Not in __all__.
 from typing import Union, Optional, Literal
@@ -3794,11 +3795,22 @@ def test_or(self):
         self.assertEqual("x" | X, Union["x", X])
 
 
+@lru_cache()
+def cached_func(x, y):
+    return 3 * x + y
+
+
+class MethodHolder:
+    @classmethod
+    def clsmethod(cls): ...
+    @staticmethod
+    def stmethod(): ...
+    def method(self): ...
+
+
 class OverloadTests(BaseTestCase):
 
     def test_overload_fails(self):
-        from typing import overload
-
         with self.assertRaises(RuntimeError):
 
             @overload
@@ -3808,8 +3820,6 @@ def blah():
             blah()
 
     def test_overload_succeeds(self):
-        from typing import overload
-
         @overload
         def blah():
             pass
@@ -3819,6 +3829,65 @@ def blah():
 
         blah()
 
+    def set_up_overloads(self):
+        def blah():
+            pass
+
+        overload1 = blah
+        overload(blah)
+
+        def blah():
+            pass
+
+        overload2 = blah
+        overload(blah)
+
+        def blah():
+            pass
+
+        return blah, [overload1, overload2]
+
+    def test_overload_registry(self):
+        impl, overloads = self.set_up_overloads()
+
+        self.assertEqual(list(get_overloads(impl)), overloads)
+        clear_overloads(impl)
+        self.assertEqual(get_overloads(impl), [])
+
+        impl, overloads = self.set_up_overloads()
+
+        self.assertEqual(list(get_overloads(impl)), overloads)
+        clear_overloads()
+        self.assertEqual(get_overloads(impl), [])
+
+    def test_overload_registry_repeated(self):
+        for _ in range(2):
+            impl, overloads = self.set_up_overloads()
+
+            self.assertEqual(list(get_overloads(impl)), overloads)
+
+    def test_get_key_for_callable(self):
+        self.assertEqual(
+            typing._get_key_for_callable(len),
+            "builtins.len",
+        )
+        self.assertEqual(
+            typing._get_key_for_callable(cached_func),
+            f"{__name__}.cached_func",
+        )
+        self.assertEqual(
+            typing._get_key_for_callable(MethodHolder.clsmethod),
+            f"{__name__}.MethodHolder.clsmethod",
+        )
+        self.assertEqual(
+            typing._get_key_for_callable(MethodHolder.stmethod),
+            f"{__name__}.MethodHolder.stmethod",
+        )
+        self.assertEqual(
+            typing._get_key_for_callable(MethodHolder.method),
+            f"{__name__}.MethodHolder.method",
+        )
+
 
 # Definitions needed for features introduced in Python 3.6
 

Lib/typing.py

@@ -121,9 +121,11 @@ def _idfunc(_, x):
     'assert_type',
     'assert_never',
     'cast',
+    'clear_overloads',
     'final',
     'get_args',
     'get_origin',
+    'get_overloads',
     'get_type_hints',
     'is_typeddict',
     'Never',
@@ -2412,10 +2414,76 @@ def utf8(value: bytes) -> bytes: ...
       def utf8(value: str) -> bytes: ...
       def utf8(value):
           # implementation goes here
+
+    The overloads for a function can be retrieved at runtime using the
+    get_overloads() function.
     """
+    try:
+        key = _get_key_for_callable(func)
+    except TypeError:
+        # Not a normal function; ignore.
+        pass
+    else:
+        # We're inlining get_overloads() here to avoid computing the key twice.
+        existing = _overload_registry.setdefault(key, [])
+        if existing:
+            # If we are registering a variant with a lineno below or equal to that of the
+            # most recent existing variant, we're probably re-creating overloads for a
+            # function that already exists. In that case, we clear the existing variants
+            # to avoid leaking memory.
+            firstlineno = _get_firstlineno(func)
+            if firstlineno is not None:
+                existing_lineno = _get_firstlineno(existing[-1])
+                if existing_lineno is not None and firstlineno <= existing_lineno:
+                    existing.clear()
+
+        existing.append(func)
     return _overload_dummy
 
 
+def _get_firstlineno(func):
+    # staticmethod, classmethod
+    func = getattr(func, "__func__", func)
+    if not hasattr(func, '__code__'):
+        return None
+    return func.__code__.co_firstlineno
+
+
+# {key: [overload]}
+_overload_registry = {}
+
+
+def get_overloads(func):
+    """Return all defined overloads for *func* as a sequence."""
+    key = _get_key_for_callable(func)
+    return _overload_registry.get(key, [])
+
+
+def clear_overloads(func=None):
+    """Clear all overloads for the given function (or all functions)."""
+    if func is None:
+        _overload_registry.clear()
+    else:
+        key = _get_key_for_callable(func)
+        _overload_registry.pop(key, None)
+
+
+def _get_key_for_callable(func):
+    """Return a key for the given callable.
+
+    This is used as a key in the overload registry.
+
+    If no key can be created (because the object is not of a supported type), raise
+    AttributeError.
+    """
+    # classmethod and staticmethod
+    func = getattr(func, "__func__", func)
+    try:
+        return f"{func.__module__}.{func.__qualname__}"
+    except AttributeError:
+        raise TypeError(f"Cannot create key for {func!r}") from None
+
+
 def final(f):
     """A decorator to indicate final methods and final classes.
 

Misc/NEWS.d/next/Library/2022-03-06-18-15-32.bpo-45100.B_lHu0.rst

@@ -0,0 +1,2 @@
+Add :func:`typing.get_overloads` and :func:`typing.clear_overloads`.
+Patch by Jelle Zijlstra.