Python's tuple Data Type: A Deep Dive With Examples

Getting Started With Python’s tuple Data Type

The built-in tuple data type is probably the most elementary sequence available in Python. Tuples are immutable and can store a fixed number of items. For example, you can use tuples to represent Cartesian coordinates (x, y), RGB colors (red, green, blue), records in a database table (name, age, job), and many other sequences of values.

In all these use cases, the number of elements in the underlying tuple is fixed, and the items are unchangeable. You may find several situations where these two characteristics are desirable. For example, consider the RGB color example:

>>> red = (255, 0, 0)

Once you’ve defined red, then you won’t need to add or change any components. Why? If you change the value of one component, then you won’t have a pure red color anymore, and your variable name will be misleading. If you add a new component, then your color won’t be an RGB color. So, tuples are perfect for representing this type of object.

Some of the most relevant characteristics of tuple objects include the following:

• Ordered: They contain elements that are sequentially arranged according to their specific insertion order.
• Lightweight: They consume relatively small amounts of memory compared to other sequences like lists.
• Indexable through a zero-based index: They allow you to access their elements by integer indices that start from zero.
• Immutable: They don’t support in-place mutations or changes to their contained elements. They don’t support growing or shrinking operations.
• Heterogeneous: They can store objects of different data types and domains, including mutable objects.
• Nestable: They can contain other tuples, so you can have tuples of tuples.
• Iterable: They support iteration, so you can traverse them using a loop or comprehension while you perform operations with each of their elements.
• Sliceable: They support slicing operations, meaning that you can extract a series of elements from a tuple.
• Combinable: They support concatenation operations, so you can combine two or more tuples using the concatenation operators, which creates a new tuple.
• Hashable: They can work as keys in dictionaries when all the tuple items are immutable.

Tuples are sequences of objects. They’re commonly called containers or collections because a single tuple can contain or collect an arbitrary number of other objects.

In Python, tuples are ordered, which means that they keep their elements in the original insertion order:

>>> record = ("John", 35, "Python Developer")

>>> record
('John', 35, 'Python Developer')

The items in this tuple are objects of different data types representing a record of data from a database table. If you access the tuple object, then you’ll see that the data items keep the same original insertion order. This order remains unchanged during the tuple’s lifetime.

You can access individual objects in a tuple by position, or index. These indices start from zero:

>>> record[0]
'John'
>>> record[1]
35
>>> record[2]
'Python Developer'

Positions are numbered from zero to the length of the tuple minus one. The element at index 0 is the first element in the tuple, the element at index 1 is the second, and so on.

Cool! You’ve had a first glance at tuples. It’s time to dive deeper into all of the above characteristics of tuples and more. To kick things off, you’ll start by learning the different ways to create tuples in Python.

Constructing Tuples in Python

A tuple is a sequence of comma-separated objects. To store objects in a tuple, you need to create the tuple object with all its content at one time. You’ll have a couple of ways to create tuples in Python. For example, you can create tuples using one of the following alternatives:

• Tuple literals
• The tuple() constructor

In the following sections, you’ll learn how to use the tools listed above to create new tuples in your code. You’ll start off with tuple literals.

item_0, item_1, ..., item_n

(item_0, item_1, ..., item_n)

>>> jane = ("Jane Doe", 25, 1.75, "Canada")
>>> point = (2, 7)
>>> pen = (2, "Solid", True)

>>> days = (
...     "Monday",
...     "Tuesday",
...     "Wednesday",
...     "Thursday",
...     "Friday",
...     "Saturday",
...     "Sunday",
... )

>>> empty = ()
>>> empty
()

>>> type(empty)
<class 'tuple'>

>>> "Hello, %s! You're %s years old." % ("Linda", 24)
'Hello, Linda! You're 24 years old.'

>>> "Hello, %s! You're %s years old." % "Linda", 24
Traceback (most recent call last):
    ...
TypeError: not enough arguments for format string

>>> one_word = "Hello",
>>> one_word
('Hello',)

>>> one_number = (42,)
>>> one_number
(42,)

tuple([iterable])

>>> tuple(["Jane Doe", 25, 1.75, "Canada"])
('Jane Doe', 25, 1.75, 'Canada')

>>> tuple("Pythonista")
('P', 'y', 't', 'h', 'o', 'n', 'i', 's', 't', 'a')

>>> tuple({
...     "manufacturer": "Boeing",
...     "model": "747",
...     "passengers": 416,
... }.values())
('Boeing', '747', 416)

>>> tuple()
()

>>> tuple(x**2 for x in range(10))
(0, 1, 4, 9, 16, 25, 36, 49, 64, 81)

Accessing Items in a Tuple: Indexing

You can extract the items of a tuple using their associated indices. What’s an index? Each item in a tuple has an integer index that specifies its position in the tuple. Indices start at 0 and go up to the number of items in the tuple minus 1.

To access an item through its index, you can use the following syntax:

tuple_object[index]

