automodule does not work with TYPE_CHECKING guarded code

[LecrisUT]

Describe the bug

I want to document TypeAlias variables which are typically guarded by if TYPE_CHECKING or they might be defined in a stub file. The issue is that these members are not automatically added and indexed by automodule with members. If I move the section to outside the TYPE_CHECKING if-guard, then the member is being documented.

How to Reproduce

from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from typing import TypeAlias

    ComplexType: TypeAlias = int | str
    """This has some documentation"""

def some_func(input: ComplexType) -> None:
    """Some function that uses the type alias"""

Environment Information

Platform:              linux; (Linux-6.11.7-300.fc41.x86_64-x86_64-with-glibc2.40)
Python version:        3.13.0 (main, Oct  8 2024, 00:00:00) [GCC 14.2.1 20240912 (Red Hat 14.2.1-3)])
Python implementation: CPython
Sphinx version:        8.1.3
Docutils version:      0.21.2
Jinja2 version:        3.1.4
Pygments version:      2.18.0

Sphinx extensions

extensions = [
    "myst_parser",
    "sphinx.ext.intersphinx",
    "sphinx_tippy",
    "sphinx.ext.autodoc",
    "sphinx_autodoc_typehints",
]

Additional context

No response

[timhoffm]

This is to be expected: autodoc introspects the module by importing them. This is done in a regular python run, in which case typing.TYPE_CHECKING is False. Therefore, your TypeAlias definition is not executed and thus does not exist. Consequently autodoc cannot see it.

I've not tested it, but you could try to adding

import typing
typing.TYPE_CHECKING = True

to your Sphinx conf.py. That should make your alias visible, but be aware that it cancels the effect of the TYPE_CHECKING variable and the guards it has put in place not only for your code but also for all the downstream dependencies you import.

[LecrisUT]

I've tested it out a bit and it breaks on sphinx eources even, so it seems a more sophisticated solution is needed. Is it possible to interogate typing for what members it sees in __dict__, etc. and try to union the results?