Hi

In section 4.7.2 of the tutorial documentation, we suddenly find the
following paragraph:

"In general, an argument list must have any positional arguments
followed by any keyword arguments, where the keywords must be chosen
from the formal parameter names. It’s not important whether a formal
parameter has a default value or not. No argument may receive a value
more than once — formal parameter names corresponding to positional
arguments cannot be used as keywords in the same calls. Here’s an
example that fails due to this restriction:"

To a beginner who is reading a tutorial to learn how to use this
language for the first time, it is completely overwhelming. What is a
"positional argument" vs a "keyword argument" and what is a "formal
parameter name"?

None of these things have been explained up until this point and an
understanding of their meaning is required to make sense of this paragraph.

Please consider revising this section.

Thank you.

Mark

I'll try to rephrase the section.

Attached patch, please review.

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):

+accepts one :term:`positional argument` (``voltage``) and three
+:term:`keyword arguments <keyword argument>` (``state``, ``action``,
+and ``type``).  

This is simply false. An argument for voltage is required, the other three are optional. I suggest something like the followinga:

Calls to this function require 1 to 4 arguments. An argument for voltage is required; arguements for the other three parameters are optional because they have default arguments specified.

Arguments can be matched to parameters by either position or 'keyword', where the keyword is the name of a parameter. The two conditions are that each parameter is matched to at most one argument and that keyword matches follow positional matches. The following matches 4 argumnts to the corresponding parameters by position:
  parrot(100, 'loose', 'skid', 'American Red')
This matches the same arguments by keyword (parameter name):
  parrot(state='loose', voltage=100, type='American Red', action='loose') 
Any order is acceptable for such 'keyword arguments'.
A call can mix the two matching methods. This
parrot(100, action='loose')
passes one argument each way and lets 'state' and 'type' get their default values of 'a stiff' and 'Norwegian Blue'.

< add minimal set of bad calls >

> +accepts one :term:`positional argument` (``voltage``) and three
> +:term:`keyword arguments <keyword argument>` (``state``, ``action``,
> +and ``type``).  
>
> This is simply false. An argument for voltage is required, the other
> three are optional. I suggest something like the followinga:

That part refers to the function signature, not the function call.  I tried to avoid using the term "function signature" to avoid introducing yet another term, but maybe the two things should be separated a bit more.

I also tried to avoid the use of 'parameters' (the 'names' in the function signature) and 'arguments' (the actual values passed to the function when it's called) to keep the things simple and also because not everyone agrees on this terminology.

Would adding 'required' before 'positional' and 'optional' before 'keyword arguments' be ok?

>Would adding 'required' before 'positional' and 'optional' before 'keyword arguments' be ok?

No! What is false in the original and the above is the equation and confusion of 'required' with 'positional' and 'optional' with 'keyword'. Required/optional is an argument property for all calls to a function as determined by the function definition.  Position/keyword is an argument property for each particular call as determined by the call itself (or the programmer thereof). The two contrasts are logically independent even if there is empirical correlation in the practice of some programmers. All arguments for parrot, both the required voltage argument and the three optional arguments, can be passed by either position or keyword. This is shown by the examples that pass both types of arguments both ways.

(Similarly, both required and optional args can be defined as (pass-by-)keyword-only arguments,
  >>> def f(a,b=2,*,c,d=4): return a,b,c,d
  >>> f(1,c=3)
  (1, 2, 3, 4)
though such possibilities are not relevant here.)

>> An argument for voltage is required, the other three are optional.

Prefix the above with "When calling this function,".

> That part refers to the function signature, not the function call.

I was specifically referring to calls. All parameters in a signature require an argument. A function signature may (optionally ;-) define an argument for any parameter as optional *in function call expressions* by giving an alternate default argument for the parameter.

OK, now I got what you mean.

I'll try to come up with a better patch then :)

Here is a new patch.

Terry, does the latest patch look good to you?

New changeset d60856651139 by Ezio Melotti in branch '2.7':
#6570: clarify tutorial section about keyword arguments.
http://hg.python.org/cpython/rev/d60856651139

New changeset 44ca4264dc88 by Ezio Melotti in branch '3.2':
#6570: clarify tutorial section about keyword arguments.
http://hg.python.org/cpython/rev/44ca4264dc88

New changeset 207408428242 by Ezio Melotti in branch 'default':
#6570: merge with 3.2.
http://hg.python.org/cpython/rev/207408428242