cpython: 352d075839f7 (original) (raw)

Mercurial > cpython

changeset 72808:352d075839f7

Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). [#12192]

line wrap: on

line diff

--- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -15,6 +15,10 @@ interpreter. The principal built-in types are numerics, sequences, mappings, classes, instances and exceptions. +Some collection classes are mutable. The methods that add, subtract, or +rearrange their members in place, and don't return a specific item, never return +the collection instance itself but None. + Some operations are supported by several object types; in particular, practically all objects can be compared, tested for truth value, and converted to a string (with the :func:repr function or the slightly different

--- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -19,13 +19,13 @@ objects: .. method:: list.append(x) :noindex:

• Add an item to the end of the list; equivalent to a[len(a):] = [x].

• Add an item to the end of the list. Equivalent to a[len(a):] = [x].

.. method:: list.extend(L) :noindex:

• Extend the list by appending all the items in the given list; equivalent to

• Extend the list by appending all the items in the given list. Equivalent to a[len(a):] = L.

@@ -40,8 +40,8 @@ objects: .. method:: list.remove(x) :noindex:

• Remove the first item from the list whose value is x. It is an error if there
• is no such item.

• Remove the first item from the list whose value is x. It is an error if
• there is no such item.

.. method:: list.pop([i]) @@ -70,13 +70,14 @@ objects: .. method:: list.sort() :noindex:

• Sort the items of the list, in place.

• Sort the items of the list in place.

.. method:: list.reverse() :noindex:

• Reverse the elements of the list, in place.

• Reverse the elements of the list in place. +

An example that uses most of the list methods:: @@ -99,6 +100,10 @@ An example that uses most of the list me >>> a [-1, 1, 66.25, 333, 333, 1234.5] +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. + .. tut-lists-as-stacks: @@ -438,7 +443,7 @@ using a non-existent key. Performing list(d.keys()) on a dictionary returns a list of all the keys used in the dictionary, in arbitrary order (if you want it sorted, just use -sorted(d.keys()) instead). [1] To check whether a single key is in the +sorted(d.keys()) instead). [2]_ To check whether a single key is in the dictionary, use the :keyword:in keyword. Here is a small example using a dictionary:: @@ -622,6 +627,9 @@ interpreter will raise a :exc:TypeError[](#l2.67) [](#l2.68) .. rubric:: Footnotes[](#l2.69) [](#l2.70) -.. [1] Calling ``d.keys()`` will return a :dfn:dictionary view` object. It +.. [1] Other languages may return the mutated object, which allows method

•   chaining, such as ``d->insert("a")->remove("b")->sort();``.[](#l2.73)

+ +.. [2] Calling d.keys() will return a :dfn:dictionary view object. It supports operations like membership test and iteration, but its contents are not independent of the original dictionary -- it is only a view.

--- a/Objects/listobject.c +++ b/Objects/listobject.c @@ -2329,16 +2329,16 @@ PyDoc_STRVAR(clear_doc, PyDoc_STRVAR(copy_doc, "L.copy() -> list -- a shallow copy of L"); PyDoc_STRVAR(append_doc, -"L.append(object) -- append object to end"); +"L.append(object) -> None -- append object to end"); PyDoc_STRVAR(extend_doc, -"L.extend(iterable) -- extend list by appending elements from the iterable"); +"L.extend(iterable) -> None -- extend list by appending elements from the iterable"); PyDoc_STRVAR(insert_doc, "L.insert(index, object) -- insert object before index"); PyDoc_STRVAR(pop_doc, "L.pop([index]) -> item -- remove and return item at index (default last).\n" "Raises IndexError if list is empty or index is out of range."); PyDoc_STRVAR(remove_doc, -"L.remove(value) -- remove first occurrence of value.\n" +"L.remove(value) -> None -- remove first occurrence of value.\n" "Raises ValueError if the value is not present."); PyDoc_STRVAR(index_doc, "L.index(value, [start, [stop]]) -> integer -- return first index of value.\n" @@ -2348,7 +2348,7 @@ PyDoc_STRVAR(count_doc, PyDoc_STRVAR(reverse_doc, "L.reverse() -- reverse IN PLACE"); PyDoc_STRVAR(sort_doc, -"L.sort(key=None, reverse=False) -- stable sort IN PLACE"); +"L.sort(key=None, reverse=False) -> None -- stable sort IN PLACE"); static PyObject list_subscript(PyListObject, PyObject*);