Skip to content

gh-145577: Correct "Annotating callable objects" explanation #145576

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

Open
hyperkai wants to merge 5 commits into
base: main
Choose a base branch
from
+9 −11
Open

gh-145577: Correct "Annotating callable objects" explanation #145576

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
44838e5
Correct "Annotating callable objects"
hyperkai Mar 5, 2026
198eb1f
Correct "Annotating callable objects" additional
hyperkai Mar 6, 2026
6fddb12
Update typing.rst
hyperkai Mar 6, 2026
35e52b1
Update typing.rst
hyperkai Mar 6, 2026
6f1851f
Update typing.rst
hyperkai Mar 6, 2026
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
20 changes: 9 additions & 11 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ Annotating callable objects

Functions -- or other :term:`callable` objects -- can be annotated using
:class:`collections.abc.Callable` or deprecated :data:`typing.Callable`.
``Callable[[int], str]`` signifies a function that takes a single parameter
``Callable[[int], str]`` signifies a function that has a single parameter
of type :class:`int` and returns a :class:`str`.

For example:
Expand All @@ -232,12 +232,11 @@ For example:

.. index:: single: ...; ellipsis literal

The subscription syntax must always be used with exactly two values: the
argument list and the return type. The argument list must be a list of types,
a :class:`ParamSpec`, :data:`Concatenate`, or an ellipsis (``...``). The return type must
be a single type.
The type specification ``[]`` must have two objects, a parameter type list and return type.
The parameter type list must be a list of types, :class:`ParamSpec`, :data:`Concatenate`
or ellipsis (``...``). The return type must be a single type.

If a literal ellipsis ``...`` is given as the argument list, it indicates that
If a literal ellipsis ``...`` is given as the parameter type list, it indicates that
a callable with any arbitrary parameter list would be acceptable:

.. testcode::
Expand All @@ -249,10 +248,9 @@ a callable with any arbitrary parameter list would be acceptable:
x = str # OK
x = concat # Also OK

``Callable`` cannot express complex signatures such as functions that take a
variadic number of arguments, :ref:`overloaded functions <overload>`, or
functions that have keyword-only parameters. However, these signatures can be
expressed by defining a :class:`Protocol` class with a
``Callable`` cannot express complex signatures such as functions that have
keyword-only or var-positional parameters, or :ref:`overloaded functions <overload>`.
However, these signatures can be expressed by defining a :class:`Protocol` class with a
:meth:`~object.__call__` method:

.. testcode::
Expand Down Expand Up @@ -281,7 +279,7 @@ parameter types are dependent on each other using :class:`ParamSpec`.
Additionally, if that callable adds or removes arguments from other
callables, the :data:`Concatenate` operator may be used. They
take the form ``Callable[ParamSpecVariable, ReturnType]`` and
``Callable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]``
``Callable[Concatenate[ParamType1, ParamType2, ..., ParamSpecVariable], ReturnType]``
respectively.

.. versionchanged:: 3.10
Expand Down
Loading