This construct is known as an indexing operation. The [index] part is the indexing operator, which consists of a pair of square brackets enclosing the target index. You can read this construct as from tuple_object give me the item at index.

Here’s how this syntax works in practice:

>>> jane = ("Jane Doe", 25, 1.75, "Canada")

>>> jane[0]
'Jane Doe'
>>> jane[1]
25
>>> jane[3]
'Canada'

Indexing a tuple with different indices gives you direct access to the associated values. If you use Big O notation for time complexity, then you can say that indexing is an O(1) operation. This means that tuples are quite good for those situations where you need to quickly access specific items from a series.

Here’s a visual representation of how indices map to items in a tuple:

In any Python tuple, the index of the first item is 0, the index of the second item is 1, and so on. The index of the last item is the number of items minus 1. In this example, the tuple has four items, so the last item’s index is 4 - 1 = 3.

The number of items in a tuple defines its length. You can learn this number by using the built-in len() function:

>>> len(jane)
4

With a tuple as an argument, the len() function returns a value representing the number of items in the target tuple. This number is the tuple’s length.

It’s important to note that, if you use an index greater than or equal to the tuple’s length, then you get an IndexError exception:

>>> jane[4]
Traceback (most recent call last):
    ...
IndexError: tuple index out of range

In this example, you get an IndexError as a result. Using out-of-range indices might be a common issue when you’re starting to use tuples or other sequences in Python. So, keep in mind that indices are zero-based, so the last item in this example has an index of 3.

You can also use negative indices while indexing tuples. This feature is common to all Python sequences, such as lists and strings. Negative indices give you access to the tuple items in backward order:

>>> jane[-1]
'Canada'

>>> jane[-2]
1.75

A negative index specifies an element’s position relative to the right end of the tuple and back to the beginning. Here’s a representation of how negative indices work:

You can access the last item in a tuple using the index -1. Similarly, the index -2 identifies the item next to the last, and so forth.

As you can see, negative indices don’t start from 0. That’s because 0 already points to the first item. This may be confusing when you’re first learning about negative and positive indices. Don’t worry, you’ll get used to this behavior.

If you use negative indices, then -len(tuple_object) will be the first item in the tuple. If you use an index lower than this value, then you’ll get an IndexError:

>>> jane[-5]
Traceback (most recent call last):
    ...
IndexError: tuple index out of range

Using an index lower than -len(tuple_object) produces an error because the target index is out of range.

As you already know, tuples can contain items of any type, including other sequences. When you have a tuple that contains other sequences, you can access the items in any nested sequence by chaining indexing operations.

To illustrate, say that you have the following tuple:

>>> employee = (
...     "John",
...     35,
...     "Python Developer",
...     ("Django", "Flask", "FastAPI", "CSS", "HTML"),
... )

Your employee tuple has an embedded tuple containing a series of skills. How can you access individual skills? You can use the following indexing syntax:

tuple_of_sequences[index_0][index_1]...[index_n]

The numbers at the end of each index represent the different levels of nesting in the tuple. So, to access individual skills in the employee tuple, you first need to access the last item and then access the desired skill:

>>> employee[-1][0]
'Django'

>>> employee[-1][1]
'Flask'

You can access items in the nested sequence by applying multiple indexing operations in a row. This syntax is extensible to other nested sequences like lists and strings. It’s even valid for dictionaries, in which case you’ll have to use keys instead of indices.

Retrieving Multiple Items From a Tuple: Slicing

Like other Python sequences, tuples allow you to extract a portion or slice of their content with a slicing operation, which uses the following syntax:

tuple_object[start:stop:step]

The [start:stop:step] part of this construct is known as the slicing operator. It consists of a pair of square brackets and three optional indices: start, stop, and step. The second colon is optional too. You typically use it only in those cases where you need a step value different from 1.

All the indices in the slicing operator are optional. Here’s summary of their meanings and default values:

You can combine these indices in different ways to obtain specific portions of a given tuple. Here are a couple of examples of slicing variations:

>>> days = (
...     "Monday",
...     "Tuesday",
...     "Wednesday",
...     "Thursday",
...     "Friday",
...     "Saturday",
...     "Sunday",
... )

>>> days[:5]
('Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday')

>>> days[5:]
('Saturday', 'Sunday')

In these examples, the first slicing allows you to extract the business days, while the second slicing gives you the weekend.

You can experiment with different combinations of indices and different tuples to get a grasp of how this construct works.

To dive deeper into slicing operations, check out the Retrieving Multiple Items From a List: Slicing section of Python’s list Data Type: A Deep Dive With Examples. For the most part, the same slicing operations that apply to lists are valid for tuples, except for those that mutate a list in place.

Speaking of mutations, immutability is a fundamental feature of tuples. This feature affects how you use tuples in practice. In the following section, you’ll learn how immutability impacts the behavior of tuples.

Exploring Tuple Immutability

