[docs] [issue37684] list.extend docs inaccurate

[wim glenn]

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

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

----------
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>
<https://bugs.python.org/issue37684>
_______________________________________