(original) (raw)

changeset: 72808:352d075839f7 user: Georg Brandl georg@python.org date: Sat Oct 08 18:32:40 2011 +0200 files: Doc/library/stdtypes.rst Doc/tutorial/datastructures.rst Objects/listobject.c description: Closes #12192: Document that mutating list methods do not return the instance (original patch by Mike Hoy). diff -r d4ce850b06b7 -r 352d075839f7 Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst Fri Oct 07 22:47:08 2011 +0200 +++ b/Doc/library/stdtypes.rst Sat Oct 08 18:32:40 2011 +0200 @@ -15,6 +15,10 @@ 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 diff -r d4ce850b06b7 -r 352d075839f7 Doc/tutorial/datastructures.rst --- a/Doc/tutorial/datastructures.rst Fri Oct 07 22:47:08 2011 +0200 +++ b/Doc/tutorial/datastructures.rst Sat Oct 08 18:32:40 2011 +0200 @@ -19,13 +19,13 @@ .. 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 @@ .. 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 @@ .. 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 @@ >>> 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 @@ 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 @@ .. rubric:: Footnotes -.. [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();``. + +.. [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*. diff -r d4ce850b06b7 -r 352d075839f7 Objects/listobject.c --- a/Objects/listobject.c Fri Oct 07 22:47:08 2011 +0200 +++ b/Objects/listobject.c Sat Oct 08 18:32:40 2011 +0200 @@ -2329,16 +2329,16 @@ 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(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*); /georg@python.org