From 57b321c37716f07c8fa3f3ea48857b81bc7012af Mon Sep 17 00:00:00 2001 From: "Miss Islington (bot)" <31488909+miss-islington@users.noreply.github.com> Date: Sun, 22 Aug 2021 13:04:43 -0700 Subject: Move susp-ignored locations --- Doc/library/typing.rst | 30 ++++++++++++---------- Doc/tools/susp-ignored.csv | 8 +++--- .../2021-08-19-15-53-08.bpo-44957.imqrh3.rst | 3 +++ 3 files changed, 23 insertions(+), 18 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2021-08-19-15-53-08.bpo-44957.imqrh3.rst diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 47d6c3a..53cf542 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -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]: ... @@ -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. @@ -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. @@ -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 @@ -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`. + .. data:: Callable Callable type; ``Callable[[int], str]`` is a function of (int) -> str. @@ -770,7 +772,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn :ref:`type variables `, 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. @@ -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`` @@ -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. @@ -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 diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index 1fde253..1ba0e5b 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -369,7 +369,7 @@ library/importlib.metadata,,:main,"EntryPoint(name='wheel', value='wheel.cli:mai library/importlib.metadata,,`,loading the metadata for packages for the indicated ``context``. library/re,,`,"`" using/configure,84,:db2,=db1:db2:... -library/typing,1004,`,# Type of ``val`` is narrowed to ``str`` -library/typing,1004,`,"# Else, type of ``val`` is narrowed to ``float``." -library/typing,1004,`,# Type of ``val`` is narrowed to ``List[str]``. -library/typing,1004,`,# Type of ``val`` remains as ``List[object]``. +library/typing,1011,`,# Type of ``val`` is narrowed to ``str`` +library/typing,1011,`,"# Else, type of ``val`` is narrowed to ``float``." +library/typing,1011,`,# Type of ``val`` is narrowed to ``List[str]``. +library/typing,1011,`,# Type of ``val`` remains as ``List[object]``. diff --git a/Misc/NEWS.d/next/Documentation/2021-08-19-15-53-08.bpo-44957.imqrh3.rst b/Misc/NEWS.d/next/Documentation/2021-08-19-15-53-08.bpo-44957.imqrh3.rst new file mode 100644 index 0000000..20a2aec --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-08-19-15-53-08.bpo-44957.imqrh3.rst @@ -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``. -- cgit v0.12