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.