-
-
Notifications
You must be signed in to change notification settings - Fork 2.3k
Open
Labels
Description
Describe the bug
Currently, sphinx.ext.autodoc does not support Python 3.14 annotations, giving failures such as:
Traceback
=========
File "/home/rui/pygaindalf/app/components/agents/base.py", line 46, in __annotate__
def portfolio(self) -> PortfolioProtocol:
^^^^^^^^^^^^^^^^^
NameError: name 'PortfolioProtocol' is not defined
(From pygaindalf)
Using from __future__ import annotations
works around this issue, however from Python 3.14 onwards that should not be necessary.
Fixing this seems to be simple, which is to use annotationlib.Format.FORWARDREF
format in all inspect.signature
calls.
The following monkey patch (see pygaindalf's conf.py) works around the issues I am seeing, by making that the default:
import annotationlib
import functools
import inspect
# sphinx.ext.autodoc
inspect_signature = inspect.signature
@functools.wraps(inspect.signature)
def patched_inspect_signature(*args, **kwargs):
if "annotation_format" not in kwargs:
kwargs["annotation_format"] = annotationlib.Format.FORWARDREF
return inspect_signature(*args, **kwargs)
inspect.signature = patched_inspect_signature
How to Reproduce
Use an unresolved forward reference in Python 3.14 and run sphinx autodoc.
For a real-life example, you can check out pygaindalf and remove the monkey patch in conf.py.
Environment Information
Platform: linux; (Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.42)
Python version: 3.14.0 (main, Oct 7 2025, 15:35:21) [Clang 20.1.4 ])
Python implementation: CPython
Sphinx version: 8.2.3
Docutils version: 0.21.2
Jinja2 version: 3.1.6
Pygments version: 2.19.2
Sphinx extensions
Reproducible with only sphinx.ext.autodoc
.
Additional context
No response