[docs] [issue37684] list.extend docs inaccurate

wim glenn report at bugs.python.org
Thu Jul 25 15:47:06 EDT 2019

New submission from wim glenn <wim.glenn at gmail.com>:

>From https://docs.python.org/3/tutorial/datastructures.html#more-on-lists :

        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:

assignee: docs at python
components: Documentation
messages: 348450
nosy: docs at python, wim.glenn
priority: normal
severity: normal
status: open
title: list.extend docs inaccurate
versions: Python 2.7, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

Python tracker <report at bugs.python.org>

More information about the docs mailing list