sphinx-autodoc-pytest-fixtures: Resolve TypeAlias names in fixture return types

[tony]

Problem

Fixtures whose return type is a TypeAlias showed the expanded underlying type in the fixture summary table rather than the alias name. For example, a fixture annotated -> UnihanTestOptions (where UnihanTestOptions: TypeAlias = Options | Mapping[str, Any]) rendered as Options | Mapping[str, Any] instead of UnihanTestOptions.

Three bugs compounded.

get_type_hints() silently expands TypeAlias names. _get_return_annotation calls get_type_hints(), which resolves the annotation string "UnihanTestOptions" against the module namespace and returns the underlying union type — losing the alias name entirely before _qualify_forward_ref ever runs.

Fast path in _qualify_forward_ref returns the alias value's identity, not the alias name. When a TypeAlias is defined at module level, getattr(mod, name) returns the alias value (e.g. the union type, whose __qualname__ is "Union"). The fast path then returned "typing.Union" instead of "module.AliasName".

_qualify_forward_ref only scanned if TYPE_CHECKING: blocks for ImportFrom nodes. TypeAlias definitions — whether inside a TYPE_CHECKING guard (Name: TypeAlias = ...) or at module level — were not handled.

Solution

_get_return_annotation: after get_type_hints() succeeds, check whether the raw annotation was a bare identifier that resolved to a non-class type (union, generic alias). If so, return the raw string instead of the expanded type. The discriminator is isinstance(ret, type): real classes (including import-aliased ones) return True; union/generic TypeAlias expansions return False.

_qualify_forward_ref fast path: guard the fast path so it only fires when obj.__qualname__ == name. TypeAlias values have __qualname__ == "Union", so they no longer steal the cross-reference.

_qualify_forward_ref slow path: add _is_type_alias_annotation() to recognise TypeAlias and t.TypeAlias/typing.TypeAlias annotation forms. Extend the AST scan to handle two new cases: Name: TypeAlias = ... inside a TYPE_CHECKING block (Case 2), and Name: TypeAlias = ... at module level (Case 3). TYPE_CHECKING ImportFrom still takes priority when the same name appears in both locations.

Test plan

• All 18 unit tests in test_type_checking_alias.py pass, covering: bare vs attribute TypeAlias form, TYPE_CHECKING vs module-level placement, non-alias AnnAssign ignored, import-wins-over-alias priority, fast-path TypeAlias value guard, import-aliased class still resolves to the class
• Full suite passes with no regressions

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.77419% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.87%. Comparing base (3a3e8fb) to head (6e5b5fe).

Files with missing lines	Patch %	Lines
...ocutils/src/sphinx_autodoc_docutils/_documenter.py	0.00%	2 Missing ⚠️
scripts/ci/package_tools.py	75.00%	2 Missing ⚠️
...hinx-argparse-neo/src/sphinx_argparse_neo/nodes.py	0.00%	1 Missing ⚠️
...ext/pytest_fixtures/test_sphinx_pytest_fixtures.py	50.00%	1 Missing ⚠️
...ts/ext/pytest_fixtures/test_type_checking_alias.py	99.40%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main       #9      +/-   ##
==========================================
+ Coverage   88.59%   88.87%   +0.27%     
==========================================
  Files          71       72       +1     
  Lines        6955     7107     +152     
==========================================
+ Hits         6162     6316     +154     
+ Misses        793      791       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.