Python’s tuples are immutable, which means that once you’ve created a tuple, you can’t change or update its items in place. This characteristic of tuples implies that you can’t use indices to update individual items in an existing tuple:

>>> jane = ("Jane Doe", 25, 1.75, "Canada")

>>> jane[3] = "United States"
Traceback (most recent call last):
    ...
TypeError: 'tuple' object does not support item assignment

Because tuples are immutable, if you try to change the value of a tuple item through an assignment, then you get a TypeError telling you that tuples don’t support item assignments. So, once you’ve created a tuple, there’s no way to update its content. You can only create a new tuple object with the new or updated content.

Another implication of tuples being immutable is that you can’t grow or shrink an existing tuple. Unlike lists, tuples don’t have .append(), .extend(), .insert(), .remove(), and .clear() methods.

Additionally, tuples don’t support the del statement on items:

>>> point = (7, 14, 21)

>>> del point[2]
Traceback (most recent call last):
    ...
TypeError: 'tuple' object doesn't support item deletion

You can’t delete tuple items using the del statement. If you try to do it, then you get a TypeError telling you that tuples don’t support item deletion, as you can confirm in the example above.

Even though Python tuples are immutable, there’s a subtle detail that you need to keep in mind when working with tuples in your code. Tuples can store any type of object, including mutable ones. This means that you can store lists, sets, dictionaries, and other mutable objects in a tuple:

>>> student_info = ("Linda", 18, ["Math", "Physics", "History"])

This tuple stores information about a student. The first two items are immutable. The third item is a list of subjects. Python’s lists are mutable, and therefore, you can change their items in place. This is possible even if your target list is nested in an immutable data type like tuple.

To change or update the list of subjects in your student_info tuple, you can use chained indices as in the following example:

>>> student_info[2][2] = "Computer science"
>>> student_info
('Linda', 22, ['Math', 'Physics', 'Computer science'])

As you can conclude from this example, you can change the content of mutable objects even if they’re nested in a tuple. This behavior of tuples may have further implications. For example, because tuples are immutable, you can use them as keys in a dictionary:

>>> student_courses = {
...     ("John", "Doe"): ["Physics", "Chemistry"],
...     ("Jane", "Doe"): ["English", "History"],
... }

>>> student_courses[("Jane", "Doe")]
['English', 'History']

In this code, you use tuples as keys for the student_courses dictionary. The example works as expected. However, what will happen if the tuples that you want to use as keys contain mutable objects? Consider the following variation of the previous example:

>>> student_courses = {
...     (["John", "Miguel"], "Doe"): ["Physics", "Chemistry"],
...     (["Fatima", "Jane"], "Doe"): ["English", "History"],
... }
Traceback (most recent call last):
    ...
TypeError: unhashable type: 'list'

In summary, you can use tuples as keys in a dictionary only if all their items are of hashable types. Otherwise, you’ll get an error.

Packing and Unpacking Tuples

Python has the notion of packing and unpacking tuples. For example, when you write an assignment statement like point = x, y, z, you’re packing the values of x, y, and z in point. That’s how you create new tuple objects.

You can also do the inverse operation and unpack the values of a tuple into an appropriate number of variables. To continue with the point example, consider the following code:

>>> point = (7, 14, 21)

>>> x, y, z = point
>>> x
7
>>> y
14
>>> z
21

The highlighted line does the magic of unpacking the content of point into three variables. Note that the values go to the variables in order. The first value goes to the first variable, the second value goes to the second variable, and so on.

In regular unpacking, the number of variables must match the number of values to unpack. Otherwise, you get an error:

>>> point = (7, 14, 21)

>>> x, y = point
Traceback (most recent call last):
    ...
ValueError: too many values to unpack (expected 2)

In this case, you’re trying to unpack a three-item tuple into two variables. You get an error because Python doesn’t know how to unambiguously perform the unpacking.

The unpacking syntax works like a charm and has several common use cases. One of the most popular use cases is to take advantage of unpacking for swapping values between variables. For example, to swap values between two variables with regular assignments, you have to use a temporary variable:

>>> a = 200
>>> b = 400

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

>>> a
400
>>> b
200

If you have to do this operation often in your code, then this approach can become cumbersome. Fortunately, the unpacking syntax can help you do the swapping in a quick, elegant way:

>>> a = 200
>>> b = 400

>>> a, b = b, a

>>> a
400
>>> b
200

In the highlighted line, the left-hand operand provides the variables, while the right-hand operand provides the values to unpack. This expression allows you to quickly swap values between variables without an intermediate step.

Parallel assignment is another cool use case of tuple unpacking. For example, say that you often do something like the following:

>>> employee = ("John Doe", 35, "Python Developer")

>>> name = employee[0]
>>> age = employee[1]
>>> job = employee[2]

In this example, you use independent assignment to grab values from the employee tuple. Even though this code works, the index handling can be error-prone and confusing. Here’s a Pythonic solution using tuple unpacking:

>>> name, age, job = ("John Doe", 35, "Python Developer")

