# Tuples

This reading presents one more built-in type, the tuple, and then shows how lists, dictionaries, and tuples work together.

One note: there is no consensus on how to pronounce “tuple”. Some people say “tuh-ple”, which rhymes with “supple”. But in the context of programming, most people say “too-ple”, which rhymes with “quadruple”.

## Tuples are Immutable

A tuple is a sequence of values. The values can be any type, and they are indexed by integers, so in that respect tuples are a lot like lists. The important difference is that tuples are immutable.

Syntactically, a tuple is a comma-separated list of values:

>>> t = 'a', 'b', 'c', 'd', 'e'


Although it is not necessary, it is common to enclose tuples in parentheses:

>>> t = ('a', 'b', 'c', 'd', 'e')


To create a tuple with a single element, you have to include a final comma:

>>> t1 = 'a',
>>> type(t1)
<class 'tuple'>


A value in parentheses is not a tuple:

>>> t2 = ('a')
>>> type(t2)
<class 'str'>


Another way to create a tuple is the built-in function tuple. With no argument, it creates an empty tuple:

>>> t = tuple()
>>> t
()


If the argument is a sequence (string, list or tuple), the result is a tuple with the elements of the sequence:

>>> t = tuple('lupins')
>>> t
('l', 'u', 'p', 'i', 'n', 's')


Because tuple is the name of a built-in function, you should avoid using it as a variable name.

Most list operators also work on tuples. The bracket operator indexes an element:

>>> t = ('a', 'b', 'c', 'd', 'e')
>>> t[0]
'a'


And the slice operator selects a range of elements.

>>> t[1:3]
('b', 'c')


But if you try to modify one of the elements of the tuple, you get an error:

>>> t[0] = 'A'
TypeError: object doesn't support item assignment


Because tuples are immutable, you can’t modify the elements. But you can replace one tuple with another:

>>> t = ('A',) + t[1:]
>>> t
('A', 'b', 'c', 'd', 'e')


This statement makes a new tuple and then makes t refer to it.

The relational operators work with tuples and other sequences; Python starts by comparing the first element from each sequence. If they are equal, it goes on to the next elements, and so on, until it finds elements that differ. Subsequent elements are not considered (even if they are really big).

>>> (0, 1, 2) < (0, 3, 4)
True
>>> (0, 1, 2000000) < (0, 3, 4)
True


## Tuple Assignment

It is often useful to swap the values of two variables. With conventional assignments, you have to use a temporary variable. For example, to swap a and b:

>>> temp = a
>>> a = b
>>> b = temp


This solution is cumbersome; tuple assignment is more elegant:

>>> a, b = b, a


The left side is a tuple of variables; the right side is a tuple of expressions. Each value is assigned to its respective variable. All the expressions on the right side are evaluated before any of the assignments.

The number of variables on the left and the number of values on the right have to be the same:

>>> a, b = 1, 2, 3
ValueError: too many values to unpack


More generally, the right side can be any kind of sequence (string, list or tuple). For example, to split an email address into a user name and a domain, you could write:

>>> addr = 'monty@python.org'


The return value from split is a list with two elements; the first element is assigned to uname, the second to domain.

>>> uname
'monty'
>>> domain
'python.org'


## Tuples as Return Values

Strictly speaking, a function can only return one value, but if the value is a tuple, the effect is the same as returning multiple values. For example, if you want to divide two integers and compute the quotient and remainder, it is inefficient to compute x//y and then x%y. It is better to compute them both at the same time.

The built-in function divmod takes two arguments and returns a tuple of two values, the quotient and remainder. You can store the result as a tuple:

>>> t = divmod(7, 3)
>>> t
(2, 1)


Or use tuple assignment to store the elements separately:

>>> quot, rem = divmod(7, 3)
>>> quot
2
>>> rem
1


Here is an example of a function that returns a tuple:

def min_max(t):
return min(t), max(t)


max and min are built-in functions that find the largest and smallest elements of a sequence. min_max computes both and returns a tuple of two values.

