Is the behaviour of Python's list += iterable documented anywhere?

Question

It would appear that in Python, list += x works for any iterable x:

In [6]: l = []

In [7]: l += [1]

In [8]: l += (2, 3)

In [9]: l += xrange(5)

In [10]: l
Out[10]: [1, 2, 3, 0, 1, 2, 3, 4]

Is this behaviour documented anywhere?

To contrast this with list + x, the latter only works if x is also a list. This is spelled out in the documentation.

Answer 1

From Guido van Rossum:

It works the same way as .extend() except that it also returns self. I can't find docs explaining this. :-(

Here is the relevant source code taken from listobject.c:

list_inplace_concat(PyListObject *self, PyObject *other) {      PyObject *result;       result = listextend(self, other);      if (result == NULL)          return result;      Py_DECREF(result);      Py_INCREF(self);      return (PyObject *)self; } 

I've raised a bug report to have the documentation fixed: http://bugs.python.org/issue16701

Answer 2

It is now documented in Python 3.4+ and Python 2.7:

4.6.3. Mutable Sequence Types

The operations in the following table are defined on mutable sequence types. The collections.abc.MutableSequence ABC is provided to make it easier to correctly implement these operations on custom sequence types.

[Below] s is an instance of a mutable sequence type, t is any iterable object and x is an arbitrary object that meets any type and value restrictions imposed by s (for example, bytearray only accepts integers that meet the value restriction 0 <= x <= 255).

---

s.extend(t) or s += t

extends s with the contents of t (for the most part the same as s[len(s):len(s)] = t)

So it is now documented that for any mutable sequence type s, s += t is synonymous with s.extend(t).

Answer 3

No (Guido confirms; thanks to Ashwini Chaudhary). The behaviour of += for sequences in general is underspecified. I conclude that it is not required by the specification that x + y where x is a list, and y some other iterable be an error (so other implementations could choose to allow it), and that other implementations could restrict += to require homogenous operands.

However, the reasons not to do this are obvious: python in general tries to do the right thing with operands, rather than requiring rigid type equality. The real mystery is why heterogenous addition is not allowed with lists.

Update: I've never really thought about the nonhomogenous addition problem, largely because itertools.chain is pretty much a complete solution to the problem.

Comments from those more familiar with Python's internals are welcome to explain why addition is required to be homogenous. (Question here: Why must Python list addition be homogenous?)