With tuple unpacking, you solve the problem in a single line without using indices. This Pythonic approach will make your code easier to read and understand. It’ll also make the code less error-prone.

Python also has a packing and unpacking operator (*) that you can use to make your unpacking statements more flexible. For example, you can use this operator to collect multiple values in a single variable when the number of variables on the left doesn’t match the number of items in the tuple on the right:

>>> numbers = (1, 2, 3, 4, 5)

>>> *head, last = numbers
>>> head
[1, 2, 3, 4]
>>> last
5

>>> first, *middle, last = numbers
>>> first
1
>>> middle
[2, 3, 4]
>>> last
5

>>> first, second, *tail = numbers
>>> first
1
>>> second
2
>>> tail
[3, 4, 5]

>>> first, *_ = numbers
>>> first
1

In these examples, the original tuple has five items. In the first unpacking, you use the unpacking operator to collect four items in head and one item in last. Note that the * operator collects the values in a new list object rather than in a tuple.

In the second and third examples, you collect several values from the middle and tail of numbers using the packing operator (*).

The final example shows how you can grab the first value from a tuple and pack the rest of the values in a disposable variable. This construct can be useful when you only need the first value. However, it may be confusing to others. Doing something like first = number[0] would probably be more intuitive and natural.

Another interesting use case of the packing and unpacking operator is when you need to merge a few tuples together to build a new one:

>>> name = ("John", "Doe")
>>> contact = ("john@example.com", "55-555-5555")

>>> (*name, *contact)
('John', 'Doe', 'john@example.com', '55-555-5555')

In the highlighted line, you use the * operator to unpack the content of name and contact, merging them to create a new tuple with all the data from both. This syntax provides a quick way to merge tuples in your code.

Returning Tuples From Functions

In some situations, you’ll need to return multiple values from a function or method. To do that, you can build a return statement with a comma-separated series of arguments. Yes, that’s a tuple. As a result, whenever you call the function, you’ll get a tuple of values.

The built-in divmod() function is a good example of a function that returns multiple values. This function takes two numbers and returns a tuple containing the quotient and the remainder when doing integer division:

>>> divmod(4, 2)
(2, 0)

>>> quotient, remainder = divmod(8, 2)
>>> quotient
4
>>> remainder
0

This function returns two values as a tuple. Because the function returns a tuple, you can use the unpacking syntax to store each value in its dedicated variable. You can use this pattern in your custom functions too.

For example, say that you want to write a function that returns the minimum and maximum value from an input iterable:

>>> def find_extremes(iterable):
...     data = tuple(iterable)
...     if len(data) == 0:
...         raise ValueError("input iterable must not be empty")
...     return min(data), max(data)
...

>>> extremes = find_extremes([3, 4, 2, 6, 7, 1, 9])
>>> extremes
(1, 9)

>>> type(extremes)
<class 'tuple'>

In this function, you first create a tuple from the input iterable. This step guarantees that the data container supports the built-in len() function. With the conditional statement, you check if the input iterable is empty, in which case you raise an exception.

If the input iterable contains at least one value, then you use the built-in min() and max() functions to determine the minimum and maximum values in the input data.

Finally, you return both values from the function. Again, when you separate a series of values with commas, you create a tuple. So, this function returns a tuple object.

You’ll note that returning multiple values as a tuple is one of those use cases where the parentheses don’t add much to the readability of your code. So, most Python developers don’t use them here.

Creating Copies of a Tuple

You typically make copies of an object when you need to transform the data while preserving the original data unchanged. Copies are quite useful when you’re working with mutable data types, such as lists and dictionaries. They allow you to make changes in the copy without affecting the original data.

Because tuples are immutable data types, there’s no way to mutate their items in place. So, creating copies of an existing tuple isn’t really necessary. The usual shallow copying techniques that you use with lists, such as the slicing operator or the copy.copy() function, create aliases instead of copies:

>>> student_info = ("Linda", 18, ["Math", "Physics", "History"])

>>> student_profile = student_info[:]
>>> id(student_info) == id(student_profile)
True
>>> id(student_info[0]) == id(student_profile[0])
True
>>> id(student_info[1]) == id(student_profile[1])
True
>>> id(student_info[2]) == id(student_profile[2])
True

Both student_info and student_profile hold references to the same tuple object. You can confirm this fact by using the built-in id() function, which takes an object as an argument and returns its identity. So, student_profile is an alias of student_info rather than a copy. Also, note how items at the same index position in both aliases share the same identity.

The copy() function from the copy module produces an equivalent result:

>>> from copy import copy

>>> student_info = ("Linda", 18, ["Math", "Physics", "History"])

>>> student_profile = copy(student_info)
>>> id(student_info) == id(student_profile)
True
>>> id(student_info[0]) == id(student_profile[0])
True
>>> id(student_info[1]) == id(student_profile[1])
True
>>> id(student_info[2]) == id(student_profile[2])
True

