document PEP 448: unpacking generalization

[benjaminp]

BPO	24136
Nosy	@warsaw, @terryjreedy, @pfmoore, @vstinner, @tjguk, @benjaminp, @ezio-melotti, @bitdancer, @berkerpeksag, @vadmium, @zware, @zooba, @NeilGirdhar, @JelleZijlstra, @supriyantomaftuh
Files	whatsnew.diff wn2.diff wn2.diff reference_calls_syntax_update.diff: Update of the function call expression syntax. replace_sequence_with_iterable.diff: Replace "sequence" with "iterable" in regard to the assigned object in the assignment statement. issue24136-expressions.patch: revised patch for call syntax in the language reference unpacking-doc.patch

^{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 2016-06-12.07:17:55.838>
created_at = <Date 2015-05-06.13:18:47.604>
labels = ['easy', 'type-feature', 'docs']
title = 'document PEP 448: unpacking generalization'
updated_at = <Date 2016-06-12.07:17:55.837>
user = 'https://github.com/benjaminp'

bugs.python.org fields:

activity = <Date 2016-06-12.07:17:55.837>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-06-12.07:17:55.838>
closer = 'martin.panter'
components = ['Documentation']
creation = <Date 2015-05-06.13:18:47.604>
creator = 'benjamin.peterson'
dependencies = []
files = ['39370', '39561', '39562', '39918', '39919', '43302', '43339']
hgrepos = []
issue_num = 24136
keywords = ['patch', 'easy']
message_count = 19.0
messages = ['242668', '243160', '244417', '246381', '246385', '246393', '246446', '246452', '246485', '246675', '261616', '263262', '267790', '267792', '267822', '268183', '268290', '268312', '268337']
nosy_count = 19.0
nosy_names = ['barry', 'terry.reedy', 'paul.moore', 'vstinner', 'tim.golden', 'benjamin.peterson', 'ezio.melotti', 'r.david.murray', 'docs@python', 'python-dev', 'berker.peksag', 'martin.panter', 'zach.ware', 'steve.dower', 'NeilGirdhar', 'moigagoo', 'JelleZijlstra', 'supriyanto maftuh', 'supriyantomaftuh']
pr_nums = []
priority = 'high'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue24136'
versions = ['Python 3.5', 'Python 3.6']

[benjaminp]

PEP-448 has been implemented (bpo-2292), but the documentation hasn't been updated. Updating the documentation will improve looking through

Doc/reference/*

and making sure the documentation (and grammar) for calls and assignments is updated for PEP-448's new syntax.

I'm marking this as "easy" because it might be a good first bug.

[NeilGirdhar]

Just updated the "what's new". Also, thank you for adding my name to Misc/Acks. Should we also add Joshua Landau's name? He helped me quite a bit with the implementation, and he wrote the PEP.

[NeilGirdhar]

Simplified functools.partial documentation.

[moigagoo]

Hi!

I'd like to update the docs with the examples of the new syntax usage. This is my first contribution to the Python docs, so I'd like to ask for some assistance.

I'm going to start with adding an example to the tutorial (https://docs.python.org/3.5/tutorial/introduction.html#lists). I wanted to demonstrate the new syntax with string too (https://docs.python.org/3.5/tutorial/introduction.html#strings), but it turned out to produce somewhat unexpected results:

>>> s = 'And now'
>>> first, *rest = s
>>> # I expected it to be synonymous
>>> # to ``first, rest = s[0], s[1:]``
>>> # ``first`` is expected to be 'A',
>>> # ``rest`` is expected to be 'nd now'.
>>> # ``first`` is 'A', as expected:
>>> first
'A'
>>> # But ``rest`` is implicitly turned into a list:
>>> rest
['n', 'd', ' ', 'n', 'o', 'w', ' ', 'f', 'o', 'r', ' ', 's', 'o', 'm', 'e', 't', 'h', 'i', 'n', 'g', ' ', 'c', 'o', 'm', 'p', 'l', 'e', 't', 'e', 'l', 'y', ' ', 'd', 'i', 'f', 'f', 'e', 'r', 'e', 'n', 't']

Is this behavior intended? Why wasn't first converted into ['A'] as well? Am I just not supposed to use the new unpacking with strings?

Thanks,
Konstantin

[vadmium]

Yes I think it is expected and documented that the leftovers are turned into a list. See <https://docs.python.org/3.5/reference/simple_stmts.html#index-6\>. I originally had similar confusion, expectating the starred target to become a tuple, because people often use tuple-like syntax, but:

>>> generator_expression = (2**i for i in range(4))
>>> (one, *a_list, eight) = generator_expression
>>> a_list  # Not a tuple!
[2, 4]

One thing in the section I linked above that should also be fixed is that the assigned object may be any iterable, not just a sequence.

About changing the tutorial, just be careful you don’t add unnecessary complication too early. The original * and ** syntax for function parameters is not mentioned until <https://docs.python.org/3.5/tutorial/controlflow.html#more-on-defining-functions\>. Later, argument unpacking: <https://docs.python.org/3.5/tutorial/controlflow.html#unpacking-argument-lists\>. Assignment unpacking doesn’t seem to mentioned at all (not that I am saying it should be). It might be higher priority to update the main reference documentation first.

[moigagoo]

@vadmium thanks for the assistance! I'll kick off with the reference then.

P.S. Am I the only one who doesn't receive any emails from the tracker? I never got the registration link or a follow-up notification from this issue. Am I missing something?

P.P.S. I'm not yet familiar with the local etiquette, so please forgive me if I'm unintentionally breaking some rules. Is @mentioning OK?

[NeilGirdhar]

I don't receive emails from the tracker anymore either and I have no idea why that is.

[vadmium]

FWIW, I still emails from the tracker, even the ones with my own comments and changes. All I can suggest is check the address you have set, check for spam, etc.

I don’t @mentioning will do anything here. But as long as the person is in the nosy list they _should_ get an email (in theory :).

[NeilGirdhar]

Copied from closed bpo-24240:

Since Grammar/Grammar relies on semantic postprocessing in ast.c,
it would be nice to have an update of the (human readable) Grammar
in the language reference docs.

[moigagoo]

I've updated the Calls syntax reference in reference/expressions and the assignment object description in reference/simple_stmts.

Please tell me if I'm generally doing OK. If I'm not, please guide me to the right direction.