Skip to content

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

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 1 commit into from
May 3, 2022
Merged

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
41 changes: 20 additions & 21 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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]): ...
...
Expand Down Expand Up @@ -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``.

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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'''
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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])

Expand All @@ -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
""""""""""""""""""""""""
Expand Down Expand Up @@ -2132,7 +2131,7 @@ Functions and decorators
...
class Sub(Base):
def done(self) -> None: # Error reported by type checker
...
...

@final
class Leaf:
Expand Down Expand Up @@ -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