New submission from Terry J. Reedy:
The Tutorial section More on Lists
https://docs.python.org/3.4/tutorial/datastructures.html#more-on-lists includes
list.pop but ignores it in the example and final comment. I think the examples
should be augmented and the comment modified.
1. (simplest) End the example block with
>>> a.pop()
1234.5
>>> a
[-1, 1, 66.25, 333, 333]
2. The comment says "You might have noticed that methods like insert, remove or
sort that modify the list have no return value printed – they return None. [1]
This is a design principle for all mutable data structures in Python." [The
footnote says "[1] Other languages may return the mutated object, which allows
method chaining, such as d->insert("a")->remove("b")->sort();."]
Inserting 'only' before 'modify' makes the statement true even now with .pop
added. I think 'the default' should be added before 'None', but that would be
optional. I do not think .pop needs to be explicitly mentioned here since the
point of the comment is to explain the lack of a printed return value, and .pop
does have a printed return value.
----------
assignee: docs@python
components: Documentation
messages: 218857
nosy: docs@python, ncoghlan, terry.reedy
priority: normal
severity: normal
stage: needs patch
status: open
title: Tutorial: examples and comment about mutation methods
type: behavior
versions: Python 2.7, Python 3.4, Python 3.5
_______________________________________
Python tracker <[email protected]>
<http://bugs.python.org/issue21545>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
