There is currently some ambiguity in our documentation around positional and keyword arguments (e.g. whether positional means "position-only" or "non-keyword" (roughly) and whether various terms and definitions should be for the calling syntax or the function definition syntax or both).  For example, see the python-dev thread starting here:

http://mail.python.org/pipermail/python-dev/2012-September/121760.html

It would be good to nail down the preferred terminology in a central place.  I would suggest that the glossary is a good place to start.

For example, when there is a question about what phrase an error message should use or how an error message should be interpreted, it would be good if (at least going forward) the glossary could be used as a definitive resource.

This issue may involve making a distinction in our terminology "between arguments (what you pass, call syntax) and parameters (what the function receives, function definition syntax)" (see http://mail.python.org/pipermail/python-dev/2012-September/121771.html ).

> "between arguments (what you pass, call syntax) and parameters
> (what the function receives, function definition syntax)"

Note that there's a subtle difference to make here.  IMHO as soon as you use terms like "receives" or "accepts", you are still talking about arguments.  What you pass from one side is received by the other, and it's called an argument.

Given "def f(x, y): pass" you can say that x and y are parameter of the f function, or that the function accepts 2 arguments -- x and y.  The latter is far more common IME, and I rarely talk about parameters myself.

In "f() missing 1 required positional argument: 'x'", the usage of "argument" is correct, because what's missing is the argument in the function call, not the parameter in the function definition.  However the error points to the corresponding parameter 'x' -- because clearly it can't point to the argument you forgot to pass -- and this fact might led to some confusion.  IMHO though, the error is clear as is (at least regarding argument/parameter), so I wouldn't change it.

Nick Coghlan pointed out that a lot of this discussion has already happened for the function signature object PEP [1].  That PEP defines constants

    Parameter.POSITIONAL_ONLY
    Parameter.POSITIONAL_OR_KEYWORD
    Parameter.KEYWORD_ONLY
    Parameter.VAR_POSITIONAL
    Parameter.VAR_KEYWORD

So the 'positional' in the TypeError messages corresponds to POSITIONAL_OR_KEYWORD.


[1] http://www.python.org/dev/peps/pep-0362/

We could start by establishing the argument/parameter distinction in the glossary.  Currently, the word "parameter" does not appear in the glossary, and the definition of "argument" blurs the distinction between the two:

For example, in the following definition of "argument"--

"argument: A value passed to a function or method, assigned to a named local variable in the function body. A function or method may have both positional arguments and keyword arguments in its definition..."

(from http://docs.python.org/dev/glossary.html#term-argument )

the second sentence is actually talking about parameters.

> IMHO as soon as you use terms like "receives" or "accepts", you are still talking about arguments.

Even PEP 362 is loose with its language in this regard.  For example, at the beginning of the "Signature Object" section:

"For each parameter accepted by the function it stores a Parameter object in its parameters collection."

And at the beginning of the "Parameter Object" section:

"Python's expressive syntax means functions can accept many different kinds of parameters with many subtle semantic differences."

Here is a proposed patch just to get the ball rolling on this.

Note that I'm proposing that we let ourselves use the word "standard" in place of "positional-or-keyword" when talking about parameters.  This is partly inspired by PEP 362, which says, "Parameter.POSITIONAL_OR_KEYWORD ... this is the standard binding behaviour for functions implemented in Python."

This patch only takes an initial crack at the glossary entries.  Once these are fleshed out, we can add additional :term: links and index directives.

On one hand it's good to have individual entries that can be referenced.
On the other hand I think it's important that people get the full picture, and having these definitions sparse in 4 or more distinct glossary entries doesn't help IMHO -- even if the reader follows all the cross-links.

I think it would be better to have a single entry somewhere (e.g. in the FAQs -- maybe it's too "advanced" for the tutorial), that:
  * explains the difference between arguments (what you pass) and parameters (what the function accepts);
  * lists the 5 kinds of parameters, providing an example for each;
  * lists the 2 kinds of arguments, providing an example for each;

I see 3 options here:
  1) we make this section and keep stub entries that link to it;
  2) we repeat the informations in both places (section and entries);
  3) we just keep the glossary entries;

If we pick 1 people might have to follow one more link.  Having a single "parameters and arguments" entry in the glossary might make this better by avoiding a redirect.
If we pick 2 there's duplication, and that's bad.
If we pick 3 I think we could at least explain the kinds of arguments in the "argument" entry and having stubs for "keyword args" and "positional args".  This will leave us with only two entries ("argument" and "parameter"), and with the initial problem that we don't know where to put the explanation of the difference between the two (in both? in a new entry? somewhere else? no parallel?).

