Named Tuple

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) # true

Code 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 namedtuple

Code 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)) # True

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)

Output:

(100, 200)

(100, 200)

100

200

Code 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')

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) # True

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)

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)) # 100

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.