## Lists and Tuples

zip is a built-in function that takes two or more sequences and interleaves them. The name of the function refers to a zipper, which interleaves two rows of teeth.

This example zips a string and a list:

>>> s = 'abc'
>>> t = [0, 1, 2]
>>> zip(s, t)
<zip object at 0x7f7d0a9e7c48>


The result is a zip object that knows how to iterate through the pairs. The most common use of zip is in a for loop:

>>> for pair in zip(s, t):
...     print(pair)
...
('a', 0)
('b', 1)
('c', 2)


A zip object is a kind of iterator, which is any object that iterates through a sequence. Iterators are similar to lists in some ways, but unlike lists, you can’t use an index to select an element from an iterator.

If you want to use list operators and methods, you can use a zip object to make a list:

>>> list(zip(s, t))
[('a', 0), ('b', 1), ('c', 2)]


The result is a list of tuples; in this example, each tuple contains a character from the string and the corresponding element from the list.

If the sequences are not the same length, the result has the length of the shorter one.

>>> list(zip('Anne', 'Elk'))
[('A', 'E'), ('n', 'l'), ('n', 'k')]


You can use tuple assignment in a for loop to traverse a list of tuples:

t = [('a', 0), ('b', 1), ('c', 2)]
for letter, number in t:
print(number, letter)


Each time through the loop, Python selects the next tuple in the list and assigns the elements to letter and number. The output of this loop is:

0 a
1 b
2 c


If you combine zip, for and tuple assignment, you get a useful idiom for traversing two (or more) sequences at the same time. For example, has_match takes two sequences, t1 and t2, and returns True if there is an index i such that t1[i] == t2[i]:

def has_match(t1, t2):
for x, y in zip(t1, t2):
if x == y:
return True
return False


If you need to traverse the elements of a sequence and their indices, you can use the built-in function enumerate:

for index, element in enumerate('abc'):
print(index, element)


The result from enumerate is an enumerate object, which iterates a sequence of pairs; each pair contains an index (starting from 0) and an element from the given sequence. In this example, the output is

0 a
1 b
2 c


Again.

## Dictionaries and Tuples

Dictionaries have a method called items that returns a sequence of tuples, where each tuple is a key-value pair.

>>> d = {'a':0, 'b':1, 'c':2}
>>> t = d.items()
>>> t
dict_items([('c', 2), ('a', 0), ('b', 1)])


The result is a dict_items object, which is an iterator that iterates the key-value pairs. You can use it in a for loop like this:

>>> for key, value in d.items():
...     print(key, value)
...
c 2
a 0
b 1


As you should expect from a dictionary, the items are in no particular order.

Going in the other direction, you can use a list of tuples to initialize a new dictionary:

>>> t = [('a', 0), ('c', 2), ('b', 1)]
>>> d = dict(t)
>>> d
{'a': 0, 'c': 2, 'b': 1}


Combining dict with zip yields a concise way to create a dictionary:

>>> d = dict(zip('abc', range(3)))
>>> d
{'a': 0, 'c': 2, 'b': 1}


The dictionary method update also takes a list of tuples and adds them, as key-value pairs, to an existing dictionary.

It is common to use tuples as keys in dictionaries (primarily because you can’t use lists). For example, a telephone directory might map from last-name, first-name pairs to telephone numbers. Assuming that we have defined last, first and number, we could write:

directory[last, first] = number


The expression in brackets is a tuple. We could use tuple assignment to traverse this dictionary.

for last, first in directory:
print(first, last, directory[last,first])


This loop traverses the keys in directory, which are tuples. It assigns the elements of each tuple to last and first, then prints the name and corresponding telephone number.

There are two ways to represent tuples in a state diagram. The more detailed version shows the indices and elements just as they appear in a list. For example, the tuple ('Cleese', 'John') would appear as follows.

But in a larger diagram you might want to leave out the details. For example, a diagram of the telephone directory might appear as follows.

Here the tuples are shown using Python syntax as a graphical shorthand. The telephone number in the diagram is the complaints line for the BBC, so please don’t call it.

