bpo-46120: State that `|` is preferred over `Union` #30222

sobolevn · 2021-12-21T09:47:07Z

Originally discussed in https://mail.python.org/archives/list/[email protected]/thread/TW5M6XDN7DO346RXMADKBAAGNSZPC4ZQ/

CC @Fidget-Spinner

https://bugs.python.org/issue46120

Doc/library/typing.rst

Misc/NEWS.d/next/Documentation/2021-12-21-12-45-57.bpo-46120.PE0DmJ.rst

Fidget-Spinner

Thanks Nikita!

Fidget-Spinner · 2021-12-21T10:01:06Z

Doc/library/typing.rst

@@ -661,6 +664,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
   Optional type.

   ``Optional[X]`` is equivalent to ``X | None`` (or ``Union[X, None]``).
+   ``X | None`` is prefered in readability in most cases.


I think Optional was still being debated. Should we leave it out for now?

My opinion is that X | None is better than Optional:

It does not create a separate concept. It is just a union with None

It does not "look" like "optional argument" to some users

But, this is not a strong opinion. So, I can do both 🙂

I also prefer X | None over Optional

Optional is also more problematic than Union, because it's a constant cause for confusion.

You could frame this to avoid adding too much opinion:

``X | None`` is equivalent to ``Optional[X]`` and ``Union[X, None]``.

patrick91 · 2021-12-21T12:12:25Z

Doc/library/typing.rst


   * The arguments must be types and there must be at least one.

   * Unions of unions are flattened, e.g.::

-       Union[Union[int, str], float] == Union[int, str, float]
+       Union[Union[int, str], float] == int | str | float


I wonder if this might be confusing, we are using the two styles here for unions 🤔

could we do something like:

IntOrStr = int | str IntOrStr | float == int | str | float

?

Good idea. But, I guess we cannot completely remove Union[Union[]] example, because it is important as well. Maybe we can show both?

why not :) hopefully it doesn’t get too verbose though

patrick91 · 2021-12-21T12:14:40Z

Doc/library/typing.rst


-   To define a union, use e.g. ``Union[int, str]`` or the shorthand ``int | str``.  Details:
+   To define a union, use e.g. ``int | str`` or the older version ``Union[int, str]``.


is it worth mentioning that Union and | behave a bit differently when used at runtime?

>>> type(Union[str, int]) <class 'typing._UnionGenericAlias'> >>> type(str | int) <class 'types.UnionType'>

I can add a link to https://docs.python.org/3/library/stdtypes.html#union-type

yes, I think that works ☺️

While they're technically equivalent (and will evaluate as equal), they're not identical. Would it be worth hinting at this by saying they're logically equivalent?

gpshead · 2021-12-22T18:16:31Z

Doc/library/typing.rst


-   To define a union, use e.g. ``Union[int, str]`` or the shorthand ``int | str``.  Details:
+   There's also an older version ``Union[int, str]``.
+   Note that the ``X | Y`` is preferred in readability in most cases.


wording: "is preferred for readability" using "for" not "in". (same in the NEWS entry)

pbryan · 2021-12-22T18:23:08Z

Doc/library/typing.rst

@@ -660,7 +667,8 @@ These can be used as types in annotations using ``[]``, each having a unique syn

   Optional type.

-   ``Optional[X]`` is equivalent to ``X | None`` (or ``Union[X, None]``).
+   ``Optional[X]`` is logically equivalent to ``X | None`` and ``Union[X, None]``.


Minor suggestion:

``X | None`` is logically equivalent to ``Optional[X]`` and ``Union[X, None]``.

I prefer "semantically equivalent" to "logically equivalent" 😉

Even better.

gpshead · 2021-12-22T18:22:56Z

Doc/library/typing.rst

+   Note that the ``X | Y`` is preferred in readability in most cases.
+   However, there are :ref:`specified runtime differences<types-union>`.
+
+   Details:

   * The arguments must be types and there must be at least one.


arguments are only present when using the Union[X, Y] syntax. Prepend a clarification on this "When using Union[] syntax, the arguments ..."

Add something that covers what may be |ed together. "Only types may be used with the | operator for this purpose" or similar perhaps.

This text is technically in the "module contents" section. There is more on X|Y in the docs for the types module. Maybe we could link there (on the word "shorthand") like was done in the first version of this PR. If the description of X|Y there is not clear enough it should be updated there IMO.

Crosslinking shorthand does make sense. Otherwise I think the text here is clear enough as is.

gpshead · 2021-12-22T18:23:48Z

Doc/library/typing.rst

-   To define a union, use e.g. ``Union[int, str]`` or the shorthand ``int | str``.  Details:
+   There's also an older version ``Union[int, str]``.
+   Note that the ``X | Y`` is preferred in readability in most cases.
+   However, there are :ref:`specified runtime differences<types-union>`.


is this linking to https://docs.python.org/3.11/library/stdtypes.html#types-union ?

The wording there doesn't specifically cover Union vs | behavior differences.

bedevere-bot · 2021-12-22T18:24:37Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

gvanrossum

I would honestly start over -- throw away all changes so far, and take this:

To define a union, use e.g. ``Union[int, str]`` or the shorthand ``int | str``. Details:

Insert a single sentence before "Details:"

Using that shorthand is recommended.

sobolevn · 2021-12-22T19:06:44Z

@gvanrossum, sure! Thank you for the feedback.

I have made the requested changes; please review again

bedevere-bot · 2021-12-22T19:06:48Z

Thanks for making the requested changes!

@gpshead: please review the changes made to this pull request.

Misc/NEWS.d/next/Documentation/2021-12-21-12-45-57.bpo-46120.PE0DmJ.rst

…E0DmJ.rst Co-authored-by: Éric <[email protected]>

