From 46e1537373ed9c9f971cbc22c670c813d09c23a1 Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Tue, 6 Jun 2023 12:46:54 +0100 Subject: [PATCH 1/7] Document that PEP-604 unions do not support forward references as strings --- Doc/library/stdtypes.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index fdef5314b9a4ef..8c748b0f4b2bce 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5162,6 +5162,15 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. def square(number: int | float) -> int | float: return number ** 2 + .. note:: + + The object on both sides of the ``|`` operand must be an object that + defines the :meth:`~object.__or__` special method. As the :class:`str` + type does not define :meth:`!__or__`, the expression ``int | "Foo"``, + where ``"Foo"`` is a reference to a class not yet defined, will fail at + runtime. To annotate forward references using union-type expressions, + 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: From 53600ff050ad409bcb4c66cd7833becfed372cbc Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Tue, 6 Jun 2023 14:03:52 +0100 Subject: [PATCH 2/7] fiddle --- Doc/library/stdtypes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 8c748b0f4b2bce..57009a560c1299 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5165,8 +5165,8 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. .. note:: The object on both sides of the ``|`` operand must be an object that - defines the :meth:`~object.__or__` special method. As the :class:`str` - type does not define :meth:`!__or__`, the expression ``int | "Foo"``, + defines the :meth:`~object.__or__` special method. As instances of + :class:`str` do not support :meth:`!__or__`, the expression ``int | "Foo"``, where ``"Foo"`` is a reference to a class not yet defined, will fail at runtime. To annotate forward references using union-type expressions, present the whole expression as a string, e.g. ``"int | Foo"``. From 35e01ce78916e9ca14371a701c8fe0462fac9afa Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 7 Jun 2023 17:22:31 +0100 Subject: [PATCH 3/7] Be more hand-wavy --- Doc/library/stdtypes.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 57009a560c1299..4a57acf696dd17 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5164,10 +5164,9 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. .. note:: - The object on both sides of the ``|`` operand must be an object that - defines the :meth:`~object.__or__` special method. As instances of - :class:`str` do not support :meth:`!__or__`, the expression ``int | "Foo"``, - where ``"Foo"`` is a reference to a class not yet defined, will fail at + The ``|`` operand cannot be used 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. To annotate forward references using union-type expressions, present the whole expression as a string, e.g. ``"int | Foo"``. From 6fff9360c28ceb55da696f95eaf770f27c43853e Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 17:32:57 +0100 Subject: [PATCH 4/7] Update Doc/library/stdtypes.rst --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 4a57acf696dd17..01555cc48dc789 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5167,7 +5167,7 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. The ``|`` operand cannot be used 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. To annotate forward references using union-type expressions, + runtime. To annotate unions which include forward references, present the whole expression as a string, e.g. ``"int | Foo"``. .. describe:: union_object == other From 30049e5b40695aac5da231812d35b350f38ad8cd Mon Sep 17 00:00:00 2001 From: AlexWaygood Date: Wed, 7 Jun 2023 17:48:32 +0100 Subject: [PATCH 5/7] Clarify that this is only a runtime limitation --- Doc/library/stdtypes.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 01555cc48dc789..405397ad9c5650 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5164,11 +5164,11 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. .. note:: - The ``|`` operand cannot be used to define unions where one or more - members is a forward reference. For example, ``int | "Foo"``, where + 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. To annotate unions which include forward references, - present the whole expression as a string, e.g. ``"int | Foo"``. + runtime. To annotate unions which include forward references, present the + whole expression as a string, e.g. ``"int | Foo"``. .. describe:: union_object == other From e9feaf71b489e4d38bc1d919e7192507245d8832 Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 17:50:42 +0100 Subject: [PATCH 6/7] Update Doc/library/stdtypes.rst --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 405397ad9c5650..a94af329e92480 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5167,7 +5167,7 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. 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. To annotate unions which include forward references, present the + runtime. To define unions which include forward references, present the whole expression as a string, e.g. ``"int | Foo"``. .. describe:: union_object == other From c405a233f9ba82f12d0d56aee4636e8bfae465ca Mon Sep 17 00:00:00 2001 From: Alex Waygood Date: Wed, 7 Jun 2023 17:51:13 +0100 Subject: [PATCH 7/7] Update Doc/library/stdtypes.rst --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index a94af329e92480..0caa725f75e642 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -5167,7 +5167,7 @@ enables cleaner type hinting syntax compared to :data:`typing.Union`. 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. To define unions which include forward references, present the + runtime. For unions which include forward references, present the whole expression as a string, e.g. ``"int | Foo"``. .. describe:: union_object == other