homepage

This issue tracker has been migrated to GitHub , and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Document asterisk (*), splat or star operator
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, madison.may, mikehoy, ncoghlan, rhettinger, techtonik, terry.reedy, xcombelle
Priority: normal Keywords: easy

Created on 2013年09月15日 13:18 by techtonik, last changed 2022年04月11日 14:57 by admin. This issue is now closed.

Messages (10)
msg197772 - (view) Author: anatoly techtonik (techtonik) Date: 2013年09月15日 13:18
I'd say this is a critical documentation bug that leads to head bang when you try to figure out what does '*' in code means.
This bug is two fold:
1. Define a dedicated place in documentation for '*' operator with examples. I propose http://docs.python.org/3/library/stdtypes.html chapter with a name like "Special Operations" or "Function Argument Operations" or "Function Argument Operators"
 
2. Make '*', 'asterisk', 'splat', 'star' operator searchable
http://docs.python.org/3/search.html?q=*
http://docs.python.org/3/search.html?q=asterisk
http://docs.python.org/3/search.html?q=splat
http://docs.python.org/3/search.html?q=star+operator
Good?
References:
http://stackoverflow.com/questions/2322355/proper-name-for-python-operator
http://stackoverflow.com/questions/5239856/foggy-on-asterisk-in-python
http://stackoverflow.com/questions/2921847/python-once-and-for-all-what-does-the-star-operator-mean-in-python
http://stackoverflow.com/questions/287085/what-do-args-and-kwargs-mean
http://stackoverflow.com/search?q=[python]+%2Bkwargs+is%3Aquestion
msg197863 - (view) Author: Madison May (madison.may) * Date: 2013年09月16日 02:26
http://docs.python.org/3/tutorial/controlflow.html#arbitrary-argument-lists
http://docs.python.org/3/tutorial/controlflow.html#unpacking-argument-lists 
The above links do a so-so of explaining the splat operator, although I agree that the docs for '*' could be improved.
msg198236 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013年09月22日 00:33
Index entries for * and ** were added in #12531 so that both are indexed as operators, in function definitions, in function calls, and in the tutorial. If any of these places need improvement, there should be specific suggestions.
I do not think there should be separate documentation for the * symbol. It would only duplicate what is already present. There are many symbols with multiple uses.
Changing html search search for symbols, if possible, would be a different issue. But returning every use of '*' in the docs would not seem too useful. For anything in the index, the index in more useful.
msg198238 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2013年09月22日 01:18
I concur with Terry.
msg198260 - (view) Author: anatoly techtonik (techtonik) Date: 2013年09月22日 11:12
223 people + me out of 1422 disagree with you both.
http://stackoverflow.com/questions/101268/hidden-features-of-python 
msg198261 - (view) Author: anatoly techtonik (techtonik) Date: 2013年09月22日 11:18
To narrow the point of conflict, I say that argument unpacking *operators*
should have a prominent place in Python documentation that people can link
to. Current page
http://docs.python.org/3/tutorial/controlflow.html#unpacking-argument-lists is
about functionality, not about operators, and therefore usage of these
while studying Python code can not be tracked back to documentation. Which
is why it is hidden.
msg198267 - (view) Author: Alyssa Coghlan (ncoghlan) * (Python committer) Date: 2013年09月22日 11:48
Unfortunately, there's currently no good place for this kind of detailed syntax reference documentation to go. The library reference doesn't cover syntax, the tutorial doesn't go into detailed semantics, and the language reference is written more for language implementors than it is for users.
My Python User's Reference project (http://svn.python.org/view/sandbox/trunk/userref/README.txt?view=markup) was designed to fill that gap, but I never found the time to do the ReST conversion myself, and nobody ever expressed interest in helping out with it, so it's now five years out of date.
Creating a cut down version of that as the "Python Syntax Reference" might be a reasonable approach. However, it's a project that could easily start life outside the core CPython repository.
msg198289 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013年09月22日 16:14
The StackOverflow question and answer about function calls is 5 years old and therefore out of date with respect to #12531, which specifically added index entries for function calls.
Perhaps my Python 3 symbol glossary "Python3 Syntax Symbol Uses"
https://code.google.com/p/xploro/downloads/detail?name=PySymbols.html&can=1&q=
could be expanded a bit or combined with other text, as well as being a basis for adding index entries.
msg199015 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013年10月05日 23:38
> 223 people + me out of 1422 disagree with you both.
Note that those votes doesn't necessarily mean "I didn't know about the feature" -- they might mean "I find this feature useful/I like this feature". Features like decorators have even more votes and I don't think they are "hidden" features.
> Current page
 http://docs.python.org/3/tutorial/controlflow.html#unpacking-argument-lists is
> about functionality, not about operators
These operators are documented here:
http://docs.python.org/3/reference/expressions.html#index-36
http://docs.python.org/3/reference/expressions.html#index-37
This can be found from the doc index (which admittedly is not the most obvious place where to look):
http://docs.python.org/3/genindex-Symbols.html
If the problem is the content of the docs, you can suggest what exactly should be improved (and how). If the problem is the discoverability, you should open a separate issue on the Sphinx bug tracker about allowing the search of operators.
msg222139 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014年07月02日 22:30
I have started indexing symbol uses on other issue and will continue after GSOC. I am closing this as there is nothing specific to do.
History
Date User Action Args
2022年04月11日 14:57:50adminsetgithub: 63224
2014年07月02日 22:30:14terry.reedysetstatus: open -> closed
resolution: wont fix
messages: + msg222139

stage: needs patch -> resolved
2013年10月05日 23:38:19ezio.melottisetmessages: + msg199015
2013年09月30日 16:43:21xcombellesetnosy: + xcombelle
2013年09月22日 16:14:12terry.reedysetmessages: + msg198289
2013年09月22日 11:48:06ncoghlansetnosy: + ncoghlan
messages: + msg198267
2013年09月22日 11:18:34techtoniksetmessages: + msg198261
2013年09月22日 11:12:36techtoniksetmessages: + msg198260
2013年09月22日 01:18:36rhettingersetnosy: + rhettinger
messages: + msg198238
2013年09月22日 00:33:39terry.reedysetnosy: + terry.reedy
messages: + msg198236
2013年09月18日 02:08:44mikehoysetnosy: + mikehoy
2013年09月16日 02:26:28madison.maysetnosy: + madison.may
messages: + msg197863
2013年09月16日 02:11:58georg.brandlsetmessages: - msg197774
2013年09月15日 13:58:17ezio.melottisetversions: - Python 2.6, Python 3.1, Python 3.2, Python 3.5
nosy: + ezio.melotti

keywords: + easy
type: crash -> enhancement
stage: needs patch
2013年09月15日 13:50:20techtoniksetmessages: + msg197774
2013年09月15日 13:18:38techtonikcreate

AltStyle によって変換されたページ (->オリジナル) /