Python NamedTuple

Summary: in this tutorial, you’ll learn how to use the Python namedtuple function to create named tuples.

Introduction to Python named tuples

The following shows a tuple that has two elements:

point = (100,200)Code language: Python (python)

The point tuple represents a 2D point whose x-coordinate is 100 and y coordinate is 200.

To get the x-coordinate and y-coordinate, you can use the following syntax:

 x = point[0]
 y = point[1]Code language: Python (python)

This code works fine. However, it’s not so obvious.

When you look at the point[0], you need to know its implicitly meaning which doesn’t mention in the code.

To make the code more clear, you might want to use a class. For example:

class Point2D:
    def __init__(self, x, y):
        self.x = x
        self.y = y
Code language: Python (python)

And you can create a new instance of the Point2D:

a = Point2D(100, 200)Code language: Python (python)

Also, you can access x-coordinate and y-coordinate attributes:

print(a.x)
print(a.y)Code language: Python (python)

To compare if two points are the same, you need to implement the __eq__ method:

class Point2D:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        if isinstance(other, Point2D):
            return self.x == other.x and self.y == other.y
        return False
Code language: Python (python)

The __eq__ method checks if a point is an instance of the Point2D class and returns True if both x-coordinate and y-coordinate are equal.

The following shows how to compare two instances of the Point2D class:

a = Point2D(100, 200)
b = Point2D(100, 200)

print(a is b)  # False
print(a == b)  # trueCode language: Python (python)

The Point2D might work as you expected. However, you need to write a lot of code.

To combine the simplicity of a tuple and the obvious of a class, you can use a named tuple:

Named tuples allow you to create tuples and assign meaningful names to the positions of the tuple’s elements.

Technically, a named tuple is a subclass of tuple. On top of that, it adds property names to the positional elements.

Creating named tuple classes

To create a named tuple class, you need to the namedtuple function of the collections standard library.

The namedtuple is a function that returns a new named tuple class. In other words, the namedtuple() is a class factory.

To use the namedtuple function, you need to import it from the collections module first:

from collections import namedtupleCode language: JavaScript (javascript)

The namedtuple function accepts the following arguments to generate a class:

• A class name that specifies the name of the named tuple class.
• A sequence of field names that correspond to the elements of tuples. The field names must be valid variable names except that they cannot start with an underscore (_).

For example, the following uses the namedtuple function to create the Point2D class:

Point2D = namedtuple('Point2D',['x','y'])Code language: Python (python)

The namedtuple also can accept fields names as:

1) A tuple of string:

Point2D = namedtuple('Point2D',('x','y'))Code language: Python (python)

2) Or a single string with field names separated by commas:

Point2D = namedtuple('Point2D',('x, y'))Code language: Python (python)

3) Or a single string with field names separated by whitespaces

Point2D = namedtuple('Point2D','x y')Code language: Python (python)

Instantiating named tuples

The Point2D is a class, which is a subclass of the tuple. And you can create new instances of the Point2D class like you do with a regular class. For example:

point = Point2D(100, 200)

Or you can use the keyword arguments:

point = Point2D(x=100, y=200)Code language: Python (python)

The point object is an instance of the Point2D class. Therefore, it’s an instance of the tuple class:

print(isinstance(point, Point2D))  # True
print(isinstance(point, tuple))  # TrueCode language: Python (python)

Accessing data of a named tuple

A named tuple is a regular tuple. Therefore, you can apply all tuple operations on a named tuple.

To access data in a named tuple, you can use:

• Slicing
• Unpacking
• Indexing
• and iterating

For example:

# unpacking
x, y = point
print(f'({x}, {y})')  # (100, 200)

# indexing
x = point[0]
y = point[1]
print(f'({x}, {y})')  # (100, 200)

# iterating

for coordinate in point:
    print(coordinate)
Code language: Python (python)

Output:

(100, 200)
(100, 200)
100
200Code language: Python (python)

The rename argument of the namedtuple function

The namedtuple function accepts the rename the keyword-only argument that allows you to rename invalid field names.

The following results in an error because the field name _radius starts with an underscore (_):

from collections import namedtuple

Circle = namedtuple(
    'Circle',
    'center_x, center_y, _radius'
)
Code language: Python (python)

However, when you use the rename argument, the namedtuple function automatically renames the _radius to a valid field name. For example:

from collections import namedtuple

Circle = namedtuple(
    'Circle',
    'center_x, center_y, _radius',
    rename=True
)Code language: Python (python)

To find field names of a named tuple, you can use the _fields class property. For example:

print(Circle._fields)Code language: Python (python)

Output:

('center_x', 'center_y', '_2')Code language: Python (python)

In this example, the namedtuple function changes the _radius field to _2 automatically.

Additional Python functions of named tuples

Named tuples provide some useful functions out of the box. For example, you can use the equal operator (==) to compare two named tuple instances:

a = Point2D(100, 200)
b = Point2D(100, 200)

print(a == b)  # TrueCode language: Python (python)

If you use the class, you need to implement the __eq__ to get this function.

Also, you can get the string representation of a named tuple:

print(a)Code language: Python (python)

Output:

Point2D(x=100, y=200)Code language: Python (python)

Again, if you use the class, you need to implement __rep__ method.

Since a named tuple is a tuple, you can apply any function that is relevant to a regular tuple to a named tuple. For example:

print(max(a))  # 200
print(min(a))  # 100Code language: Python (python)

Summary

• Named tuples are tuples whose element positions have meaningful names.
• Use the namedtuple function of the collections standard library to create a named tuple class.
• Named tuples are immutable.