## Sequences of Sequences

I have focused on lists of tuples, but almost all of the examples in this chapter also work with lists of lists, tuples of tuples, and tuples of lists. To avoid enumerating the possible combinations, it is sometimes easier to talk about sequences of sequences.

In many contexts, the different kinds of sequences (strings, lists and tuples) can be used interchangeably. So how should you choose one over the others?

To start with the obvious, strings are more limited than other sequences because the elements have to be characters. They are also immutable. If you need the ability to change the characters in a string (as opposed to creating a new string), you might want to use a list of characters instead.

Lists are more common than tuples, mostly because they are mutable. But there are a few cases where you might prefer tuples:

1. In some contexts, like a return statement, it is syntactically simpler to create a tuple than a list.
2. If you want to use a sequence as a dictionary key, you have to use an immutable type like a tuple or string.
3. If you are passing a sequence as an argument to a function, using tuples reduces the potential for unexpected behavior due to aliasing.

Because tuples are immutable, they don’t provide methods like sort and reverse, which modify existing lists. But Python provides the built-in function sorted, which takes any sequence and returns a new list with the same elements in sorted order, and reversed, which takes a sequence and returns an iterator that traverses the list in reverse order.

## Sorting Sequences

Functions like sorted include an optional parameter called the key that allows you to specify how the list should be sorted. A common use case of this is sorting a list of tuples by a specific index. For example, we might have a list of contacts where each contact consists of a first and last name.

>>> contacts = [("Jean", "Grey"), ("Charles", "Xavier"), ("Scott", "Summers")]


Now suppose we have two functions that extract out the first and last names from each tuple. These would be simple functions and could be defined by:

def first(tup):
return tup[0]

def last(tup):
return tup[1]


The first function takes a tuple as a parameter and returns the first element of the tuple and the last function returns the second element.

We can now use these functions to sort the list of contacts in a particular way:

>>> sorted(contacts, key=last)
[('Jean', 'Grey'), ('Scott', 'Summers'), ('Charles', 'Xavier')]
>>> sorted(contacts, key=first)
[('Charles', 'Xavier'), ('Jean', 'Grey'), ('Scott', 'Summers')]


This optional key parameter also exists in the list method sort.

## Glossary

tuple
An immutable sequence of elements.
tuple assignment
An assignment with a sequence on the right side and a tuple of variables on the left. The right side is evaluated and then its elements are assigned to the variables on the left.
gather
An operation that collects multiple arguments into a tuple.
scatter
An operation that makes a sequence behave like multiple arguments.
zip object
The result of calling a built-in function zip; an object that iterates through a sequence of tuples.
iterator
An object that can iterate through a sequence, but which does not provide list operators and methods.

## Self Checks

### Self Check

Write a function called most_frequent that takes a string and prints the letters in decreasing order of frequency.

Hint: Remember the histogram function from a previous reading?

### Challenge Problem

1. Write a program that reads a word list (e.g. words.txt) and prints all the sets of words that are anagrams.

Here is an example of what the output might look like:

['deltas', 'desalt', 'lasted', 'salted', 'slated', 'staled']
['retainers', 'ternaries']
['generating', 'greatening']
['resmelts', 'smelters', 'termless']


Hint: You might want to build a dictionary that maps from a collection of letters to a list of words that can be spelled with those letters. The question is, how can you represent the collection of letters in a way that can be used as a key?

2. Modify the previous program so that it prints the longest list of anagrams first, followed by the second longest, and so on.

3. In Scrabble a “bingo” is when you play all seven tiles in your rack, along with a letter on the board, to form an eight-letter word. What collection of 8 letters forms the most possible bingos?

#### Acknowledgment:

This reading was originally written by Allen Downey in his open source book Think Python 2e. Downey's book is licensed under the GNU Free Documentation License, which allows users to copy, modify, and distribute the book.

This reading was modified by Titus H. Klinge in 2021 and presented above under the same license in order to better serve the students of this course.