From 1697373a9ce759967c81f1e9d0779621c9d7485e Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Tue, 3 May 2022 15:49:21 -0600 Subject: [PATCH] [3.10] Improve the typing docs (GH-92264) Co-authored-by: Alex Waygood . (cherry picked from commit 27e366571590e9e98f61dccf69dbeaa88ee66737) Co-authored-by: Jelle Zijlstra --- Doc/library/typing.rst | 41 ++++++++++++++++++++--------------------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 6a160af895c064..bcf2b22b1a3c2a 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -115,7 +115,7 @@ Note that ``None`` as a type hint is a special case and is replaced by NewType ======= -Use the :class:`NewType` helper class to create distinct types:: +Use the :class:`NewType` helper to create distinct types:: from typing import NewType @@ -144,7 +144,7 @@ accidentally creating a ``UserId`` in an invalid way:: Note that these checks are enforced only by the static type checker. At runtime, the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a -class that immediately returns whatever parameter you pass it. That means +callable that immediately returns whatever parameter you pass it. That means the expression ``Derived(some_value)`` does not create a new class or introduce much overhead beyond that of a regular function call. @@ -232,7 +232,7 @@ respectively. See :pep:`612` for more information. .. seealso:: - The documentation for :class:`ParamSpec` and :class:`Concatenate` provide + The documentation for :class:`ParamSpec` and :class:`Concatenate` provides examples of usage in ``Callable``. .. _generics: @@ -401,7 +401,7 @@ to this is that a list of types can be used to substitute a :class:`ParamSpec`:: Furthermore, a generic with only one parameter specification variable will accept parameter lists in the forms ``X[[Type1, Type2, ...]]`` and also ``X[Type1, Type2, ...]`` for aesthetic reasons. Internally, the latter is converted -to the former and are thus equivalent:: +to the former, so the following are equivalent:: >>> class X(Generic[P]): ... ... @@ -505,7 +505,7 @@ manner. Use :data:`Any` to indicate that a value is dynamically typed. Nominal vs structural subtyping =============================== -Initially :pep:`484` defined Python static type system as using +Initially :pep:`484` defined the Python static type system as using *nominal subtyping*. This means that a class ``A`` is allowed where a class ``B`` is expected if and only if ``A`` is a subclass of ``B``. @@ -756,7 +756,6 @@ These can be used as types in annotations using ``[]``, each having a unique syn def with_lock(f: Callable[Concatenate[Lock, P], R]) -> Callable[P, R]: '''A type-safe decorator which provides a lock.''' - global my_lock def inner(*args: P.args, **kwargs: P.kwargs) -> R: # Provide the lock as the first argument. return f(my_lock, *args, **kwargs) @@ -912,7 +911,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn ``no_type_check`` functionality that currently exists in the ``typing`` module which completely disables typechecking annotations on a function or a class, the ``Annotated`` type allows for both static typechecking - of ``T`` (e.g., via mypy or Pyre, which can safely ignore ``x``) + of ``T`` (which can safely ignore ``x``) together with runtime access to ``x`` within a specific application. Ultimately, the responsibility of how to interpret the annotations (if @@ -1016,7 +1015,7 @@ These can be used as types in annotations using ``[]``, each having a unique syn 2. If the return value is ``True``, the type of its argument is the type inside ``TypeGuard``. - For example:: + For example:: def is_str_list(val: List[object]) -> TypeGuard[List[str]]: '''Determines whether all objects in the list are strings''' @@ -1230,11 +1229,11 @@ These are not used in annotations. They are building blocks for creating generic use a :class:`TypeVar` with bound ``Callable[..., Any]``. However this causes two problems: - 1. The type checker can't type check the ``inner`` function because - ``*args`` and ``**kwargs`` have to be typed :data:`Any`. - 2. :func:`~cast` may be required in the body of the ``add_logging`` - decorator when returning the ``inner`` function, or the static type - checker must be told to ignore the ``return inner``. + 1. The type checker can't type check the ``inner`` function because + ``*args`` and ``**kwargs`` have to be typed :data:`Any`. + 2. :func:`~cast` may be required in the body of the ``add_logging`` + decorator when returning the ``inner`` function, or the static type + checker must be told to ignore the ``return inner``. .. attribute:: args .. attribute:: kwargs @@ -1392,7 +1391,7 @@ These are not used in annotations. They are building blocks for declaring types. The resulting class has an extra attribute ``__annotations__`` giving a dict that maps the field names to the field types. (The field names are in the ``_fields`` attribute and the default values are in the - ``_field_defaults`` attribute both of which are part of the namedtuple + ``_field_defaults`` attribute, both of which are part of the :func:`~collections.namedtuple` API.) ``NamedTuple`` subclasses can also have docstrings and methods:: @@ -1467,7 +1466,7 @@ These are not used in annotations. They are building blocks for declaring types. Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) The functional syntax should also be used when any of the keys are not valid - :ref:`identifiers`, for example because they are keywords or contain hyphens. + :ref:`identifiers `, for example because they are keywords or contain hyphens. Example:: # raises SyntaxError @@ -1506,7 +1505,7 @@ These are not used in annotations. They are building blocks for declaring types. y: int z: int - A ``TypedDict`` cannot inherit from a non-TypedDict class, + A ``TypedDict`` cannot inherit from a non-\ ``TypedDict`` class, notably including :class:`Generic`. For example:: class X(TypedDict): @@ -1915,7 +1914,7 @@ Corresponding to other types in :mod:`collections.abc` .. class:: Hashable - An alias to :class:`collections.abc.Hashable` + An alias to :class:`collections.abc.Hashable`. .. class:: Reversible(Iterable[T_co]) @@ -1927,7 +1926,7 @@ Corresponding to other types in :mod:`collections.abc` .. class:: Sized - An alias to :class:`collections.abc.Sized` + An alias to :class:`collections.abc.Sized`. Asynchronous programming """""""""""""""""""""""" @@ -2132,7 +2131,7 @@ Functions and decorators ... class Sub(Base): def done(self) -> None: # Error reported by type checker - ... + ... @final class Leaf: @@ -2293,8 +2292,8 @@ Constant If ``from __future__ import annotations`` is used in Python 3.7 or later, annotations are not evaluated at function definition time. - Instead, they are stored as strings in ``__annotations__``, - This makes it unnecessary to use quotes around the annotation. + Instead, they are stored as strings in ``__annotations__``. + This makes it unnecessary to use quotes around the annotation (see :pep:`563`). .. versionadded:: 3.5.2