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

@picnixz picnixz Mar 7, 2026

Choose a reason for hiding this comment

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

I prefer "take" but would rather have "takes a single argument". "has" doesn't ring good here.

Copy link
Member

@AlexWaygood AlexWaygood Mar 7, 2026

Choose a reason for hiding this comment

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

I find this specific change an improvement, but I'm also fine with "takes a single argument". I don't have a preference between "takes a single argument" and "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.
Copy link
Member

@picnixz picnixz Mar 7, 2026

Choose a reason for hiding this comment

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

I think subscription syntax is better. It is confusing to say that [] must have two objects. But parameter list is correct.

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

@picnixz picnixz Mar 7, 2026

Choose a reason for hiding this comment

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

I prefer the current formulation.

keyword-only or var-positional parameters, or :ref:`overloaded functions <overload>`.
Copy link
Member

@picnixz picnixz Mar 7, 2026

Choose a reason for hiding this comment

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

I think we can neither express var-keyword arguments (which is different from keyword-only ones) nor "positional-only". I also think "variadic number of arguments" actually takes into account both positional and keyword-only ones, so I would only add a mention to "positional-only". I would also mention overloaded functions at the end of the sentence though.

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