classification
Title: documentation index entries for * and **
Type: Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, eric.araujo, eric.snow, ezio.melotti, georg.brandl, petere, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2011-07-11 12:03 by petere, last changed 2011-07-30 18:31 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
python-doc-index-**.patch petere, 2011-07-11 12:03 review
Messages (13)
msg140113 - (view) Author: Peter Eisentraut (petere) * Date: 2011-07-11 12:03
The existing documentation index entries for * and ** only point to their use in function definitions but not to their use in function calls.  I was looking for the latter, and it was difficult to find without this.  Here is a small patch to add the additional entries.
msg140466 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-15 19:25
This is just the tip of the iceberg as far as needed symbol index entries goes. Nearly 3 years ago, I wrote a Python 3 symbol glossary "Python3 Syntax Symbol Uses" that was complete as far as I knew then. I think most of the entries there should have a corresponding index entry in the official docs. Link to download/view is

https://code.google.com/p/xploro/downloads/detail?name=PySymbols.html&can=1&q=

That has 7 entries for '*':
  *: In function parameter list, make following unstarred names keyword only.
P *parameter_name: Function parameter bound to a tuple of extra positional arguments, any following unstarred names are keyword only.
P *iterable: In a call, unpack iterable items as arguments.
P *assignment_target: Starred target in assignment statement gets extra items from iterable.
I number1 * number2: Number multiplication operator.
I n * sequence or sequence * n: Operator to concatenate n copies of sequence.
S from module import *: Import all public (non-private) names from the module. 

 /P/I/S == 'nofix', prefix, infix, suffix.

I have been planning to work on a patch 'sometime', but would be happy if someone else grabbed the above and ran with it (and expanded the title of this issue).

I believe existing docs can get additions like this.
msg140484 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-16 09:30
Peter, doesn't your patch also refer to the meaning of * and ** in function definitions?  

I would argue that the missing reference is to a paragraph further down:

   [...] If the syntax *expression appears in the function call, expression must evaluate to a sequence. Elements from this sequence [...]

Terry, the glossary you compiled certainly looks comprehensive. However, I wouldn't delay local fixes like the one discussed here until "the grand scheme" is committed.
msg140598 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-18 15:49
> [...] If the syntax *expression appears in the function call,
> expression must evaluate to a sequence.

An iterable :)
msg140611 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-18 19:14
I would not propose to do everything in one grand patch as it would be way too much to review all at once. A somewhat separate subissue is whether there should be however many separate issues over the next however many years or one master issue with multiple patches.

The existing patch is enough to review for now. It needs changes and should add everything needed just for * and **. And there may be some unwritten policy issues.

I agree that the directive for * should be moved as Eli says.
I think 'statement' should be changed to 'function calls', or maybe 'in function calls' or 'function call operator' for both * and **.
The same directives should be added to the tutorial at the top and middle of Tutorial 4.7.4 Unpacking Argument Lists.
The existing * and ** 'statement' directives for defs in both tutorial and reference should become 'function defs' (or 'definitions') or 'in def statement'.
The existing * 'operator' directive should be 'number multiplication' or 'number multiplication operator' or at least 'number operator'.
Perhaps it (and the following) should be duplicated in the tutorial.
A new * 'sequence repetition* directive should be added.
The existing ** 'operator' directive should be 'number exponentiation'.
New 'assigment' and 'import' directives are needed.

I think *all* the entries for a given symbol should be considered together so that they can be properly differentiated. We should minimize duplicates that appear like this -- 'statement, [1]' -- and such duplicates should refer to the *same* usage. 

Policy issues:

I think 'statement' should be reserved for statement keywords like def, class, etc. Things in statements should be at least qualified as 'in <specific> statement.

I see that plain 'operator' is currently used for most or all operators. I think they should at least be qualified as to category -- number operator, seqeunce operator, comparision operator, logic operator, etc. This might tell users all they need to know and would separate overloaded operators like '*'.

Both general suggestions follow other usages. Classes are specified as 'class in <modname>', not just 'class'. Functions are specified not just with '()' but also 'in <modname>' Expanding 'statement' to 'in <keyword> statement' or something would be in the same spirit. Methods are specified as '<class> method', not just 'method'. Operators should get the same differentiation with at least '<optype> operator' if not more detail.

