mirror of
https://github.com/python/cpython.git
synced 2026-01-06 15:32:22 +00:00
Improve the typing docs (#92264)
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
This commit is contained in:
Jelle Zijlstra
GitHub
parent
1f631ae3a1
commit
27e3665715
1 changed files with 33 additions and 34 deletions
|
|
@ -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::
|
||||
|
||||
from typing import NewType
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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:
|
||||
|
|
@ -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]): ...
|
||||
...
|
||||
|
|
@ -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``.
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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`.
|
||||
|
||||
|
|
@ -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
|
||||
def inner(*args: P.args, **kwargs: P.kwargs) -> R:
|
||||
# Provide the lock as the first argument.
|
||||
return f(my_lock, *args, **kwargs)
|
||||
|
|
@ -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``)
|
||||
together with runtime access to ``x`` within a specific application.
|
||||
|
||||
Ultimately, the responsibility of how to interpret the annotations (if
|
||||
|
|
@ -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'''
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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::
|
||||
|
|
@ -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.
|
||||
Example::
|
||||
|
||||
# raises SyntaxError
|
||||
|
|
@ -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):
|
||||
|
|
@ -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])
|
||||
|
||||
|
|
@ -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
|
||||
""""""""""""""""""""""""
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -2493,7 +2492,7 @@ Functions and decorators
|
|||
...
|
||||
class Sub(Base):
|
||||
def done(self) -> None: # Error reported by type checker
|
||||
...
|
||||
...
|
||||
|
||||
@final
|
||||
class Leaf:
|
||||
|
|
@ -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::
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue