Forward reference does not work when using union type operator in type alias

[maxvfischer]

Bug report

Bug description:

When creating a type alias, it seems like forward referencing does not work as expected when using union type operator.

This works fine

from typing import Union
ABC = dict[str, Union[list[str], "ABC"]]

But this does not

ABC = dict[str, list[str] | "ABC"]

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unsupported operand type(s) for |: 'types.GenericAlias' and 'str'

On python:3.14, I also tried to use the new PEP 649:

ABC = dict[str, list[str] | ABC]

Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    ABC = dict[str, list[str] | ABC]
                                ^^^
NameError: name 'ABC' is not defined

This is the same when using Union

from typing import Union
ABC = dict[str, Union[list[str], ABC]]

NameError: name 'ABC' is not defined

CPython versions tested on:

3.11, 3.12, 3.13, 3.14

Operating systems tested on:

macOS

[AlexWaygood]

Hi! Everything here is behaving as expected. We state in the docs for UnionType:

Note: The | operand cannot be used at runtime to define unions where one or more members is a forward reference. For example, int | "Foo", where "Foo" is a reference to a class not yet defined, will fail at runtime. For unions which include forward references, present the whole expression as a string, e.g. "int | Foo".

With regards to your later comment:

On python:3.14, I also tried to use the new PEP 649:

If you're able to use newer versions of Python, you can use the new type statement, introduced in Python 3.12, which is also lazily evaluated, and therefore allows you to define recursive type aliases natively without any strings:

>>> type ABC = dict[str, list[str] | ABC]
>>> ABC.__value__
dict[str, list[str] | ABC]

[maxvfischer]

Everything here is behaving as expected.

Ahh sorry, should've read the docs more carefully. Thanks for the pointer 🙏