[separate issue note: 'as' seems not to be indexed.]

Adding Georg as I am suggesting a deviation from certain precedents (and conformance to others).
msg140612 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-07-18 19:21
> expression must evaluate to a sequence.

To be clear, Eli quoted the doc correctly and Eric correctly suggested that 'sequence' needs to be updated to 'iterable' (in at least two places). Since the patch for this issue will be adding something just above, it could just as well make this change also.
msg140717 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-20 03:25
Peter, would you like to submit a corrected patch?
msg141342 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-07-29 11:47
New changeset 8328fe952303 by Eli Bendersky in branch '2.7':
Issue #12531: add index entries to documentation of * and ** in function calls
http://hg.python.org/cpython/rev/8328fe952303
msg141343 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-29 11:48
I've committed a fix into 2.7, taking Terry's advice ("in function calls" subsection instead of "statement") and Eric's sequence/iterable correction into account.

If this looks OK, I will commit a similar fix to the 3.x branches as well.
msg141359 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-07-29 12:39
Looks good to me.

One tip for commits: it’s often better to let a line exceed 80 characters in order to make for a smaller diff.  Here, only one word was changed but four lines were marked as changed, which makes reviews longer.  Lines are rewrapped when doing larger rewritings.
msg141364 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-07-29 12:46
Éric - when I was just starting contributing patches to Python, I was strictly disciplined by veteran devs to stay within 80 chars no matter what :-)
msg141419 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-07-30 04:09
New changeset a8aa918041c2 by Eli Bendersky in branch '3.2':
Issue #12531: add index entries to documentation of * and ** in function calls
http://hg.python.org/cpython/rev/a8aa918041c2

New changeset 221ca00121ef by Eli Bendersky in branch 'default':
Merge from 3.2: Issue #12531: add index entries to documentation of * and ** in function calls
http://hg.python.org/cpython/rev/221ca00121ef
msg141451 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-07-30 18:31
New changeset 8862ec62f9ee by Ezio Melotti in branch '3.2':
#12531: Fix spaces and markup.
http://hg.python.org/cpython/rev/8862ec62f9ee

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

New changeset 952e83a8bc78 by Ezio Melotti in branch '2.7':
#12531: Fix spaces.
http://hg.python.org/cpython/rev/952e83a8bc78
History
Date User Action Args
2011-07-30 18:31:36python-devsetmessages: + msg141451
2011-07-30 13:32:06eric.araujosetstage: patch review -> resolved
2011-07-30 04:10:19eli.benderskysetstatus: open -> closed
resolution: fixed
2011-07-30 04:09:39python-devsetmessages: + msg141419
2011-07-29 12:46:07eli.benderskysetmessages: + msg141364
2011-07-29 12:39:52eric.araujosetmessages: + msg141359
2011-07-29 11:48:14eli.benderskysetmessages: + msg141343
2011-07-29 11:47:08python-devsetnosy: + python-dev
messages: + msg141342
2011-07-20 03:25:10eli.benderskysetmessages: + msg140717
2011-07-18 19:21:27terry.reedysetmessages: + msg140612
2011-07-18 19:14:07terry.reedysetnosy: + georg.brandl

messages: + msg140611
stage: patch review
2011-07-18 15:59:16eric.araujosetnosy: + terry.reedy, eric.snow

versions: + Python 2.7, Python 3.2
2011-07-18 15:49:41eric.araujosetnosy: + eric.araujo, - terry.reedy, eric.snow

messages: + msg140598
versions: - Python 2.7, Python 3.2
2011-07-16 09:30:20eli.benderskysetmessages: + msg140484
2011-07-15 20:36:02eric.snowsetnosy: + eric.snow
2011-07-15 19:25:50terry.reedysetnosy: + terry.reedy

messages: + msg140466
versions: + Python 2.7, Python 3.2
2011-07-13 12:15:48ezio.melottisetnosy: + ezio.melotti
2011-07-12 06:30:34eli.benderskysetnosy: + eli.bendersky
2011-07-11 12:03:43peterecreate