Skip to content

Document asterisk (*), splat or star operator #63224

Closed

Description

@techtonik
mannequin
BPO 19024
Nosy @rhettinger, @terryjreedy, @ncoghlan, @ezio-melotti

Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-07-02.22:30:14.505>
created_at = <Date 2013-09-15.13:18:38.616>
labels = ['easy', 'type-feature', 'docs']
title = 'Document asterisk (*), splat or star operator'
updated_at = <Date 2014-07-02.22:30:14.504>
user = 'https://bugs.python.org/techtonik'

bugs.python.org fields:

activity = <Date 2014-07-02.22:30:14.504>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-07-02.22:30:14.505>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2013-09-15.13:18:38.616>
creator = 'techtonik'
dependencies = []
files = []
hgrepos = []
issue_num = 19024
keywords = ['easy']
message_count = 10.0
messages = ['197772', '197863', '198236', '198238', '198260', '198261', '198267', '198289', '199015', '222139']
nosy_count = 9.0
nosy_names = ['rhettinger', 'terry.reedy', 'ncoghlan', 'techtonik', 'ezio.melotti', 'docs@python', 'mikehoy', 'madison.may', 'xcombelle']
pr_nums = []
priority = 'normal'
resolution = 'wont fix'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19024'
versions = ['Python 2.7', 'Python 3.3', 'Python 3.4']

Activity

  1. techtonik commented on Sep 15, 2013

    techtonikmannequin
    MannequinAuthor

    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

  2. added
    type-crashA hard crash of the interpreter, possibly with a core dump
    on Sep 15, 2013
  3. added
    type-featureA feature request or enhancement
    and removed
    type-crashA hard crash of the interpreter, possibly with a core dump
    on Sep 15, 2013
  4. MadisonMay commented on Sep 16, 2013

    MadisonMaymannequin
    Mannequin

    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.

  5. terryjreedy commented on Sep 22, 2013

    @terryjreedy
    Member

    Index entries for * and ** were added in bpo-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.

  6. rhettinger commented on Sep 22, 2013

    @rhettinger
    Contributor

    I concur with Terry.

  7. techtonik commented on Sep 22, 2013

    techtonikmannequin
    MannequinAuthor

    223 people + me out of 1422 disagree with you both.
    http://stackoverflow.com/questions/101268/hidden-features-of-python

  8. techtonik commented on Sep 22, 2013

    techtonikmannequin
    MannequinAuthor

    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.

  9. ncoghlan commented on Sep 22, 2013

    @ncoghlan
    Contributor

    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.

  10. terryjreedy commented on Sep 22, 2013

    @terryjreedy
    Member

    The StackOverflow question and answer about function calls is 5 years old and therefore out of date with respect to bpo-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.

  11. ezio-melotti commented on Oct 5, 2013

    @ezio-melotti
    Member

    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.

  12. terryjreedy commented on Jul 2, 2014

    @terryjreedy
    Member

    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.

  13. transferred this issue fromon Apr 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc direasytype-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions