Skip to content

sphinx.ext.autodoc: Broken Python 3.14 forward references support #13945

@ruipin

Description

@ruipin

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions