classification
Title: list.extend docs inaccurate
Type: Stage: resolved
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: aeros, docs@python, rhettinger, wim.glenn
Priority: normal Keywords: patch

Created on 2019-07-25 19:47 by wim.glenn, last changed 2019-07-26 20:44 by aeros. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 14951 closed wim.glenn, 2019-07-25 19:56
Messages (6)
msg348450 - (view) Author: wim glenn (wim.glenn) * Date: 2019-07-25 19:47
From https://docs.python.org/3/tutorial/datastructures.html#more-on-lists :

    list.extend(iterable)
        Extend the list by appending all the items from the iterable.
        Equivalent to a[len(a):] = iterable.

The "equivalent" is not very good. Consider 

    def gen():
        yield 1
        yield 2
        raise Exception

Using `a.extend(gen())` would mutate `a`. Using slice assignment would still consume the generator, but `a` would not be modified.

I propose a different example to use to describe the behaviour of extend:

    for x in iterable:
        a.append(x)
msg348467 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-07-26 06:18
Thanks for the suggestion, but I'm going to reject this.

The existing rough equivalent isn't exact but it does do a better job of communicating a bulk update rather than a series of appends.  Also, it isn't far from how the C list_extend() is actually implemented
msg348470 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-07-26 07:02
Raymond, what were your thoughts on the alternative suggestion I posted on the GitHub PR? My suggestion might have been too different from the original PR, but personally I think it's a bit more appropriate for the tutorial than the existing example. Would it be worth opening a separate PR for it, or do you prefer the existing example?
msg348471 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-07-26 07:03
Clarification: Since I posted two potential suggestions, I'm referring to the one using the interpreter, not the one that changed it into two lines and added indentation.
msg348500 - (view) Author: wim glenn (wim.glenn) * Date: 2019-07-26 16:09
Raymond,

I understand that consecutive appends could potentially trigger multiple resizes behind the scenes, and so it's not really showing that extend is more like a bulk update as you mentioned. That's a good point!

However I think it's a more important consideration to make sure the equivalent actually gives a correct *result*. Can you suggest an alternative code snippet to use which is correct, or perhaps soften the language claiming that the code is equivalent?

For what it's worth, the stdtypes.html docs writes that extend is "for the most part the same as" the slice assignment:

https://docs.python.org/3/library/stdtypes.html#mutable-sequence-types
msg348526 - (view) Author: Kyle Stanley (aeros) * (Python triager) Date: 2019-07-26 20:44
Upon further consideration, I think the code example suggestion I made using the interpreter could be in a separate PR or issue and doesn't have to replace the the current "Equivalent to ..." portion. I'll open a separate PR for that (which isn't attached to this issue). Apologies if that at all derailed this conversation, as it might not be directly relevant (even if it's within the same section).
History
Date User Action Args
2019-07-26 20:44:27aerossetmessages: + msg348526
2019-07-26 16:09:31wim.glennsetmessages: + msg348500
2019-07-26 07:03:45aerossetmessages: + msg348471
2019-07-26 07:02:40aerossetnosy: + aeros
messages: + msg348470
2019-07-26 06:18:19rhettingersetstatus: open -> closed

nosy: + rhettinger
messages: + msg348467

resolution: rejected
stage: patch review -> resolved
2019-07-25 19:56:34wim.glennsetkeywords: + patch
stage: patch review
pull_requests: + pull_request14720
2019-07-25 19:47:06wim.glenncreate