Again, both variables hold references to the same tuple object and the same items. So, the copy() function doesn’t make any difference.

Wait, the tuple in the above example hosts a list object, which is mutable. What would happen if you changed one of its items? Would the change affect both student_profile and student_info? Run the code below to answer these questions:

>>> student_profile[2][2] = "Computer science"

>>> student_profile
('Linda', 18, ['Math', 'Physics', 'Computer science'])
>>> student_info
('Linda', 18, ['Math', 'Physics', 'Computer science'])

In this example, you change the "History" subject to "Computer science" in student_profile. The change also affects the original data in student_info.

Maybe you’ve made deep copies of lists using the deepcopy() function from the copy module, and you’re wondering if you can do the same with tuples. In this case, you’re looking for a new tuple that contains copies of the contained elements. Does that work with tuples? Take a look at the following example:

>>> from copy import deepcopy

>>> student_info = ("Linda", 18, ["Math", "Physics", "History"])
>>> student_profile = deepcopy(student_info)

>>> id(student_info) == id(student_profile)
False
>>> id(student_info[0]) == id(student_profile[0])
True
>>> id(student_info[1]) == id(student_profile[1])
True
>>> id(student_info[2]) == id(student_profile[2])
False

In this example, you use deepcopy() to create a copy of your original tuple, student_info. Note that both variables now point to different tuple objects with different identities. However, the items at the same index in both tuples hold references to the same objects.

Now go ahead and change the subject again:

>>> student_profile[2][2] = "Computer science"
>>> student_profile
('Linda', 18, ['Math', 'Physics', 'Computer science'])
>>> student_info
('Linda', 18, ['Math', 'Physics', 'History'])

This time, changes to the mutable object in student_profile don’t affect the original data in student_info.

In summary, shallow copies of tuples don’t create copies but aliases. Deep copies create new tuple objects with references to the same items. If the deep-copied tuple contains mutable objects, then Python creates a new copy of these objects so that mutations to them in the copy won’t affect the original data.

Concatenating and Repeating Tuples

Like lists and strings, tuples also support concatenation and repetition. You can use the plus operator (+) to concatenate tuples together and the star operator (*) to repeat the content of an existing tuple.

In the following sections, you’ll learn how these two operations work on Python tuples and how to use them in your code.

>>> personal_info = ("John", 35)
>>> professional_info = ("Computer science", ("Python", "Django", "Flask"))

>>> profile = personal_info + professional_info
>>> profile
('John', 35, 'Computer science', ('Python', 'Django', 'Flask'))

>>> (0, 1, 2, 3, 4, 5) + [6, 7, 8, 9]
Traceback (most recent call last):
    ...
TypeError: can only concatenate tuple (not "list") to tuple

>>> profile = ("John", 35)
>>> id(profile)
4420700928

>>> profile += ("Computer science", ("Python", "Django", "Flask"))
>>> id(profile)
4406635200

>>> profile
('John', 35, 'Computer science', ('Python', 'Django', 'Flask'))

>>> numbers = (1, 2, 3)

>>> numbers * 3
(1, 2, 3, 1, 2, 3, 1, 2, 3)

>>> 4 * numbers
(1, 2, 3, 1, 2, 3, 1, 2, 3, 1, 2, 3)

>>> numbers = (1, 2, 3)
>>> id(numbers)
4407400448

>>> numbers *= 3
>>> numbers
(1, 2, 3, 1, 2, 3, 1, 2, 3)
>>> id(numbers)
4407458624

Reversing and Sorting Tuples

In Python, you’ll have the built-in reversed() and sorted() functions that you can use when you need to reverse and sort tuples. You can also create reversed tuples using the slicing operator with a step of -1. In the following sections, you’ll learn how to reverse and sort tuples using these tools.

>>> days = (
...     "Monday",
...     "Tuesday",
...     "Wednesday",
...     "Thursday",
...     "Friday",
...     "Saturday",
...     "Sunday",
... )

>>> reversed(days)
<reversed object at 0x107032b90>

>>> tuple(reversed(days))
(
    'Sunday',
    'Saturday',
    'Friday',
    'Thursday',
    'Wednesday',
    'Tuesday',
    'Monday'
)

>>> reversed_days = days[::-1]

>>> reversed_days
(
    'Sunday',
    'Saturday',
    'Friday',
    'Thursday',
    'Wednesday',
    'Tuesday',
    'Monday'
)

>>> id(days) == id(reversed_days)
False

>>> numbers = (2, 9, 5, 1, 6)

>>> sorted(numbers)
[1, 2, 5, 6, 9]

>>> employee = ("John Doe", 35, "Python Developer")

>>> sorted(employee)
Traceback (most recent call last):
    ...
TypeError: '<' not supported between instances of 'int' and 'str'

>>> numbers = (2, 9, 5, 1, 6)

>>> sorted(numbers, reverse=True)
[9, 6, 5, 2, 1]

>>> fruits = (("apple", 0.40), ("banana", 0.25), ("orange", 0.35))

