.append() Adds a Single Item

With.append(), you can add a number, list, tuple, dictionary, user-defined object, or any other object to an existing list. However, you need to keep in mind that.append() adds only a single item or object at a time:

>>>x=[1,2,3,4]>>>y=(5,6)>>>x.append(y)>>>x[1, 2, 3, 4, (5, 6)]

What happens here is that.append() adds the tuple objecty to the end of your target list,x. What if you want to add each item iny to the end ofx as an individual item and get[1, 2, 3, 4, 5, 6]? In that case, you can use.extend():

>>>x=[1,2,3,4]>>>y=(5,6,7)>>>x.extend(y)>>>x[1, 2, 3, 4, 5, 6, 7]>>>x=[1,2,3,4]>>>y=(5,6,7)>>># Equivalent to x.extend(y)>>>x[len(x):]=y>>>x[1, 2, 3, 4, 5, 6, 7]

.extend() takes an iterable as an argument, unpacks its items, and adds them to the end of your target list. This operation is equivalent tox[len(x):] = y, which is the same technique you saw in the previous section.

.append() ReturnsNone

In practice,.append() does its workin place by modifying and growing the underlying list. This means that.append() doesn’treturn a new list with an additional new item at the end. It returnsNone:

>>>x=[1,2,3,4]>>>y=x.append(5)>>>yisNoneTrue>>>x[1, 2, 3, 4, 5]

Like with several similar methods,.append() changes the underlying list in place. Trying to use the return value of.append() is a common mistake when it comes to learning howmutable sequence types work. Keeping this behavior of.append() in mind will help you prevent errors in your code.

Using.append()

One common use case of.append() is to completely populate an empty list using afor loop. Inside the loop, you can manipulate the data and use.append() to add successive results to the list. Say you need to create a function that takes a sequence of numbers and returns a list containing the square root of each number:

>>>importmath>>>defsquare_root(numbers):...result=[]...fornumberinnumbers:...result.append(math.sqrt(number))...returnresult...>>>numbers=[1,4,9,16,25,36,49,64,81]>>>square_root(numbers)[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]

Here, you definesquare_root(), which takes a list ofnumbers as an argument. Insidesquare_root(), you create an empty list calledresult and start afor loop that iterates over the items innumbers. In each iteration, you usemath.sqrt() to calculate the square root of the current number and then use.append() to add the result toresult. Once the loop finishes, you return the resulting list.

This way of populating lists is fairly common in Python. However, the language provides some convenient constructs that can make the process a lot more efficient andPythonic. One of these constructs is alist comprehension, which you’ll see in action in the next section.

Using a List Comprehension

In practice, you often replace.append() with alist comprehension when creating a list from scratch and populating it. With a list comprehension, you can reimplementsquare_root() like this:

>>>importmath>>>defsquare_root(numbers):...return[math.sqrt(number)fornumberinnumbers]...>>>numbers=[1,4,9,16,25,36,49,64,81]>>>square_root(numbers)[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]

The list comprehension insidesquare_root() creates a list containing the square root ofnumber for eachnumber innumbers. This reads almost like plain English. Also, this new implementation will be more efficient in terms of processing time than the implementation that uses.append() along with afor loop.

To turn.append() into a list comprehension, you just need to put its argument followed by the loop header (without the colon) inside a pair of square brackets.

Switching Back to.append()

Even though list comprehensions can be more readable and efficient than.append() for populating lists, there might be situations where.append() is a better choice.

Suppose you needsquare_root() to provide your users with detailed information about the progress of calculating the square root of the input list of numbers. To report the operation progress, you can useprint():

>>>importmath>>>defsquare_root(numbers):...result=[]...n=len(numbers)...fori,numberinenumerate(numbers):...print(f"Processing number:{number}")...result.append(math.sqrt(number))...print(f"Completed:{int((i+1)/n*100)}%")...returnresult...>>>numbers=[1,4,9,16,25,36,49,64,81]>>>square_root(numbers)Processing number: 1Completed: 11%...Processing number: 81Completed: 100%[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0]

