gh-133438: Fix the use of the terms "argument" and "parameter" in the documentation

[serhiy-storchaka]

• Issue: PEP 3102 and PEP 570 should say **Keyword-Only Parameters** instead of **Keyword-Only Arguments** #133438

---

📚 Documentation preview 📚: https://cpython-previews--135160.org.readthedocs.build/

[encukou]

Sadly, “keyword” means something entirely different. IMO we need to use the full term.

Suggested change

	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

[serhiy-storchaka]

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 a

[terryjreedy]

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

Suggested change

	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.

[encukou]

Arguments have values. Also, this should be plural.

Suggested change

	keyword-or-positional parameter.
	keyword-or-positional arguments.

[serhiy-storchaka]

Only parameters have default values. If the argument is not passed, the the default value is used.

[encukou]

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.

[serhiy-storchaka]

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.

[terryjreedy]

Again, I agree with Serhiy.

[encukou]

Suggested change

	| | | 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)

[encukou]

https://docs.python.org/3/library/inspect.html#inspect.CO_VARKEYWORDS uses “**kwargs-like”.

[serhiy-storchaka]

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.

[JelleZijlstra]

Thanks for doing all this! Most of it looks great.

[JelleZijlstra]

I think the old wording is clearer here, "keyword-only" is a well-known term in Python.

[serhiy-storchaka]

Keyword-only can be only parameters. Arguments are either positional or keyword. Argument is what we pass to the function.

[encukou]

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.

[JelleZijlstra]

Why remove "only"? I don't see anything wrong with calling these "keyword-only".

[JelleZijlstra]

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.

[encukou]

IMO, the -only is redundant, but it does make things clearer.

[serhiy-storchaka]

If the parameter was keyword-or-positional, we would say "The optional argument context".

[terryjreedy]

I agree with Jelle's 2nd comment that -only can be left removed here and below.

[serhiy-storchaka]

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.

[terryjreedy]

I stopped at ast.rst for now.

[terryjreedy]

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

Suggested change

	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.

[terryjreedy]

I think an alternative change, not necessarily better, would have been /take/have/.

[bedevere-app]

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

[terryjreedy]

Stopped at code.h.

[rhettinger]

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.

[serhiy-storchaka]

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.

[rhettinger]

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 / and * are simply restrictions on how arguments may be passed. From that POV, they don't modify the parameters themselves. Accordingly, "positional-only" parameter doesn't make any sense.

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").