>>> sorted(fruits, key=lambda fruit: fruit[1])
[('banana', 0.25), ('orange', 0.35), ('apple', 0.4)]

Traversing Tuples in Python

Sometimes, you’ll need to loop over each value in a tuple. Python provides a few tools that allow you to do this. The most popular are for loops, comprehensions, and generator expressions. However, you can also use some of Python’s functional programming tools that implement an implicit loop, such as the map() and filter() functions.

In the following sections, you’ll learn how to traverse tuples using these tools. To kick things off, you’ll start with for loops.

>>> monthly_incomes = (
...     ("January", 5000),
...     ("February", 5500),
...     ("March", 6000),
...     ("April", 5800),
...     ("May", 6200),
...     ("June", 7000),
...     ("July", 7500),
...     ("August", 7300),
...     ("September", 6800),
...     ("October", 6500),
...     ("November", 6000),
...     ("December", 5500)
... )

>>> total_income = 0
>>> for income in monthly_incomes:
...     total_income += income[1]
...

>>> total_income
75100

>>> quarter_income = 0

>>> for index, (month, income) in enumerate(monthly_incomes, start=1):
...     print(f"{month:>10}: {income}")
...     quarter_income += income
...     if index % 3 == 0:
...         print("-" * 20)
...         print(f"{'Quarter':>10}: {quarter_income}", end="\n\n")
...         quarter_income = 0
...
   January: 5000
  February: 5500
     March: 6000
--------------------
   Quarter: 16500

     April: 5800
       May: 6200
      June: 7000
--------------------
   Quarter: 19000

      July: 7500
    August: 7300
 September: 6800
--------------------
   Quarter: 21600

   October: 6500
  November: 6000
  December: 5500
--------------------
   Quarter: 18000

>>> numbers = ("2", "9", "5", "1", "6")

>>> tuple([int(number) for number in numbers])
(2, 9, 5, 1, 6)

>>> tuple(int(number) for number in numbers)
(2, 9, 5, 1, 6)

Exploring Other Features of Tuples

Python’s tuple is a pretty lightweight data type with limited functionality. Tuples are immutable, so they don’t need methods to add, update, or remove items. In consequence, they have only two methods as part of their public API: .count() and .index().

With .count(), you can count the number of occurrences of a given item in a tuple. The method allows you to check how many times a given item is present in the target tuple:

>>> fruits = (
...     "apple",
...     "banana",
...     "orange",
...     "apple",
...     "apple",
...     "kiwi",
...     "banana"
... )

>>> fruits.count("apple")
3
>>> fruits.count("banana")
2
>>> fruits.count("mango")
0

The .count() method takes a potential item as an argument, traverses the underlying tuple, and finds out how many times the target item is present. If the item isn’t present in the tuple, then .count() returns 0.

Because most tuple use cases imply storing items of different types, such as those in a record of a database, the .count() method may have limited practical applications. You’ll probably find .count() more useful when you’re working with list objects, where the items are often of the same type and represent homogeneous and related values.

On the other hand, the .index() method allows you to locate the first occurrence of an item in an existing tuple. If the target item is in the tuple, then the method returns its index. Otherwise, the tuple raises a ValueError exception:

>>> fruits.index("apple")
0

>>> fruits.index("mango")
Traceback (most recent call last):
    ...
ValueError: tuple.index(x): x not in tuple

In the first call to .index(), you get the index of the first occurrence of "apple" in the underlying tuple. In the second call, because "mango" isn’t present in fruits, you get a ValueError with a self-explanatory message.

item in tuple_object

item not in tuple_object

>>> skills = ("Python", "Django", "Flask", "CSS")

>>> "Flask" in skills
True
>>> "Flask" not in skills
False

>>> "pandas" in skills
False
>>> "pandas" not in skills
True

>>> employee = ("John Doe", "Python Developer", "Remote", "Canada")

>>> len(employee)
4

>>> (2, 3) == (2, 3)
True

>>> (5, 6, 7) < (7, 5, 6)
True

>>> (4, 3, 2) <= (4, 3, 2)
True

>>> (5, 6, 7) < (8,)
True

>>> (5, 6, 7) < (5,)
False

>>> (5, 6, 7) == (5, 6)
False

>>> ("Python", 42, 3.14, (1, 2)) == ("Python", 42, 3.14, (1, 2))
True

>>> ("Python", 42, 3.14, (1, 2)) == ("Python", "42", 3.14, (1, 2))
False

>>> ("Python", 42, 3.14, (1, 2)) > ("Python", "42", 3.14, (1, 2))
Traceback (most recent call last):
    ...
TypeError: '>' not supported between instances of 'int' and 'str'

Common Gotchas of Python Tuples

If you’re new to Python and are just starting out with tuples, then you should know about a couple of gotchas that can cause subtle issues in your code. Arguably, the most common gotcha with tuples is to forget the trailing comma when defining one-item tuples:

>>> numbers = (42)

