Tutorial: Add example code for list.extend()

Ideas
1

In the Data Structures section of the tutorial, I think it would be particularly helpful to provide of an example of list.extend() being used:

>>> round_table = ['Arthur']
>>> knights = ('Bedevere', 'Lancelot', 'Gallahad', 'Robin')
>>> round_table.extend(knights)
>>> round_table
['Arthur', 'Bedevere', 'Lancelot', 'Gallahad', 'Robin']

The tutorial is typically the section of the documentation most aimed at newcomers to the language, and is filled with significantly more code examples in comparison to the rest of the documentation. However, there are currently no examples of list.extend() being utilized on that page, and the description alone for the method may not be particularly clear for new users:

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

Code examples should be used sparingly, but I think extend() has more complexity involved in comparison the other list methods listed on that page to justify the usage. The usage of an example will help to solidify a reader’s understanding of the method, particularly if they are newer to programming and have not seen the usage of similar methods or functions in other languages.

I plan on opening an issue on bpo and attaching a PR to adjust this section of the tutorial accordingly. But, I figured that it might be worthwhile to obtain some feedback first.

Edit: Fixed link.

Edit2: Slightly modified the example to use a tuple for knights instead of a list. The performance improvement is small, but it doesn’t make much sense to use a list when the container is not going to be modified.

2

IMHO, i add the example of code or not just depend on one single rule: the user(including newcomer) need know the detail or not? If the ans is yes, pls go ahead :slight_smile:

PS: If you have an idea plan to write a newcomer’s guide book, pls add the refs in https://devguide.python.org/exploring/?highlight=cpython-source-code-guide#additional-references

3

I would say that list.extend() is a fairly fundamental method for list, and is definitely relevant to know for users. It’s not quite as widely used as list.append() or list.pop(), but I think it’s important enough to have a brief example. When working with larger sets of data, it’s useful for users to know how to make use of list.extend(iterable) rather than relying solely on for item in iterable: list.append(item).

I don’t think it’s worth going into optimization details in the tutorial, but essentially, as the number of items being added increases, extend() becomes more efficient. The purpose of showing the example is not to cover optimization though, it’s just so that users can become aware of how the method actually works if they see it being used.

This sounds like an interesting idea, but I’m not currently planning on writing an extensive standalone guide. My primary focus has been on improving and updating the existing documentation.

1 Like