gh-133438: Fix the use of the terms "argument" and "parameter" in the documentation #135160
Conversation
…in the documentation
…in dis.show_code()
…in error messages for invalid function calls
| Indicates that the remaining arguments in the Python argument list are | ||
| keyword-only. Currently, all keyword-only arguments must also be optional | ||
| Indicates that the remaining arguments in the Python argument list can be | ||
| supplied only by keyword. Currently, all such arguments must also be optional |
There was a problem hiding this comment.
Sadly, “keyword” means something entirely different. IMO we need to use the full term.
| supplied only by keyword. Currently, all such arguments must also be optional | |
| supplied only as keyword arguments. Currently, all such arguments must also be optional |
There was a problem hiding this comment.
This is from the definition of the keyword-only parameter.
* :dfn:`keyword-only`: specifies an argument that can be supplied only
by keyword. Keyword-only parameters can be defined by including aThere was a problem hiding this comment.
In the context of PyArg_ParseTupleAndKeywords, 'keyword' means 'parameter name' rather than 'syntax keyword. So I think Serhiy's revision could be left as is, or changed to
| supplied only by keyword. Currently, all such arguments must also be optional | |
| supplied only by parameter name. Currently, all such arguments must also be optional |
The keword-only definition is a bit circular. Perhaps by keyword should be changed to by parameter name to break the loop.
Doc/library/ast.rst
Outdated
| positionally. If there are fewer defaults, they correspond to the last n | ||
| arguments. | ||
| * ``defaults`` is a list of default values for positional-only and | ||
| keyword-or-positional parameter. |
There was a problem hiding this comment.
Arguments have values. Also, this should be plural.
| keyword-or-positional parameter. | |
| keyword-or-positional arguments. |
There was a problem hiding this comment.
Only parameters have default values. If the argument is not passed, the the default value is used.
| There are two optional keyword-only arguments. The *key* argument specifies | ||
| Two optional keyword arguments are supported. The *key* argument specifies |
There was a problem hiding this comment.
This PR removes the -only in lots of places. I'd lean toward keeping that by default, even for arguments to make it clearer that you can't pass it positionally.
The * in the signature is only useful if you know what it means.
There was a problem hiding this comment.
If we did not mean that they can only be passed by keyword, we would not use word "keyword" here. "Two optional arguments are supported." Misuse "-only" for arguments provokes further errors.
Doc/library/inspect.rst
Outdated
| | | | \*\* arg) | | ||
| | | co_kwonlyargcount | number of keyword-only | | ||
| | | | parameters (not including | | ||
| | | | var-positional parameter) | |
There was a problem hiding this comment.
| | | | var-positional parameter) | | |
| | | | a ``**kwargs`` parameter) | |
IMO **kwargs is clear enough. It's already used in https://docs.python.org/3/library/inspect.html#inspect.Parameter.kind
(And if you disagree: it'd be var-keyword, not var-positional)
There was a problem hiding this comment.
https://docs.python.org/3/library/inspect.html#inspect.CO_VARKEYWORDS uses “**kwargs-like”.
There was a problem hiding this comment.
Thank you, this was a typo.
I used terminology from the glossary. In few cases I left *args and **kwargs, but in the module documentation we can allow ourself to be more formal and verbose.
| @@ -410,8 +410,8 @@ inside nested parentheses. They are: | |||
|
|
|||
| ``$`` | |||
| :c:func:`PyArg_ParseTupleAndKeywords` only: | |||
| Indicates that the remaining arguments in the Python argument list are | |||
| keyword-only. Currently, all keyword-only arguments must also be optional | |||
There was a problem hiding this comment.
I think the old wording is clearer here, "keyword-only" is a well-known term in Python.
There was a problem hiding this comment.
Keyword-only can be only parameters. Arguments are either positional or keyword. Argument is what we pass to the function.
There was a problem hiding this comment.
In the same way, an argument can't be optional: if you omit it, it does not exist at all.
But the terms “optional” and “keyword-only” describe the possibilities you have, not a specific argument in a specific call.
| @@ -232,7 +232,7 @@ Scheduling callbacks | |||
| Callbacks are called in the order in which they are registered. | |||
| Each callback will be called exactly once. | |||
|
|
|||
| The optional keyword-only *context* argument specifies a | |||
| The optional keyword argument *context* specifies a | |||
There was a problem hiding this comment.
Why remove "only"? I don't see anything wrong with calling these "keyword-only".
There was a problem hiding this comment.
Answering my own question after reading more of the diff: "only" means nothing for arguments, since an argument is only ever keyword or positional, not both. So arguments are either positional or keyword; "keyword-only" makes sense only for parameters because parameters can be both at once.
There was a problem hiding this comment.
IMO, the -only is redundant, but it does make things clearer.
There was a problem hiding this comment.
If the parameter was keyword-or-positional, we would say "The optional argument context".
There was a problem hiding this comment.
I agree with Jelle's 2nd comment that -only can be left removed here and below.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> Co-authored-by: Petr Viktorin <encukou@gmail.com>
|
Thank you for a review. The changes are not always trivial, and it is not always easy to find a clear and correct alternative, but I think that we should be a bit more formal to prevent further spreading of incorrect terminology. In some cases, I had to open the original issue or look into the code to understand what it was actually about -- an argument or a parameter. |
| Indicates that the remaining arguments in the Python argument list are | ||
| keyword-only. Currently, all keyword-only arguments must also be optional | ||
| Indicates that the remaining arguments in the Python argument list can be | ||
| supplied only by keyword. Currently, all such arguments must also be optional |
There was a problem hiding this comment.
In the context of PyArg_ParseTupleAndKeywords, 'keyword' means 'parameter name' rather than 'syntax keyword. So I think Serhiy's revision could be left as is, or changed to
| supplied only by keyword. Currently, all such arguments must also be optional | |
| supplied only by parameter name. Currently, all such arguments must also be optional |
The keword-only definition is a bit circular. Perhaps by keyword should be changed to by parameter name to break the loop.
| formatting styles. The :class:`Formatter` class been enhanced to take an | ||
| additional, optional keyword parameter named ``style``. This defaults to | ||
| additional, optional keyword argument named ``style``. This defaults to |
There was a problem hiding this comment.
I think an alternative change, not necessarily better, would have been /take/have/.
|
When you're done making the requested changes, leave the comment: |
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>
|
I have doubts about this massive sweep through the docs. The difference between parameter and argument is a technicality that disagrees with common usage. The norm is to refer to "keyword arguments" and to name the parameter "**kwargs". This is common in blog posts, docs, docstrings and it is what people search for. My opinion is that the utility and accessibility of our docs would be impaired by this global substitution. There are some places where it makes sense and some where is doesn't sound right. @nedbat The docs wg should take a look at this one. |
|
It is not so massive comparing with the size of the documentation. "Keyword arguments" is a correct term, this PR does nothing with it. "kwargs" is a nice name for var-keyword parameter, it will contain a dict of keyword arguments. If we fix the documentation now, there will be fewer errors in the future, because new small pieces of documentation are often written based on existing examples. |
|
ISTM this ventures far from how everyday Python programmers think, speak, and write about the language. The terms "keyword-only arguments" and "positional only arguments" are commonplace (including in PEP 3102). In Python books, at conferences, and in blog posts, I don't recall ever hearing "keyword-only parameters" or "positional only parameters." To my ear, that sounds foreign and discordant. This is a somewhat of a "sweeping PR" and hits 85 files, reversing the wording decisions made by many authors and their reviewers. The premise of the PR seems pedantic to me and at odds with the needs of our users. While I personally am careful when teaching Python to use "argument" and "parameter" precisely, most people do not draw a distinction and use "argument" for both. My opinion is that the PR mostly makes the docs less readable, searchable, and user friendly (though it would be worse if the even more precise term "formal parameter" was used everywhere). Keep in mind, that the PEPs went through. a heavy discussion phase and no one asked for the title to be changed. Also, the same terminology was used in whatsnew and throughout the docs. It is somewhat heavily vetted as reasonably clear speech and has been in the wild since 2006. We do not need to make this sweeping edit to well established text. Another thought is the that current terminology reflects a reasonable point of view that Also, there is another issue for users. While folks with a CS background tend to think arguments as being the values that get bound to parameters, other engineering disciplines use the term "parameters" to mean the values themselves (i.e. "we adjusted the parameters" or "parametric equations"). |
|
There is a dedicated FAQ entry for difference between arguments and parameters: See also definitions of terms argument and parameter in the glossary: In this PR you only see changes for incorrect use of terms argument and parameter, but you do not see when thay are used correctly. Some of fixed docs were written by me, it was not intentional, they were errors. If we fix existing errors in the documentation, this will reduce the number of future errors, because the authors will have less wrong examples. If you have any specific requests for changes, please point them out, we will discuss them or leave the concrete cases for future if they are ambiguous. But overall this PR fixes a lot of errors. |
📚 Documentation preview 📚: https://cpython-previews--135160.org.readthedocs.build/