classification
Title: solidify argument/parameter terminology
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Arfrever, chris.jerdonek, docs@python, eric.araujo, ezio.melotti, mark.dickinson, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2012-09-20 19:24 by chris.jerdonek, last changed 2012-12-25 23:00 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue-15990-1-default.patch chris.jerdonek, 2012-11-21 12:49 review
issue-15990-2-default.patch chris.jerdonek, 2012-11-22 02:50 review
issue-15990-3-default.patch ezio.melotti, 2012-11-22 15:21 review
issue-15990-4-default.patch chris.jerdonek, 2012-11-25 02:58 review
issue-15990-5-default.patch chris.jerdonek, 2012-11-28 02:17 review
issue-15990-5-2.7.patch chris.jerdonek, 2012-11-29 19:44
Messages (23)
msg170834 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-20 19:24
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 ).
msg170876 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-21 10:08
> "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.
msg170878 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-09-21 10:46
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/
msg170911 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-21 20:05
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.
msg170912 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-21 20:06
> 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."
msg176055 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-21 12:49
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.
msg176061 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-21 15:18
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?).
msg176092 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-22 02:50
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.
msg176110 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-22 15:21
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.
msg176120 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-22 18:44
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.
msg176328 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-25 02:58
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.
msg176507 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-28 02:17
Attaching new patch to address Ezio's suggestions on Rietveld.  I will also respond to those comments on Rietveld shortly.
msg176508 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-28 02:42
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.
msg176532 - (view) Author: Roundup Robot (python-dev) Date: 2012-11-28 10:52
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
msg176534 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-28 11:03
I realize now that this would also be good for 2.7.  I will try to do that tomorrow.
msg176575 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-28 21:18
> 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 )
msg176578 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-28 22:01
PEP 1 doesn’t reflect current practice then.
msg176579 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-28 22:04
The PEPs don't undergo major changes, but AFAIU typo fixes and minor clarifications/rephrasing are allowed.
msg176589 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-28 23:53
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.
msg176599 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-29 00:57
I just created issue 16574 to clarify PEP 1 with regard to the above.
msg176672 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-11-29 19:44
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).
msg176679 - (view) Author: Roundup Robot (python-dev) Date: 2012-11-30 03:04
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
msg178170 - (view) Author: Roundup Robot (python-dev) Date: 2012-12-25 23:00
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
History
Date User Action Args
2012-12-25 23:00:52python-devsetmessages: + msg178170
2012-11-30 03:05:46chris.jerdoneksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2012-11-30 03:04:34python-devsetnosy: + python-dev
messages: + msg176679
2012-11-29 19:44:38chris.jerdoneksetfiles: + issue-15990-5-2.7.patch

messages: + msg176672
2012-11-29 00:57:43chris.jerdoneksetmessages: + msg176599
2012-11-28 23:53:40chris.jerdoneksetmessages: + msg176589
2012-11-28 22:04:03ezio.melottisetmessages: + msg176579
2012-11-28 22:01:33eric.araujosetmessages: + msg176578
2012-11-28 21:18:39chris.jerdoneksetmessages: + msg176575
2012-11-28 17:06:06gvanrossumsetnosy: - gvanrossum, python-dev
2012-11-28 11:03:39chris.jerdoneksetmessages: + msg176534
versions: + Python 2.7, Python 3.2
2012-11-28 10:52:56python-devsetnosy: + python-dev
messages: + msg176532
2012-11-28 02:42:55chris.jerdoneksetmessages: + msg176508
2012-11-28 02:17:35chris.jerdoneksetfiles: + issue-15990-5-default.patch

messages: + msg176507
2012-11-25 02:58:51chris.jerdoneksetfiles: + issue-15990-4-default.patch

messages: + msg176328
2012-11-22 18:44:51chris.jerdoneksetmessages: + msg176120
2012-11-22 15:21:46ezio.melottisetfiles: + issue-15990-3-default.patch
nosy: + eric.araujo
messages: + msg176110

2012-11-22 02:50:57chris.jerdoneksetfiles: + issue-15990-2-default.patch

messages: + msg176092
2012-11-21 15:18:09ezio.melottisetmessages: + msg176061
2012-11-21 12:49:05chris.jerdoneksetfiles: + issue-15990-1-default.patch
versions: + Python 3.3, Python 3.4
messages: + msg176055

keywords: + patch
stage: patch review
2012-09-21 20:06:58chris.jerdoneksetmessages: + msg170912
2012-09-21 20:05:40chris.jerdoneksetmessages: + msg170911
2012-09-21 10:46:32mark.dickinsonsetmessages: + msg170878
2012-09-21 10:08:50ezio.melottisetnosy: + gvanrossum
messages: + msg170876
2012-09-20 21:10:40Arfreversetnosy: + Arfrever
2012-09-20 20:24:11terry.reedysetnosy: + terry.reedy
2012-09-20 20:07:47ezio.melottisetnosy: + ezio.melotti
type: enhancement
2012-09-20 20:03:04mark.dickinsonsetnosy: + mark.dickinson
2012-09-20 19:24:17chris.jerdonekcreate