Now think of how you can turn the body ofsquare_root() into a list comprehension. Usingprint() inside a list comprehension doesn’t seem coherent or even possible unless you wrap part of the code in a helper function. So, in this example, using.append() is the right choice.

The moral behind the above example is that there are some situations in which you can’t replace.append() with a list comprehension or with any other construct.

Implementing a Stack

Astack is adata structure that stores items on top of each other. Items come in and out of the stack in aLast-In/First-Out (LIFO) fashion. Typically, a stack implements two main operations:

1. push adds an item to the top, or end, of the stack.
2. pop removes and returns the item at the top of the stack.

In a list,.append() is equivalent to apush operation, so you can use it to push items onto the stack. Lists also provide.pop(), which optionally takes an integer index as an argument. It returns the item at that index in the underlying list and also removes the item:

>>>numbers=[1,2,3]>>>numbers.pop(1)2>>>numbers[1, 3]>>>numbers.pop()3>>>numbers[1]>>>numbers.pop()1>>>numbers[]>>>numbers.pop()Traceback (most recent call last):  File"<input>", line1, in<module>numbers.pop()IndexError:pop from empty list

If you supply an integer index as an argument to.pop(), then the method returns and removes the item at that index in the list. Calling.pop() without an argument returns the last item in the list. Note that.pop() also removes the item from the underlying list. Finally, if you call.pop() on an empty list, then you’ll get anIndexError.

With this knowledge, you’re ready to implement a stack using.append() and.pop(). Here’s a class that defines a stack. The class provides.push() and.pop() operations:

classStack:def__init__(self):self._items=[]defpush(self,item):self._items.append(item)defpop(self):try:returnself._items.pop()exceptIndexError:print("Empty stack")def__len__(self):returnlen(self._items)def__repr__(self):returnf"Stack({self._items})"

InStack, you first initialize theinstance attribute._items. This attribute holds an empty list that you’ll use to store the items in the stack. Then you code.push(), which implements thepush operation using.append() on._items.

You also implement thepop operation by calling.pop() on the underlying list,._items. In this case, you use atry andexcept block to handle theIndexError that occurs when you call.pop() on an empty list.

You take advantage of a couple ofspecial methods here. The special method.__len__() provides the required functionality for retrieving the length of the internal list._items. The special method.__repr__() allows you to provide a user-friendlystring representation of the stack when printing the data structure to the screen.

Here are some examples of how you can useStack in practice:

>>>stack=Stack()>>># Push items onto the top of the stack>>>stack.push(1)>>>stack.push(2)>>># User-friendly printing format>>>stackStack([1, 2])>>>print(stack)Stack([1, 2])>>># Retrieve the length of the stack>>>len(stack)2>>># Pop items from the top of the stack>>>stack.pop()2>>>stack.pop()1>>>stack.pop()Empty stack>>>stackStack([])

That’s it! You’ve coded a stack data structure that implements thepush andpop operations. It also provides functionality to get the length of the underlying list and to print the entire stack in a user-friendly manner.

Implementing a Queue

Queues are data structures that commonly manage their items in aFirst-In/First-Out (FIFO) fashion. Queues work like a pipe in which you push in new items at one end, and old items pop out from the other end.

Adding an item to the end of a queue is known as anenqueue operation, and removing an item from the front, or beginning, of a queue is known as adequeue operation.

You can enqueue items using.append() and dequeue them using.pop(). This time, you need to provide0 as an argument to.pop() just to make it retrieve the first item in the list instead of the last item. Here’s a class that implements a queue data structure using a list to store its items:

classQueue:def__init__(self):self._items=[]defenqueue(self,item):self._items.append(item)defdequeue(self):try:returnself._items.pop(0)exceptIndexError:print("Empty queue")def__len__(self):returnlen(self._items)def__repr__(self):returnf"Queue({self._items})"

This class is quite similar to yourStack. The main difference is that.pop() takes0 as an argument to return and removes thefirst item in the underlying list,._items, rather than the last.

The rest of the implementation is almost identical but uses appropriate names, such as.enqueue() for adding items and.dequeue() for removing them. You can useQueue the same way you usedStack in the above section: just call.enqueue() to add items and.dequeue() to retrieve and remove them.

