A Python tuple is one of Python’s three built-in sequence data types, the others being lists and range objects. A Python tuple shares a lot of properties with the more commonly known Python list:
- It can hold multiple values in a single variable
- It’s ordered: the order of items is preserved
- A tuple can have duplicate values
- It’s indexed: you can access items numerically
- A tuple can have an arbitrary length
But there are important differences:
- A tuple is immutable; it can not be changed once you defined it.
- A tuple is defined using optional parentheses () instead of square brackets []
- Since a tuple is immutable, it can be hashed, and thus it can act as the key in a dictionary
Table of contents
Creating a Python tuple
We create tuples from individual values using optional parentheses (round brackets) like this:
>>> my_numbers = (1, 2, 3)
>>> the_same = 1, 2, 3
>>> my_strings = ('Hello', 'World')
>>> my_mixed_tuple = ('Hello', 123, True)
Like everything in Python, tuples are objects and have a class that defines them. A tuple can also be created by using the tuple() constructor from that class. It allows any Python iterable type as an argument. In the following example, we create a tuple from a list:
>>> tuple([0,1,2]) (0, 1, 2) >>>
Now you know how to convert a Python list to a tuple as well!
Which method is best?
It’s not always easy for Python to infer if you’re using regular parentheses, or if you’re trying to create a tuple. To demonstrate, let’s define a tuple holding only one item:
>>> t = (1) 1 >>> t = (1, ) (1,)
On the first try, Python sees the number one, surrounded by useless parentheses, so Python strips down the expression to the number 1. In the second try, however, we added a comma, explicitly signaling to Python that we are creating a tuple with just one element.
A tuple with just one item is useless for most use cases, but it demonstrates how Python recognizes a tuple: because of the comma.
If we can use tuple(), why is there a second method as well? The other notation obviously is more concise, but it also has its value because you can use it to concisely unpack multiple lists into a tuple, in this way:
>>> l1 = [1, 2, 3] >>> l2 = [4, 5, 6] >>> t = (*l1, *l2) >>> t (1, 2, 3, 4, 5, 6)
The leading * operator unpacks the lists into individual elements. This unpacking trick works for all iterable types if you were wondering!
Multiple assignment using a Python tuple
There’s another way of unpacking a tuple, or any other iterable, as well. It’s useful when assigning multiple variables at once. It works like this:
>>> person = ('Erik', 38, True)
>>> name, age, registered = person
>>> name
'Erik'
>>> _
Just like using the *, this type of unpacking works for all iterable types in Python, including lists and strings.
As I explained in the Python trick on returning multiple values from a Python function, unpacking tuples comes in very handy when returning multiple values from a function. It’s a neat way of returning more than one value, without having to resort to data classes or dictionaries:
def get_user_by_id(userid):
# fetch user from database
# ....
return name, age
name, age = get_user_by_id(4)
Indexed access
A tuple can be accessed using index numbers like [0] and [1]:
>>> my_mixed_tuple = 'Hello', 123, True >>> my_mixed_tuple[0] 'Hello' >>> my_mixed_tuple[2] True >>> _
Append to a Python Tuple
Because a tuple is immutable, you can not append data to a tuple after it’s created. For the same reason, you can’t remove data from a tuple either. You can, of course, create a new tuple from the old one, and append the extra item(s) to it this way:
>>> t1 = (1, 2, 3) >>> t = (*t1, 'Extra', 'Items') >>> t (1, 2, 3, 'Extra', 'Items')
What we did is unpack t1, create a new tuple with the unpacked values and two extra strings, and assign the result to t again.
Get tuple length
The len() function works on Python tuples just like it works on all other iterable types:
>>> t = 1, 2, 3 >>> len(t) 3
Python Tuple vs List
The biggest difference between a Python tuple and a Python list is the fact that a List is mutable, while a tuple is not. After defining a tuple, you can not add or remove values. In contrast, a list allows you to add or remove values at will. This property can be an advantage; you can see it as write protection. If a piece of data is not meant to change, using a tuple can prevent errors. After all, 6 months from now you might have forgotten that the data should not be changed. Using a tuple prevents mistakes.
Another advantage is that tuples are faster, or at least that is what people say. I have not seen proof, but it makes sense. Since it’s an immutable data type, a tuple’s internal implementation can be simpler than lists. After all, they don’t need ways to grow larger or insert elements at random positions, which usually is implemented as a linked list. From what I understand, a tuple uses a simple array-like structure in the CPython implementation.
Python Tuple vs Set
The biggest difference between tuples and sets is the fact that a tuple can have duplicates while a set can’t. The entire purpose of a set is its inability to contain duplicates. It’s a great tool for deduplicating your data.
Converting Python tuples
Convert Tuple to List
Python’s List, in other languages often called an array, is mutable. If you need to convert a tuple to a list, use one of the following methods.
The cleanest and most readable way is to use the list() constructor:
>>> t = 1, 2, 3 >>> list(t) [1, 2, 3]
A more concise, but less readable method is to use unpacking. This can sometimes come in handy though because it allows you to unpack multiple tuples into one list, or add some extra values otherwise:
>>> t = 1, 2, 3 >>> l = [*t] >>> l [1, 2, 3] >>> l = [*t, 4, 5, 6] >>> l [1, 2, 3, 4, 5, 6]
Convert tuple to set
Analogous to the conversion to a list, we can use set() to convert a tuple to a set:
>>> t = (1, 2, 3)
>>> s = set(t)
>>> s
{1, 2, 3}
Here, too, we can use unpacking:
>>> s = {*t}
>>> s
{1, 2, 3}
Convert tuple to string
Like most objects in Python, a tuple has a so-called dunder method, called __str__, which converts the tuple into a string. When you want to print a tuple, you don’t need to do so explicitly. Print will call this method on any object that is not a string. In other cases, you can use the str() constructor to get the string representation of a tuple:
>>> t = (1, 2, 3) >>> print(t) (1, 2, 3) >>> str(t) '(1, 2, 3)'
