[Python-checkins] [3.10] Improve the typing docs (GH-92264) (#92270)
JelleZijlstra
webhook-mailer at python.org
Tue May 3 18:41:43 EDT 2022
https://github.com/python/cpython/commit/31d9a88ca8ecf06c410a980e08bb848101d4461a
commit: 31d9a88ca8ecf06c410a980e08bb848101d4461a
branch: 3.10
author: Jelle Zijlstra <jelle.zijlstra at gmail.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2022-05-03T16:41:39-06:00
summary:
[3.10] Improve the typing docs (GH-92264) (#92270)
Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>.
(cherry picked from commit 27e366571590e9e98f61dccf69dbeaa88ee66737)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
files:
M Doc/library/typing.rst
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index 6a160af895c06..bcf2b22b1a3c2 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 <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
More information about the Python-checkins
mailing list