gh-145577: Correct "Annotating callable objects" explanation#145576
gh-145577: Correct "Annotating callable objects" explanation#145576hyperkai wants to merge 5 commits intopython:mainfrom
Conversation
hyperkai
changed the title
picnixz
left a comment
picnixz
left a comment
There was a problem hiding this comment.
Some formulations are correct while others feel weird to me, but I also want to have other core devs' opinion on this one. Formally, there are a lot of terms that are imprecise in the docs but in practice, having more formal definitions or formulation usually confuses the reader more than helping them. What we try to do now, though, is to avoid using "argument" in place of parameter and vice-versa.
| 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 |
There was a problem hiding this comment.
I prefer the current formulation.
| 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 |
There was a problem hiding this comment.
I prefer "take" but would rather have "takes a single argument". "has" doesn't ring good here.
There was a problem hiding this comment.
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".
| 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. |
There was a problem hiding this comment.
I think subscription syntax is better. It is confusing to say that [] must have two objects. But parameter list is correct.
| 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>`. |
There was a problem hiding this comment.
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.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
3 participants
Fix: #145577
Related: #145602