sphinx.ext.autodoc: Broken Python 3.14 forward references support (original) (raw)

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