Skip to content

Improve the typing docs #92264

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

Improve the typing docs #92264

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
df8975d
Improve the typing docs
JelleZijlstra May 3, 2022
db40adb
Update Doc/library/typing.rst
JelleZijlstra May 3, 2022
c965540
Update Doc/library/typing.rst
JelleZijlstra May 3, 2022
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
67 changes: 33 additions & 34 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,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::
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's an implementation detail whether it is a class or a function, so avoid being specific.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An alternative would be "helper callable", but I think "helper" is also fine.


from typing import NewType

Expand Down Expand Up @@ -154,7 +154,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 @@ -242,7 +242,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 @@ -411,7 +411,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 @@ -515,7 +515,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 @@ -590,10 +590,10 @@ These can be used as types in annotations and do not support ``[]``.
* Every type is compatible with :data:`Any`.
* :data:`Any` is compatible with every type.

.. versionchanged:: 3.11
:data:`Any` can now be used as a base class. This can be useful for
avoiding type checker errors with classes that can duck type anywhere or
are highly dynamic.
.. versionchanged:: 3.11
:data:`Any` can now be used as a base class. This can be useful for
avoiding type checker errors with classes that can duck type anywhere or
are highly dynamic.

.. data:: LiteralString

Expand Down Expand Up @@ -708,9 +708,9 @@ These can be used as types in annotations and do not support ``[]``.

Other common use cases include:

- :class:`classmethod`\s that are used as alternative constructors and return instances
of the ``cls`` parameter.
- Annotating an :meth:`object.__enter__` method which returns self.
- :class:`classmethod`\s that are used as alternative constructors and return instances
of the ``cls`` parameter.
- Annotating an :meth:`~object.__enter__` method which returns self.

For more information, see :pep:`673`.

Expand Down Expand Up @@ -880,7 +880,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
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not needed since we're not writing to the variable

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 @@ -1036,7 +1035,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``)
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to call out specific type checkers here

together with runtime access to ``x`` within a specific application.

Ultimately, the responsibility of how to interpret the annotations (if
Expand Down Expand Up @@ -1140,7 +1139,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 @@ -1279,7 +1278,7 @@ These are not used in annotations. They are building blocks for creating generic

.. class:: TypeVarTuple

Type variable tuple. A specialized form of :class:`Type variable <TypeVar>`
Type variable tuple. A specialized form of :class:`type variable <TypeVar>`
that enables *variadic* generics.

A normal type variable enables parameterization with a single type. A type
Expand Down Expand Up @@ -1440,11 +1439,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 @@ -1602,7 +1601,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 @@ -1695,7 +1694,7 @@ These are not used in annotations. They are building blocks for declaring types.
in 3.13. It may also be unsupported by static type checkers.

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.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This showed up as "Identifiers and keywords" (the section title over there).

Example::

# raises SyntaxError
Expand Down Expand Up @@ -1737,7 +1736,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,
except for :class:`Generic`. For example::

class X(TypedDict):
Expand Down Expand Up @@ -2155,7 +2154,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 @@ -2167,7 +2166,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 @@ -2388,12 +2387,12 @@ Functions and decorators

.. seealso::
`Unreachable Code and Exhaustiveness Checking
<https://typing.readthedocs.io/en/latest/source/unreachable.html>_` has more
<https://typing.readthedocs.io/en/latest/source/unreachable.html>`__ has more
information about exhaustiveness checking with static typing.

.. versionadded:: 3.11

.. function:: reveal_type(obj)
.. function:: reveal_type(obj, /)

Reveal the inferred static type of an expression.

Expand Down Expand Up @@ -2465,9 +2464,9 @@ Functions and decorators
the documentation for :func:`@overload <overload>`,
``get_overloads(process)`` will return a sequence of three function objects
for the three defined overloads. If called on a function with no overloads,
``get_overloads`` returns an empty sequence.
``get_overloads()`` returns an empty sequence.

``get_overloads`` can be used for introspecting an overloaded function at
``get_overloads()`` can be used for introspecting an overloaded function at
runtime.

.. versionadded:: 3.11
Expand All @@ -2493,7 +2492,7 @@ Functions and decorators
...
class Sub(Base):
def done(self) -> None: # Error reported by type checker
...
...

@final
class Leaf:
Expand Down Expand Up @@ -2632,8 +2631,8 @@ Introspection helpers
.. class:: ForwardRef

A class used for internal typing representation of string forward references.
For example, ``list["SomeClass"]`` is implicitly transformed into
``list[ForwardRef("SomeClass")]``. This class should not be instantiated by
For example, ``List["SomeClass"]`` is implicitly transformed into
``List[ForwardRef("SomeClass")]``. This class should not be instantiated by
a user, but may be used by introspection tools.

.. note::
Expand Down Expand Up @@ -2667,7 +2666,7 @@ 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.
This makes it unnecessary to use quotes around the annotation
(see :pep:`563`).

.. versionadded:: 3.5.2
Expand Down