Support Enum signatures in Python 3.12 and 3.13

Author: AA-Turner

sphinx/ext/autodoc/__init__.py

@@ -10,6 +10,7 @@
 import functools
 import operator
 import re
+import sys
 from inspect import Parameter, Signature
 from typing import TYPE_CHECKING, Any, NewType, TypeVar
 
@@ -1543,10 +1544,15 @@ def get_user_defined_function_or_method(obj: Any, attr: str) -> Any:
         # This sequence is copied from inspect._signature_from_callable.
         # ValueError means that no signature could be found, so we keep going.
 
-        # First, we check the obj has a __signature__ attribute
-        if (hasattr(self.object, '__signature__') and
-                isinstance(self.object.__signature__, Signature)):
-            return None, None, self.object.__signature__
+        # First, we check if obj has a __signature__ attribute
+        if hasattr(self.object, '__signature__'):
+            object_sig = self.object.__signature__
+            if isinstance(object_sig, Signature):
+                return None, None, object_sig
+            if sys.version_info[:2] in {(3, 12), (3, 13)} and callable(object_sig):
+                # Support for enum.Enum.__signature__ in Python 3.12
+                if isinstance(object_sig_str := object_sig(), str):
+                    return None, None, inspect.signature_from_str(object_sig_str)
 
         # Next, let's see if it has an overloaded __call__ defined
         # in its metaclass

tests/test_extensions/test_ext_autodoc.py

@@ -1562,7 +1562,7 @@ def preamble_lookup(
             doc
         ), f'enumeration class {self.target!r} should have an explicit docstring'
 
-        args = self._preamble_args()
+        args = self._preamble_args(functional_constructor=False)
         return self._preamble(doc=doc, args=args, indent=indent, **options)
 
     def preamble_constructor(
@@ -1572,7 +1572,7 @@ def preamble_constructor(
             doc
         ), f'enumeration class {self.target!r} should have an explicit docstring'
 
-        args = self._preamble_args()
+        args = self._preamble_args(functional_constructor=True)
         return self._preamble(doc=doc, args=args, indent=indent, **options)
 
     def _preamble(
@@ -1582,12 +1582,25 @@ def _preamble(
         return self._node('class', self.name, doc, args=args, indent=indent, **options)
 
     @staticmethod
-    def _preamble_args():
+    def _preamble_args(functional_constructor: bool = False):
         """EnumType.__call__() is a dual-purpose method:
 
         * Look an enum member (valid only if the enum has members)
         * Create a new enum class (functional API)
         """
+        if sys.version_info[:2] >= (3, 13) or sys.version_info[:3] >= (3, 12, 3):
+            if functional_constructor:
+                return (
+                    '(new_class_name, /, names, *, module=None, '
+                    'qualname=None, type=None, start=1, boundary=None)'
+                )
+            else:
+                return '(*values)'
+        if sys.version_info[:2] >= (3, 12):
+            return (
+                '(value, names=None, *values, module=None, '
+                'qualname=None, type=None, start=1, boundary=None)'
+            )
         return '(value)'
 
     def method(