classification
Title: Tutorial clarity: section 4.7.2, parameters and arguments
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: StMark, eric.araujo, ezio.melotti, georg.brandl, ggenellina, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2009-07-25 08:35 by StMark, last changed 2011-12-13 13:54 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue6570.diff ezio.melotti, 2011-11-08 21:12
issue6570-2.diff ezio.melotti, 2011-11-18 12:26 review
Messages (10)
msg90910 - (view) Author: Mark du Preez (StMark) Date: 2009-07-25 08:35
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
msg91218 - (view) Author: Gabriel Genellina (ggenellina) Date: 2009-08-03 07:06
I'll try to rephrase the section.
msg147317 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-08 21:12
Attached patch, please review.
msg147328 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-11-09 01:43
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 >
msg147329 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-09 01:53
> +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?
msg147332 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-11-09 03:51
>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.
msg147333 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-09 03:53
OK, now I got what you mean.

I'll try to come up with a better patch then :)
msg147863 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-18 12:26
Here is a new patch.
msg149279 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-12 09:14
Terry, does the latest patch look good to you?
msg149388 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-12-13 13:54
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
History
Date User Action Args
2011-12-13 13:54:39ezio.melottisetstatus: open -> closed
resolution: fixed
stage: commit review -> resolved
2011-12-13 13:54:06python-devsetnosy: + python-dev
messages: + msg149388
2011-12-12 09:14:44ezio.melottisetmessages: + msg149279
2011-11-18 12:26:39ezio.melottisetfiles: + issue6570-2.diff

messages: + msg147863
2011-11-09 03:53:43ezio.melottisetmessages: + msg147333
2011-11-09 03:51:46terry.reedysetmessages: + msg147332
2011-11-09 01:53:11ezio.melottisetmessages: + msg147329
2011-11-09 01:43:24terry.reedysetmessages: + msg147328
2011-11-08 21:12:31ezio.melottisetfiles: + issue6570.diff

assignee: docs@python -> ezio.melotti
versions: + Python 2.7, - Python 3.1
keywords: + patch
nosy: + ezio.melotti, eric.araujo

messages: + msg147317
stage: commit review
2011-03-09 03:14:18terry.reedysetnosy: + terry.reedy

versions: + Python 3.2, Python 3.3
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2009-08-03 07:06:22ggenellinasetnosy: + ggenellina
messages: + msg91218
2009-07-31 20:03:57terry.reedysettitle: Documentation Clarity -> Tutorial clarity: section 4.7.2, parameters and arguments
2009-07-25 08:35:39StMarkcreate