Skip to content
CodeMDD.io | Coding Tutorials

Effortlessly Master Python Named Tuple

CodeMDD.io

Write Pythonic and Clean Code With namedtuple

Using namedtuple to Write Pythonic Code

Python’s collections module provides a factory function called namedtuple(), which is specially designed to make your code more Pythonic when you’re working with tuples. With namedtuple(), you can create immutable sequence types that allow you to access their values using descriptive field names and the dot notation instead of unclear integer indices.

If you have some experience using Python, then you know that writing Pythonic code is a core skill for Python developers. In this tutorial, you’ll level up that skill using namedtuple.

In this tutorial, you’ll learn how to:

  • Create namedtuple classes using namedtuple()
  • Identify and take advantage of cool features of namedtuple
  • Use namedtuple instances to write Pythonic code
  • Decide whether to use a namedtuple or a similar data structure
  • Subclass a namedtuple to provide new features

To get the most out of this tutorial, you need to have a general understanding of Python’s philosophy related to writing Pythonic and readable code. You also need to know the basics of working with tuples, dictionaries, classes and object-oriented programming, data classes, and type hints.

Creating Tuple-Like Classes With namedtuple()

The first step in using namedtuple is to import it from the collections module:

from collections import namedtuple

You can create a namedtuple class by calling namedtuple() and passing in the name of the class and the names of the fields you want to define. For example, to create a Point class with x and y fields, you can do the following:

Point = namedtuple('Point', ['x', 'y'])

With this simple line of code, you’ve created a new class called Point that behaves like a tuple but with named fields. Now, you can create instances of this class and access their fields using the dot notation:

p = Point(1, 2)
print(p.x)  # Output: 1
print(p.y)  # Output: 2

Providing Required Arguments to namedtuple()

By default, namedtuple expects a sequence of field names as its second argument. However, you can also pass in a string with the field names separated by spaces:

Person = namedtuple('Person', 'name age')

Alternatively, you can pass the field names as individual arguments:

Person = namedtuple('Person', 'name', 'age')

Using Optional Arguments With namedtuple()

The namedtuple() function also accepts additional optional arguments to modify the behavior of the generated class. Two useful optional arguments are verbose and rename.

The verbose argument controls the output of the namedtuple factory function. If verbose is set to True, then a string representation of the newly created class is printed. By default, verbose is set to False.

The rename argument is used to resolve naming conflicts between field names and reserved Python keywords. By default, rename is set to False, which means that if you try to use a reserved keyword as a field name, a ValueError will be raised. If you set rename to True, then the reserved keyword will be renamed by appending an underscore to it.

For example, let’s say you want to create a namedtuple class where one of the fields is named class, which is a reserved keyword in Python. You can do the following:

Car = namedtuple('Car', ['make', 'class', 'year'], rename=True)

Now, you can create instances of the Car class without any issues:

car = Car('Honda', 'Sedan', 2020)
print(car.make)   # Output: Honda
print(car.class_) # Output: Sedan
print(car.year)   # Output: 2020

Exploring Additional Features of namedtuple Classes

namedtuple provides several additional features that go beyond the capabilities of regular tuples.

Creating namedtuple Instances From Iterables

You can use the _make() class method to create namedtuple instances from iterables. The elements in the iterable must match the field names in the namedtuple class, and the iterable must be the same length as the number of fields.

p = Point._make([1, 2])
print(p.x)  # Output: 1
print(p.y)  # Output: 2

Converting namedtuple Instances Into Dictionaries

You can use the _asdict() instance method to convert a namedtuple instance into an ordered dictionary.

p = Point(1, 2)
d = p._asdict()
print(d)  # Output: OrderedDict([('x', 1), ('y', 2)])

Replacing Fields in Existing namedtuple Instances

namedtuple instances are immutable, which means you can’t modify their fields directly. However, you can use the _replace() instance method to create a new instance with some of the fields replaced.

p = Point(1, 2)
p2 = p._replace(y=3)
print(p2)  # Output: Point(x=1, y=3)

Exploring Additional namedtuple Attributes

namedtuple classes provide several attributes that can be used to access information about the class and its instances:

  • Point._fields: This attribute contains a tuple with the field names of the Point class.
  • Point._field_defaults: This attribute is only available if you’re using Python 3.7 or later. It contains a dictionary that maps field names to their default values.
  • p._asdict(): This instance method returns an ordered dictionary with the field names and values of the p instance.
  • p._make(iterable): This class method creates a new instance of the Point class using the elements of the iterable.
  • p._replace(**kwargs): This instance method replaces some fields of the p instance with new values specified as keyword arguments.

Writing Pythonic Code With namedtuple

One of the main benefits of using namedtuple is that it allows you to write more Pythonic code. Here are some examples of how you can use namedtuple to improve the readability and expressiveness of your code.

Using Field Names Instead of Indices

By using namedtuple instead of regular tuples, you can access the fields of instances using descriptive field names instead of indices. This makes the code more readable and less error-prone.

For example, let’s say you have a list of points in a 2D plane, where each point is represented as a tuple with the x and y coordinates. Here’s how you can make the code more Pythonic by using namedtuple:

Point = namedtuple('Point', ['x', 'y'])


points = []
points.append(Point(1, 2))
points.append(Point(3, 4))