array.append()

Python’sarray.array() provides a sequence-like data structure that can compactly represent an array of values. These values must be of the samedata type, which is limited to C-style data types, such as characters, integer numbers, and floating-point numbers.

array.array() takes the following two arguments:

Thedocumentation ofarray provides complete information about all the allowed type codes that you can use when creating arrays. The following example uses the"i" type code to create an array of integer numbers:

>>>fromarrayimportarray>>># Array of integer numbers>>>int_array=array("i",[1,2,3])>>>int_arrayarray('i', [1, 2, 3])>>>int_array[0]1>>>int_array[:2]array('i', [1, 2])>>>int_array[2]=4>>>int_arrayarray('i', [1, 2, 4])

To create an array, you need to provide a single-character code to define the data type of the values in the array. You can also provide an optional list of values with the appropriate type to initialize the array.

Arrays support most list operations, such asslicing andindexing. Like lists,array.array() also provides a method called.append(). This method works similarly to its list counterpart, adding a single value to the end of the underlying array. However, the value must have a data type that’s compatible with the existing values in the array. Otherwise, you’ll get aTypeError.

For example, if you have an array with integer numbers, then you can’t use.append() to add a floating-point number to that array:

>>>fromarrayimportarray>>>a=array("i",[1,2,3])>>>aarray('i', [1, 2, 3])>>># Add a floating-point number>>>a.append(1.5)Traceback (most recent call last):  File"<input>", line1, in<module>a.append(1.5)TypeError:integer argument expected, got float

If you try to add a floating-point number toa, then.append() fails with aTypeError. That’s because Python can’t automatically convert a floating-point number into an integer number without losing information.

In contrast, if you have an array with floating-point numbers and try to add integer numbers to it, then your operation will succeed:

>>>fromarrayimportarray>>>float_array=array("f",[1.0,2.0,3.0])>>>float_arrayarray('f', [1.0, 2.0, 3.0])>>># Add and integer number>>>float_array.append(4)>>>float_arrayarray('f', [1.0, 2.0, 3.0, 4.0])

Here, you use.append() to add an integer number to an array of floating-point numbers. That’s possible because Python can automatically convert integer numbers into floating-point numbers without losing information in the process.

deque.append() anddeque.appendleft()

collections.deque() is another data structure that implements a variation of.append(). Adeque is a generalization of a stack and a queue specially designed to support fast and memory-efficientappend andpop operations on both of its sides. So if you need to create a data structure with these features, then consider using a deque instead of a list.

collections.deque() takes the following two optional arguments:

If you provide a value tomaxlen, then your deque will only store up tomaxlen items. Once the deque is full, adding a new item will automatically cause the item at the opposite end of the deque to be discarded. On the other hand, if you don’t supply a value tomaxlen, then the deque can grow to an arbitrary number of items.

In deques,.append() also adds a single item to the end, or right side, of the underlying data structure:

>>>fromcollectionsimportdeque>>>d=deque([1,"a",3.0])>>>ddeque([1, 'a', 3.0])>>>d.append("b")>>>ddeque([1, 'a', 3.0, 'b'])

Like lists, deques can hold different types of items, so.append() adds arbitrary items to the end of the deque. In other words, with.append(), you can add any object to a deque.

Besides.append(), deques also provide.appendleft(), which adds a single item to the beginning, or left side, of a deque. Similarly, deques provide.pop() and.popleft() to remove items from the right and left side of the deque, respectively:

>>>fromcollectionsimportdeque>>>d=deque([1,"a",3.0])>>>d.appendleft(-1.0)>>>ddeque([-1.0, 1, 'a', 3.0])>>>d.pop()3.0>>>d.popleft()-1.0>>>ddeque([1, 'a'])

The call to.appendleft() adds-1.0 to the left side ofd. On the other hand,.pop() returns and removes the last item ind, and.popleft() returns and removes the first item. As an exercise, you can try to implement your own stack or queue using a deque instead of a list. To do this, you can take advantage of the examples you saw in the sectionCreating Stacks and Queues With Python’s .append().