gvanrossum · 2021-12-24T18:57:13Z

@gpshead It’s all in. Can you merge?

gpshead · 2021-12-24T21:38:27Z

is this a 3.10 or 3.11 thing. (apply the 3.10 backport label if needed to trigger that if so)

miss-islington · 2021-12-24T21:44:32Z

Thanks @sobolevn for the PR, and @gpshead for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10.
🐍🍒⛏🤖

bedevere-bot · 2021-12-24T21:44:43Z

GH-30250 is a backport of this pull request to the 3.10 branch.

gvanrossum · 2021-12-24T21:45:16Z

Definitely 3.10. Can someone check if 3.9 has ‘|’ for unions?

AlexWaygood · 2021-12-24T21:46:18Z

Definitely 3.10. Can someone check if 3.9 has ‘|’ for unions?

It does not

Co-authored-by: Éric <[email protected]> Co-authored-by: Guido van Rossum <[email protected]> (cherry picked from commit 1b30660) Co-authored-by: Nikita Sobolev <[email protected]>

…GH-30250) Co-authored-by: Éric <[email protected]> Co-authored-by: Guido van Rossum <[email protected]> (cherry picked from commit 1b30660) Co-authored-by: Nikita Sobolev <[email protected]> Automerge-Triggered-By: GH:gpshead

sobolevn requested review from Fidget-Spinner and gvanrossum as code owners December 21, 2021 09:47

the-knights-who-say-ni added the CLA signed label Dec 21, 2021

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Dec 21, 2021

kumaraditya303 requested changes Dec 21, 2021

View reviewed changes

Doc/library/typing.rst Outdated Show resolved Hide resolved

Doc/library/typing.rst Outdated Show resolved Hide resolved

Misc/NEWS.d/next/Documentation/2021-12-21-12-45-57.bpo-46120.PE0DmJ.rst Outdated Show resolved Hide resolved

bedevere-bot added awaiting core review and removed awaiting review labels Dec 21, 2021

Fidget-Spinner reviewed Dec 21, 2021

View reviewed changes

AlexWaygood self-requested a review December 21, 2021 10:18

patrick91 reviewed Dec 21, 2021

View reviewed changes

sobolevn changed the title ~~bpo-46120: State that | is prefered over Union~~ bpo-46120: State that | is preferred over Union Dec 21, 2021

gpshead reviewed Dec 22, 2021

View reviewed changes

pbryan reviewed Dec 22, 2021

View reviewed changes

gpshead requested changes Dec 22, 2021

View reviewed changes

bedevere-bot removed the awaiting core review label Dec 22, 2021

bedevere-bot added the awaiting changes label Dec 22, 2021

gvanrossum reviewed Dec 22, 2021

View reviewed changes

Start over

f9d8689

sobolevn force-pushed the issue-46120 branch from 2d252ab to f9d8689 Compare December 22, 2021 19:05

bedevere-bot added awaiting change review and removed awaiting changes labels Dec 22, 2021

bedevere-bot requested a review from gpshead December 22, 2021 19:06

merwok reviewed Dec 24, 2021

View reviewed changes

Misc/NEWS.d/next/Documentation/2021-12-21-12-45-57.bpo-46120.PE0DmJ.rst Outdated Show resolved Hide resolved

Update Misc/NEWS.d/next/Documentation/2021-12-21-12-45-57.bpo-46120.P…

fd24598

…E0DmJ.rst Co-authored-by: Éric <[email protected]>

gvanrossum approved these changes Dec 24, 2021

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting change review labels Dec 24, 2021

gpshead approved these changes Dec 24, 2021

View reviewed changes

gpshead merged commit 1b30660 into python:main Dec 24, 2021

bedevere-bot removed the awaiting merge label Dec 24, 2021

gvanrossum added the needs backport to 3.10 only security fixes label Dec 24, 2021

bedevere-bot removed the needs backport to 3.10 only security fixes label Dec 24, 2021

AlexWaygood removed their request for review June 5, 2022 11:04

flying-sheep mentioned this pull request Jan 5, 2024

Render union types using | tox-dev/sphinx-autodoc-typehints#413

Closed

dexter2206 mentioned this pull request Mar 24, 2025

refactor: remove duplicate function names PsiQ/bartiq#167

Merged

3 tasks


		To define a union, use e.g. ``Union[int, str]`` or the shorthand ``int \| str``. Details:
		To define a union, use e.g. ``int \| str`` or the older version ``Union[int, str]``.

Uh oh!

bpo-46120: State that | is preferred over Union #30222

bpo-46120: State that | is preferred over Union #30222

Uh oh!

Conversation

sobolevn commented Dec 21, 2021 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Fidget-Spinner left a comment

Choose a reason for hiding this comment

Uh oh!

Fidget-Spinner Dec 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sobolevn Dec 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-bot commented Dec 22, 2021

Uh oh!

gvanrossum left a comment

Choose a reason for hiding this comment

Uh oh!

sobolevn commented Dec 22, 2021

Uh oh!

bedevere-bot commented Dec 22, 2021

Uh oh!

Uh oh!

gvanrossum commented Dec 24, 2021

Uh oh!

gpshead commented Dec 24, 2021

Uh oh!

miss-islington commented Dec 24, 2021

Uh oh!

bedevere-bot commented Dec 24, 2021

Uh oh!

gvanrossum commented Dec 24, 2021

Uh oh!

AlexWaygood commented Dec 24, 2021

Uh oh!

bpo-46120: State that `|` is preferred over `Union` #30222

bpo-46120: State that `|` is preferred over `Union` #30222

sobolevn commented Dec 21, 2021 •

edited by bedevere-bot

Loading

Fidget-Spinner Dec 21, 2021 •

edited

Loading

sobolevn Dec 21, 2021 •

edited

Loading