for point in points:
    print(f"The coordinates are x={point.x}, y={point.y}")

Returning Multiple Named Values From Functions

You can use namedtuple to return multiple named values from a function. This can improve the readability of the code and make it more self-explanatory.

Point = namedtuple('Point', ['x', 'y'])


def calculate_distance(p1, p2):
    dx = p2.x - p1.x
    dy = p2.y - p1.y
    return Point(dx, dy)


p1 = Point(1, 2)
p2 = Point(4, 6)
distance = calculate_distance(p1, p2)


print(f"The distance is dx={distance.x}, dy={distance.y}")

Reducing the Number of Arguments to Functions

When you have a function that takes a large number of arguments, you can use namedtuple to reduce the number of arguments and make the function signature more readable.

For example, let’s say you have a function that calculates the area of a rectangle. Instead of passing in the width and height as separate arguments, you can use a namedtuple to represent the dimensions of the rectangle:

Dimensions = namedtuple('Dimensions', ['width', 'height'])


def calculate_area(dimensions):
    return dimensions.width * dimensions.height


rect = Dimensions(width=10, height=5)
area = calculate_area(rect)


print(f"The area is {area}")

Reading Tabular Data From Files and Databases

namedtuple can be useful when reading tabular data from files or databases. You can define a namedtuple class to represent the structure of the data, and then create instances of the class for each row of data.

For example, let’s say you have a CSV file with a list of people’s names and ages. You can create a namedtuple class to represent each row of data, and then read the file and create instances of the class for each row:

import csv
from collections import namedtuple


Person = namedtuple('Person', ['name', 'age'])


people = []
with open('people.csv') as file:
    reader = csv.reader(file)
    next(reader)  # Skip the header
    for row in reader:
        name, age = row
        person = Person(name, int(age))
        people.append(person)


for person in people:
    print(f"Name: {person.name}, Age: {person.age}")

Using namedtuple vs Other Data Structures

namedtuple is a versatile data structure that can be used in many different scenarios. However, it’s not always the best choice, and sometimes other data structures might be more appropriate for the task at hand. Let’s explore some alternatives to namedtuple.

namedtuple vs Dictionary

Both namedtuple and dictionaries allow you to store and access data using named fields. The main difference between the two is that namedtuple is immutable, while dictionaries are mutable.

If you need to store data that won’t change over time, or you want to emphasize that the data is read-only, then namedtuple might be a better choice. On the other hand, if you need to modify the data or store additional information, then a dictionary might be a more suitable data structure.

namedtuple vs Data Class

In Python 3.7 and later, the dataclasses module provides a way to define classes that are similar to namedtuple but with additional features. Data classes allow you to specify default values for fields, define methods, and provide more control over how the class is represented as a string.

If you’re using Python 3.7 or later and you need the extra features provided by data classes, then you should consider using data classes instead of namedtuple.

namedtuple vs typing.NamedTuple

The typing.NamedTuple class is another alternative to namedtuple. It’s part of the typing module and provides a way to define classes with named fields using type hints.

The main advantage of typing.NamedTuple over namedtuple is that it allows you to specify the types of the fields using annotations. This can be useful for static analyzers and IDEs that support type checking.

If you’re using Python 3.6 or later and you want to take advantage of type hints, then you should consider using typing.NamedTuple instead of namedtuple.

Subclassing namedtuple Classes

namedtuple classes are regular classes, which means you can subclass them and provide additional functionality.

For example, let’s say you have a Point class and you want to add a method to calculate the distance between two points:

Point = namedtuple('Point', ['x', 'y'])


class EnhancedPoint(Point):
    def distance_to(self, other_point):
        dx = other_point.x - self.x
        dy = other_point.y - self.y
        return (dx ** 2 + dy ** 2) ** 0.5

Now, you can create instances of the EnhancedPoint class and use the distance_to() method to calculate the distance between them:

p1 = EnhancedPoint(1, 2)
p2 = EnhancedPoint(4, 6)
distance = p1.distance_to(p2)


print(f"The distance is {distance}")

Measuring Creation Time: tuple vs namedtuple

One of the concerns when using namedtuple is whether it adds any overhead compared to regular tuples. To answer this question, let’s measure the creation time of both data structures.

import timeit
from collections import namedtuple


Point = namedtuple('Point', ['x', 'y'])
n = 1000000


def create_tuple():
    for i in range(n):
        t = (i, i)


def create_namedtuple():
    for i in range(n):
        p = Point(i, i)


tuple_creation_time = timeit.timeit(create_tuple, number=1)
namedtuple_creation_time = timeit.timeit(create_namedtuple, number=1)


print(f"Tuple creation time: {tuple_creation_time}")
print(f"Namedtuple creation time: {namedtuple_creation_time}")

Conclusion

In this tutorial, you’ve learned how to use namedtuple to write more Pythonic and clean code. namedtuple allows you to create tuple-like classes with named fields, which makes your code more readable and less error-prone. You’ve also explored some of the additional features of namedtuple and learned when to use it compared to other data structures.

By using namedtuple, you can improve the readability and expressiveness of your code, making it easier to understand and maintain. It’s a powerful tool that every Python developer should have in their toolbox.

Now that you have a good understanding of namedtuple, you can start using it in your own projects and take advantage of its features to write more Pythonic code.

CodeMDD.io