Skip to content

Regression: TypeAliasForwardRef is not resolved when it apears inside of typing constructs #14003

@taminomara

Description

@taminomara

Describe the bug

When autodoc is applied to a function with type annotations that have type aliases inside of typing constructs, the signature is rendered as incorrectly.

Issue originally reported in #10333, then fixed in #10353, then re-introduced in 423452c.

An easy fix is to revert 423452c. However, 423452c was made for some reason; my guess is it was because implementation of __repr__ from #10353 was hindering debugging, or hiding some other problem. So, if we want to keep current implementation of __repr__, we'll need to add a check for TypeAliasForwardRef to stringify_annotation (probably after this branch). Note that this will create a circular dependency between sphinx.util.typing and sphinx.util.inspect.

How to Reproduce

Example: when autodoc renders function test from this code:

from __future__ import annotations
from typing import *

Alias: TypeAlias = int

def test() -> list[Alias]: ...

if Alias appears in autodoc_type_aliases, the resulting signature will contain TypeAliasForwardRef('Alias') | None instead of Alias | None.

Environment Information

Platform:              linux; (Linux-6.6.87.2-microsoft-standard-WSL2-x86_64-with-glibc2.39)
Python version:        3.13.8 (main, Oct 12 2025, 16:57:39) [GCC 13.3.0])
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

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