-
-
Notifications
You must be signed in to change notification settings - Fork 2.9k
Make "X | Y" union syntax more prominent in documentation #17835
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
Soon 4 out of 5 supported Python versions will support the `X | Y` syntax, so we can make it more prominent (Python 3.13 will be out soon, and 3.8 will reach end of life). The syntax is available starting from Python 3.10, but it can be used in annotations in earlier Python versions as well if using `from __future__ import annotations`.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good, some small feedback
docs/source/kinds_of_types.rst
Outdated
@@ -236,18 +237,16 @@ Python functions often accept values of two or more different | |||
types. You can use :ref:`overloading <function-overloading>` to | |||
represent this, but union types are often more convenient. | |||
|
|||
Use the ``Union[T1, ..., Tn]`` type constructor to construct a union | |||
type. For example, if an argument has type ``Union[int, str]``, both | |||
Use the ``T1 | ... | Tn`` type constructor to construct a union |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Use the ``T1 | ... | Tn`` type constructor to construct a union | |
Use the ``T1 | ... | Tn`` operator to construct a union |
Feels odd to call this a "type constructor"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Using "operator" here also didn't feel quite right, so I just left out the "type constructor" bit.
docs/source/kinds_of_types.rst
Outdated
t1: int | str # equivalent to Union[int, str] | ||
|
||
t2: int | None # equivalent to Optional[int] | ||
The type ``... | None`` *does not* mean a function parameter with a default value. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since this confusion is related to the name Optional, it might be better to keep using Optional[T]
here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated.
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Soon 4 out of 5 supported Python versions will support the
X | Y
syntax,so we can make it more prominent (Python 3.13 will be out soon, and 3.8
will reach end of life). Use it in most examples.
The syntax is available starting from Python 3.10, but it can be used
in annotations in earlier Python versions as well if using
from __future__ import annotations
.