From: Alex Waygood <Alex.Waygood@Gmail.com>
Date: Wed, 7 Jun 2023 17:26:23 +0000 (+0100)
Subject: gh-90015: Document that PEP-604 unions do not support forward references (#105366)
X-Git-Tag: v3.13.0a1~1844
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=fbdee000de47ae96fbf53ce8908e8efbb23cfba4;p=thirdparty%2FPython%2Fcpython.git

gh-90015: Document that PEP-604 unions do not support forward references (#105366)
---

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index fdef5314b9a4..0caa725f75e6 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -5162,6 +5162,14 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`.
       def square(number: int | float) -> int | float:
           return number ** 2
 
+   .. 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"``.
+
 .. describe:: union_object == other
 
    Union objects can be tested for equality with other union objects.  Details: