list.extend docs inaccurate

[wimglenn]

BPO	37684
Nosy	@rhettinger, @wimglenn, @aeros
PRs	bpo-37684: Improved list.extend example in datastructures docs #14951

^{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 2019-07-26.06:18:19.287>
created_at = <Date 2019-07-25.19:47:06.614>
labels = ['3.7', '3.8', '3.9', 'docs']
title = 'list.extend docs inaccurate'
updated_at = <Date 2019-07-26.20:44:27.821>
user = 'https://github.com/wimglenn'

bugs.python.org fields:

activity = <Date 2019-07-26.20:44:27.821>
actor = 'aeros'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-07-26.06:18:19.287>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2019-07-25.19:47:06.614>
creator = 'wim.glenn'
dependencies = []
files = []
hgrepos = []
issue_num = 37684
keywords = ['patch']
message_count = 6.0
messages = ['348450', '348467', '348470', '348471', '348500', '348526']
nosy_count = 4.0
nosy_names = ['rhettinger', 'docs@python', 'wim.glenn', 'aeros']
pr_nums = ['14951']
priority = 'normal'
resolution = 'rejected'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue37684'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']

[wimglenn]

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)

[rhettinger]

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

[aeros]

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?

[aeros]

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.

[wimglenn]

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

[aeros]

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).