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) # 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 named tuple also can accept fields names as:
1) A tuple of strings:
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
Code 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
200
Code language: Python (python)
The rename argument of the named tuple 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 namedtupleCircle = 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 namedtupleCircle = 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) # True
Code 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)) # 100
Code language: Python (python)
Summary
- Named tuples are tuples whose element positions have meaningful names.
- Use the
namedtuple
function of thecollections
standard library to create a named tuple class. - Named tuples are immutable.