How to add tooltip/docstring to a TypeAlias variable that is declared within if TYPE_CHECKING?

[Daraan]

The situation is I have a vector class Foo that is generic and I use Foo(Generic[T]) in a stub file.
Using Foo[T] at runtime is not possible and will raise and TypeError hence I have to do:

from mod import Foo
from typing import TYPE_CHECKING, TypeVar, TypeAlias

T = TypeVar("T")

if TYPE_CHECKING:
   FooList : TypeAlias = Foo[T] | List[T]
   """Short doc of FooList"""
else:
   FooList: TypeAlias = Foo | List[T]  # at runtime cannot add a type to Foo
   """Short doc of FooList"""

x : FooList # <-- has no doc tooltip

In non TypeAlias cases I can hack around it with a redefinition, or using a

Example: Any
"""Short doc of Example"""

if TYPE_CHECKING
   Example = .... # correct typing
else:
  # runtime behavior

However doing this will result in a Variable not allowed in type expression from pyright.

How can I address this, and is this something that pylance could implement to integrate docstring from such always-true guarded if-clauses?

[Daraan]

What I came up with so far is to hack it with TypeAliasType during runtime:

if TYPE_CHECKING:
    _GenericFoo = Foo[_A]
else:
    _GenericFoo = TypeAliasType("_GenericFoo", Foo, type_params=(_A,))

FooList : TypeAlias = Union[_GenericFoo[_A], Sequence[_A]]
"""doc for FooList"""

[erictraut]

There is no formally accepted specification for attribute docstrings. The closest thing is PEP 258, which was submitted for consideration but ultimately rejected. This is the spec I used when implementing support for attribute docstrings in pyright. This PEP clearly states that string literals should be considered docstrings only if they're at the top level of a module or class definition, not within a conditional block. That makes sense if you think about it.

There have been several attempts over the past few years to formally specify ways to add docstrings to attributes and type aliases, but these attempts have faltered.

If you'd like to propose a standard in this area, the Python Ideas forum is probably a good place to propose your idea. If you can get community consensus around an idea — and especially if you can get it standardized, then pyright / pylance will likely implement your idea.

I like the suggestion by @Daraan. That's the workaround I'd use in this case.