>>> numbers.index(42)
Traceback (most recent call last):
    ...
AttributeError: 'int' object has no attribute 'index'

>>> type(numbers)
<class 'int'>

In this example, you attempt to create a one-item tuple using a pair of parentheses. Later in the code, when you call the .index() method, you get an error telling you that integer objects don’t have this method.

What just happened? When you define a tuple, the parentheses are superfluous. They help you enhance readability but nothing else. The commas are what really defines a tuple. To create a one-item tuple, you need to include a trailing comma after the item:

>>> numbers = (42,)

>>> numbers.index(42)
0

>>> type(numbers)
<class 'tuple'>

The trailing comma after 42 creates the actual tuple. Now the code works correctly, and you can call .index() as needed.

Another gotcha that can bite you when you’re working with tuples is hashability, which is the possibility of using a hash function to calculate a unique hash code out of a given value or data structure. In Python, it’s common to hear people say that because tuples are immutable, you can use them as keys in a dictionary.

However, this assumption isn’t always true. When you store mutable objects in a tuple, that tuple won’t be hashable and won’t work as a dictionary key. You already saw an example of this issue in the Exploring Tuple Immutability section.

Here’s another example. This time, you create a dictionary of cities. The keys include the city name and its geographical coordinates. The values hold the population of each city:

>>> cities = {
...     ("Vancouver", [49.2827, -123.1207]): 631_486,
...     ("Denver", [39.7392, -104.9903]): 716_492,
...     ("Oslo", [59.9139, 10.7522]): 693_491,
...     ("Berlin", [52.5200, 13.4050]): 3_769_495,
...     ("Vienna", [48.2082, 16.3738]): 1_900_000,
...     ("Warsaw", [52.2297, 21.0122]): 1_791_000,
...     ("Belgrade", [44.7866, 20.4489]): 1_395_000,
... }
Traceback (most recent call last):
    ...
TypeError: unhashable type: 'list'

In this example, you use tuples as the keys of your cities dictionary. Tuples are immutable, but this fact doesn’t guarantee that all tuples can work as dictionary keys. In this specific case, your tuples contain lists, which are mutable. Therefore, your code fails with a TypeError exception.

Using Alternatives to the Built-in tuple Type

Up to this point, you’ve learned a lot about Python tuples. You now know that they’re immutable sequences that can contain heterogeneous data. Even though tuples have a few cool features, their functionality is pretty limited.

For example, you can only access tuple items using numeric indices. This can be error-prone and annoying because it forces you to remember the right index every time.

Consider the following example:

>>> person = ("John", 35, "Python Developer")

>>> name = person[0]
>>> name
'John'

>>> age = person[2]
>>> age
'Python Developer'

In this example, you have a tuple that contains information about a person. Later in your code, you access the first item, which is the person’s name. However, the index to access the person’s age in the last expression is wrong, and the age variable ends up holding the incorrect data.

Fortunately, Python has other classes that can emulate a tuple but offer a more readable and explicit interface that doesn’t rely on numeric indices. In the following sections, you’ll learn the basics of these classes. To kick things off, you’ll start with traditional named tuples.

>>> from collections import namedtuple

>>> Person = namedtuple("Person", "name age position")

>>> person = Person("John", 35, "Python Developer")
>>> person.name
'John'
>>> person.age
35
>>> person.position
'Python Developer'

>>> person[0]
'John'

>>> person.name = "John Doe"
Traceback (most recent call last):
    ...
AttributeError: can't set attribute

>>> person[0] = "John Doe"
Traceback (most recent call last):
    ...
TypeError: 'Person' object does not support item assignment

>>> from collections import namedtuple

>>> def custom_divmod(a, b):
...     DivMod = namedtuple("DivMod", "quotient remainder")
...     return DivMod(*divmod(a, b))
...

>>> custom_divmod(8, 4)
DivMod(quotient=2, remainder=0)

name,age,position
"Fatima",28,"Technical Lead"
"Joe",32,"Senior Web Developer"
"Lara",40,"Project Manager"
"Miguel",25,"Data Analyst"
"Jane",40,"Senior Python Developer"

>>> from typing import NamedTuple

>>> class Employee(NamedTuple):
...     name: str
...     age: int
...     position: str = "Python Developer"
...

>>> import csv

>>> with open("employees.csv", mode="r") as csv_file:
...     reader = csv.reader(csv_file)
...     next(reader)  # Skip headers
...     employees = []
...     for name, age, position in reader:
...         employees.append(Employee(name, int(age), position))
...

>>> employees
[
    Employee(name='Fatima', age='28', position='Technical Lead'),
    Employee(name='Joe', age='32', position='Senior Web Developer'),
    Employee(name='Lara', age='40', position='Project Manager'),
    Employee(name='Miguel', age='25', position='Data Analyst'),
    Employee(name='Jane', age='40', position='Senior Python Developer')
]

>>> fatima = employees[0]

