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

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

1. It does not create a separate concept. It is just a union with None
2. 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]``.

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

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?

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

Minor suggestion:

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

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

Even better.

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.

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.