8000 [3.10] bpo-44957: Promote PEP 604 syntax in typing docs (GH-27833) by miss-islington · Pull Request #27897 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

[3.10] bpo-44957: Promote PEP 604 syntax in typing docs (GH-27833) #27897

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Aug 22, 2021
Merged

[3.10] bpo-44957: Promote PEP 604 syntax in typing docs (GH-27833) #27897

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
913747d
bpo-44957: Promote PEP 604 syntax in typing docs (GH-27833)
srittau Aug 22, 2021
19ae194
Move susp-ignored locations
ambv Aug 22, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
bpo-44957: Promote PEP 604 syntax in typing docs (GH-27833) 
* Use "X | Y" instead of "Union" where it makes sense.
* Mention that "X | Y" is equivalent to "Union[X, Y]" in Union section.
* Remove "Optional[X]" as shorthand for "Union[X, None]" as the new
  shorthand is now "X | None".
* Mention that "Optional[X]" can be written as "X | None" in section
  about "Optional".

Co-authored-by: Ken Jin <28750310+Fidget-Spinner@users.noreply.github.com>
(cherry picked from commit dabb6e8)

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>
  • Loading branch information
@srittau @miss-islington
srittau authored and miss-islington committed Aug 22, 2021
commit 913747d2589e0f0d9605b9c33dd3e805d2c3ecbd
30 changes: 16 additions & 14 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -321,11 +321,11 @@ not generic but implicitly inherits from ``Iterable[Any]``::
User defined generic type aliases are also supported. Examples::

from collections.abc import Iterable
from typing import TypeVar, Union
from typing import TypeVar
S = TypeVar('S')
Response = Union[Iterable[S], int]
Response = Iterable[S] | int

# Return type here is same as Union[Iterable[str], int]
# Return type here is same as Iterable[str] | int
def response(query: str) -> Response[str]:
...

Expand Down Expand Up @@ -588,9 +588,9 @@ These can be used as types in annotations using ``[]``, each having a unique syn

.. data:: Union

Union type; ``Union[X, Y]`` means either X or Y.
Union type; ``Union[X, Y]`` is equivalent to ``X | Y`` and means either X or Y.

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

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

Expand All @@ -604,18 +604,16 @@ These can be used as types in annotations using ``[]``, each having a unique syn

* Redundant arguments are skipped, e.g.::

Union[int, str, int] == Union[int, str]
Union[int, str, int] == Union[int, str] == int | str

* When comparing unions, the argument order is ignored, e.g.::

Union[int, str] == Union[str, int]

* You cannot subclass or instantiate a union.
* You cannot subclass or instantiate a ``Union``.

* You cannot write ``Union[X][Y]``.

* You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``.

.. versionchanged:: 3.7
Don't remove explicit subclasses from unions at runtime.

Expand All @@ -627,7 +625,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn

Optional type.

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

Note that this is not the same concept as an optional argument,
which is one that has a default. An optional argument with a
Expand All @@ -644,6 +642,10 @@ These can be used as types in annotations using ``[]``, each having a unique syn
def foo(arg: Optional[int] = None) -> None:
...

.. versionchanged:: 3.10
Optional can now be written as ``X | None``. See
:ref:`union type expressions<types-union>`.

.. data:: Callable

Callable type; ``Callable[[int], str]`` is a function of (int) -> str.
Expand Down Expand Up @@ -770,7 +772,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
:ref:`type variables <generics>`, and unions of any of these types.
For example::

def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]): ...
def new_non_team_user(user_class: Type[BasicUser | ProUser]): ...

``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent
to ``type``, which is the root of Python's metaclass hierarchy.
Expand Down Expand Up @@ -951,7 +953,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn
conditional code flow and applying the narrowing to a block of code. The
conditional expression here is sometimes referred to as a "type guard"::

def is_str(val: Union[str, float]):
def is_str(val: str | float):
# "isinstance" type guard
if isinstance(val, str):
# Type of ``val`` is narrowed to ``str``
Expand Down Expand Up @@ -2031,7 +2033,7 @@ Introspection helpers
For a typing object of the form ``X[Y, Z, ...]`` these functions return
``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or
:mod:`collections` class, it gets normalized to the original class.
If ``X`` is a :class:`Union` or :class:`Literal` contained in another
If ``X`` is a union or :class:`Literal` contained in another
generic type, the order of ``(Y, Z, ...)`` may be different from the order
of the original arguments ``[Y, Z, ...]`` due to type caching.
For unsupported objects return ``None`` and ``()`` correspondingly.
Expand All @@ -2056,7 +2058,7 @@ Introspection helpers
year: int

is_typeddict(Film) # => True
is_typeddict(Union[list, str]) # => False
is_typeddict(list | str) # => False

.. versionadded:: 3.10

Expand Down
3 changes: 3 additions & 0 deletions Misc/NEWS.d/next/Documentation/2021-08-19-15-53-08.bpo-44957.imqrh3.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
Promote PEP 604 union syntax by using it where possible. Also, mention ``X |
Y`` more prominently in section about ``Union`` and mention ``X | None`` at
all in section about ``Optional``.
0