I like option (3).  I attached a new patch using this approach.

As suggested, I made the glossary entries for "keyword argument" and "positional argument" into stubs.  So now there are just two substantive entries: one for "argument" and one for "parameter."  I also included in the parameter entry an example for each of the five parameter types.

I modified the last patch to use bullet lists and include more examples, and also added a FAQ entry to explain the difference between args and parameters.
I'll leave further comments on rietveld.

I have a number of comments but it is a holiday this weekend so I might not be able to get to it for a day or two.

I'm attaching a patch that preserves the structure of the previous patch but that builds on the wording and formatting.  The patch also addresses many of the comments on Rietveld.  I will also publish some comment replies on Rietveld (to the previous patch) that will give background on some of the changes made by this patch.

Attaching new patch to address Ezio's suggestions on Rietveld.  I will also respond to those comments on Rietveld shortly.

For some reason, Rietveld is erroring out every time I try to reply to one of the comments.  So I am pasting the reply below:

[Issue in the Rietveld tracker here:
 http://code.google.com/p/rietveld/issues/detail?id=394 ]

On 2012/11/26 22:07:50, ezio.melotti wrote:
> 
> Note that I took this from the pep.  The pep could get the same clarification
> (unless I made it more confusing than it was).

From what I have observed, PEPs tend to be left alone after they are accepted.  But that could simply be a misperception on my part.  What is the process for updating PEPs and whose approval is needed, etc?  In any case, that could be done as part of a separate issue.

New changeset 69d5d834c5cb by Chris Jerdonek in branch '3.2':
Improve argument/parameter documentation (issue #15990).
http://hg.python.org/cpython/rev/69d5d834c5cb

New changeset 40fd26a4206b by Chris Jerdonek in branch '3.3':
Merge from 3.2: improve argument/parameter documentation (issue #15990).
http://hg.python.org/cpython/rev/40fd26a4206b

New changeset 74d8a2a20c52 by Chris Jerdonek in branch 'default':
Merge from 3.3: improve argument/parameter documentation (issue #15990).
http://hg.python.org/cpython/rev/74d8a2a20c52

I realize now that this would also be good for 2.7.  I will try to do that tomorrow.

> Note that I took this from the pep.  The pep could get the same clarification
> (unless I made it more confusing than it was).

Reading the following, it seems that PEPs aren't generally clarified after becoming Final (as is PEP 362):

"In general, Standards track PEPs are no longer modified after they have reached the Final state."

(from http://www.python.org/dev/peps/pep-0001/#pep-maintenance )

PEP 1 doesn’t reflect current practice then.

The PEPs don't undergo major changes, but AFAIU typo fixes and minor clarifications/rephrasing are allowed.

Thanks for the clarification.  I will create an issue to clarify that part of PEP 1.  It should also say who is allowed to make such changes and whether/from whom approval is necessary, etc.

I just created issue 16574 to clarify PEP 1 with regard to the above.

Attaching a 2.7 version of the patch for this issue.

From the patch committed to Python 3, I removed mention of keyword-only parameters, inspect.Parameter, and PEP 362 (because all are specific to Python 3).

New changeset f44b8d69e5fc by Chris Jerdonek in branch '2.7':
Backport from 3.2: improve argument/parameter documentation (issue #15990).
http://hg.python.org/cpython/rev/f44b8d69e5fc

New changeset ecf3cd3af502 by Chris Jerdonek in branch '2.7':
Add additional links and index entries for "argument" and "parameter".
http://hg.python.org/cpython/rev/ecf3cd3af502

New changeset 31e1f0b7f42e by Chris Jerdonek in branch '3.2':
Add additional links and index entries for "argument" and "parameter".
http://hg.python.org/cpython/rev/31e1f0b7f42e

New changeset 7a4a1fc6b3ee by Chris Jerdonek in branch '3.3':
Merge from 3.2: add links and index entries for "argument" and "parameter."
http://hg.python.org/cpython/rev/7a4a1fc6b3ee

New changeset 10e4d28d0090 by Chris Jerdonek in branch 'default':
Merge from 3.3: add links and index entries for "argument" and "parameter."
http://hg.python.org/cpython/rev/10e4d28d0090