>>> fatima.name
'Fatima'
>>> fatima.age
'28'
>>> fatima.position
'Technical Lead'

>>> from dataclasses import dataclass

>>> @dataclass
... class Employee:
...     name: str
...     age: int
...     position: str = "Python Developer"
...

>>> import csv

>>> with open("employees.csv", mode="r") as csv_file:
...     reader = csv.reader(csv_file)
...     next(reader)  # Skip headers
...     employees = []
...     for name, age, position in reader:
...         employees.append(Employee(name, int(age), position))
...

>>> employees
[
    Employee(name='Fatima', age='28', position='Technical Lead'),
    Employee(name='Joe', age='32', position='Senior Web Developer'),
    Employee(name='Lara', age='40', position='Project Manager'),
    Employee(name='Miguel', age='25', position='Data Analyst'),
    Employee(name='Jane', age='40', position='Senior Python Developer')
]

>>> fatima = employees[0]

>>> fatima.name
'Fatima'
>>> fatima.age
'28'
>>> fatima.position
'Technical Lead'

>>> joe = employees[1]
>>> joe.name
'Joe'

>>> joe.name = "Joe Smith"
>>> joe.name
'Joe Smith'

>>> @dataclass(frozen=True)
... class Employee:
...     name: str
...     age: int
...     position: str = "Python Developer"
...

>>> with open("employees.csv", mode="r") as csv_file:
...     reader = csv.reader(csv_file)
...     next(reader)  # Skip headers
...     employees = []
...     for name, age, position in reader:
...         employees.append(Employee(name, int(age), position))
...

>>> joe = employees[1]
>>> joe.name
'Joe'
>>> joe.name = "Joe García"
Traceback (most recent call last):
    ...
dataclasses.FrozenInstanceError: cannot assign to field 'name'

Deciding Whether to Use Tuples

As you’ve learned throughout this tutorial, tuples are quite basic immutable sequences with a reduced set of features. However, they’re suitable for those use cases where you need to store heterogeneous data in a sequence that doesn’t change at all or doesn’t change frequently.

Database records are a good example of a typical use case of tuples. In this scenario, a tuple will provide a good representation of records or rows, where you have many fields containing heterogeneous values that shouldn’t change frequently.

In contrast, a list will be the right data type to represent database fields or columns because lists typically store homogeneous data that can change frequently. This will allow you to add or remove rows in your database and to update their content.

In general, you should use tuples when you need to:

• Ensure data integrity: Tuples are immutable, meaning that you can’t modify their elements after creation. This immutability guarantees data stability, ensuring that the values in the tuple remain unchanged.
• Reduce memory consumption: Tuples have less memory overhead compared to lists since they allocate a fixed amount of memory. This is particularly advantageous when working with large collections of data or in memory-constrained environments.
• Improve performance: Tuples are generally more efficient than lists in terms of creation, iteration, and element access. This can result in improved performance, especially when working with large datasets.

If you’re in one of these scenarios, then favor using tuples over other similar sequences like lists, for example.

Some more concrete use cases of tuples include the following:

• Associating two or more values (pairs, trios, and so on)
• Representing database records
• Providing multi-value keys in dictionaries

Here are a few quick examples of these use cases:

>>> color = (0, 2, 255)

>>> car = ("Toyota", "Camry", 2020, "Blue")

>>> capital_cities = {
...    ("Ottawa", (45.4215, -75.6972)): "Canada",
...    ("Washington D.C.", (38.9072, -77.0369)): "USA",
...    ("Berlin", (52.5200, 13.4050)): "Germany",
...    ("Belgrade", (44.7866, 20.4489)): "Serbia",
...    ("Vienna", (48.2082, 16.3738)): "Austria",
...    ("Oslo", (59.9139, 10.7522)): "Norway",
...    ("Warsaw", (52.2297, 21.0122)): "Poland"
... }

The first tuple represents a color using the RGB color model. This is an example of related values that you group together in a trio that may remain unchanged over time. The second tuple holds a car’s information, which you may have retrieved from a database.

Finally, the capital_cities dictionary has tuples as keys. Each key contains the capital city of a given country and the corresponding geographical coordinates.

Conclusion

You’ve delved into the core features and functionalities of Python’s tuples. You now know that tuples are immutable sequences that provide a reliable container for data that’s likely to remain unmodified during your code’s lifetime.

You’ve also learned about various aspects of tuple usage, including their most common use cases. Tuples are a great tool for any Python developer, and you’ll find them in most codebases out there.

In this tutorial, you’ve learned how to:

• Create tuples using different approaches in Python
• Access one or more items in a tuple using indexing and slicing
• Unpack, return, copy, and concatenate tuples
• Reverse, sort, and traverse tuples using loops and other tools
• Explore other features and common gotchas of tuples

With all this knowledge, you’re ready to write better code, as tuples offer an efficient and reliable way to handle and manipulate grouped data. Exploring tuples further and playing with them in various ways will take your Python powers to the next level.