Why does append() always return None in Python?
One word of advice would be to avoid using key words or functions as variable names. In your code above, you use list as a variable:
list = [1, 2, 3]
I would advise against using list
as a variable name as list is actually already defined as a builtin type. As ChaseTheSun and squiguy pointed out, there isn't much more to it then
lst = [1, 2, 3]
lst.append(4)
print(lst) ## [1, 2, 3, 4]
append
is a mutating (destructive) operation (it modifies the list in place instead of of returning a new list). The idiomatic way to do the non-destructive equivalent of append
would be
>>> l = [1,2,3]
>>> l + [4]
[1,2,3,4]
>>> l
[1,2,3]
to answer your question, my guess is that if append
returned the newly modified list, users might think that it was non-destructive, ie they might write code like
m = l.append("a")
n = l.append("b")
and expect n
to be [1,2,3,"b"]
list.append()
is an in-place operation, meaning that it modifies the state of the list
, instead of returning a new list
object.
All functions in Python return None
unless they explicitly return something else. The method a.append()
modifies a
itself, which means that there's nothing to return.
Another way you can see this behavior is in the difference between sorted(some_list)
and some_list.sort()
.
If you don't want to append "x"
to a
, then you'll need to use the second snippet, or you can simply concatenate:
>>> a = [1, 2, 3, 4]
>>> b = a[1:] + ["x"]
>>> b
[2, 3, 4, 'x']
To further clarify:
>>> a = [1, 2, 3, 4]
>>> b = a[1:].append("x")
>>> a
[1, 2, 3, 4]
>>> a[1:]
[2, 3, 4]
>>> type(b)
<class 'NoneType'>
Notice that b
is None
, since the list.append()
method returns None
. Notice also that a
wasn't actually modified. This is because you were appending to a slice of a
, but not actually saving that slice anywhere. Notice what happens if you do a.append("x")
:
>>> b = a.append("x")
>>> a
[1, 2, 3, 4, 'x']
>>> type(b)
<class 'NoneType'>
b
is still None
, but now a
got modified.
It is a convention in Python that methods that mutate sequences return None
.
Consider:
>>> a_list = [3, 2, 1]
>>> print a_list.sort()
None
>>> a_list
[1, 2, 3]
>>> a_dict = {}
>>> print a_dict.__setitem__('a', 1)
None
>>> a_dict
{'a': 1}
>>> a_set = set()
>>> print a_set.add(1)
None
>>> a_set
set([1])
Starting in Python 3.3, this is now more explicitly documented:
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
.
The Design and History FAQ gives the reasoning behind this design decision (with respect to lists):
Why doesn’t
list.sort(
) return the sorted list?In situations where performance matters, making a copy of the list just to sort it would be wasteful. Therefore,
list.sort()
sorts the list in place. In order to remind you of that fact, it does not return the sorted list. This way, you won’t be fooled into accidentally overwriting a list when you need a sorted copy but also need to keep the unsorted version around.In Python 2.4 a new built-in function –
sorted()
– has been added. This function creates a new list from a provided iterable, sorts it and returns it.