mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 19:54:21 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

[3.10] Improve the typing docs (GH-92264) (#92270)

Browse source 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>.
(cherry picked from commit 27e3665715)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
This commit is contained in:
Jelle Zijlstra 2022-05-03 16:41:39 -06:00 • committed by GitHub
parent 666820cb4b
commit 31d9a88ca8
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

41
Doc/library/typing.rst
View file

@ -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