Python namedtuple

last modified January 29, 2024

Python namedtuple tutorial shows how to work with namedtuples in Python.

Python namedtuple

Python namedtuple is an immutable container type, whose values can be accessed with indexes and named attributes. It has functionality like tuples with additional features. A named tuple is created with the collections.namedtuple factory function.

Named tuples are essentially easy-to-create, immutable, lightweight object types. Named tuples can be used to make the code more clean and Pythonic. They are similar to records in other languages (C#, Java).

Python namedtuple basic example

The following is a simple example with a namedtuple.

basic.py

#!/usr/bin/python

from collections import namedtuple

City = namedtuple(‘City’ , ’name population’)

c1 = City(‘Bratislava’, 432000) c2 = City(‘Budapest’, 1759000)

print(c1) print(c2)

The example create city namedtuples.

from collections import namedtuple

First, we import the namedtuple type from the collections module.

City = namedtuple(‘City’ , ’name population’)

We define the namedtuple. The first argument is the name for the namedtuple. The second argument are the field names. These can be specified in a string ’name population’ or in a list [’name’, ‘population’].

c1 = City(‘Bratislava’, 432000) c2 = City(‘Budapest’, 1759000)

Here we create two namedtuple objects.

$ ./basic.py City(name=‘Bratislava’, population=432000) City(name=‘Budapest’, population=1759000)

Python namedtuple accessing

The namedtuples can be accessed using indexing and their named attributes.

accessing.py

#!/usr/bin/python

from collections import namedtuple

City = namedtuple(‘City’ , ’name population’)

c1 = City(‘Bratislava’, 432000) c2 = City(‘Budapest’, 1759000)

print(c1[0]) print(c1[1])

print(c2.name) print(c2.population)

In the example, we demonstrate both ways.

$ ./accessing.py Bratislava 432000 Budapest 1759000

Python namedtuple unpacking

The unpacking is storing iterable elements into variables or function arguments.

unpacking.py

#!/usr/bin/python

from collections import namedtuple

City = namedtuple(‘City’ , ’name population’)

c1 = City(‘Bratislava’, 432000) c2 = City(‘Budapest’, 1759000)

name, population = c1 print(f’{name}: {population}’)

print(’———————-’)

print(c2) print(*c2, sep=’: ‘)

In the example, we unpack our namedtuples.

name, population = c1

Here we unpack the c1 namedtuple into two variables.

print(*c2, sep=’: ‘)

Here we unpack the c2 namedtuple with the * operator into print function arguments, which are joined with the given separator into the final output.

$ ./unpacking.py Bratislava: 432000

City(name=‘Budapest’, population=1759000) Budapest: 1759000

unpacking2.py

#!/usr/bin/python

from collections import namedtuple

City = namedtuple('City' , 'name population')

d = { 'name': 'Bratislava', 'population': 432000}

c = City(**d)
print(c)

With the ** operator, we can unpack a dictionary into arguments of a namedtuple.

Python namedtuple subclassing

Since namedtuples are built on top of regular classes, we can
add functionality to them.

subclassing.py

#!/usr/bin/python

from collections import namedtuple from math import sqrt

class Point(namedtuple(‘Point’, ‘x y’)):

__slots__ = ()

@property
def hypot(self):
    return sqrt((self.x ** 2 + self.y ** 2))

def __str__(self):
    return f'Point: x={self.x}  y={self.y}  hypot={self.hypot}'

p = Point(5, 5) print(p.hypot) print(p)

We have a Point namedtuple. We add the hypot property to it.

$ ./subclassing.py 7.0710678118654755 Point: x=5 y=5 hypot=7.0710678118654755

Python typing.NamedTuple

Since Python 3.6, we can use the typing.NamedTuple to create a namedtuple.

named_tuple.py

#!/usr/bin/python

from typing import NamedTuple

class City(NamedTuple): name: str population: int

c1 = City(‘Bratislava’, 432000) c2 = City(‘Budapest’, 1759000)

print(c1) print(c2)

In the example, we have a City class that inherits from the typing.NamedTuple. The attributes have typehints.

Python namedtuple defaults

The defaults parameter can be used to provide default values to fields.

defaults.py

#!/usr/bin/python

from collections import namedtuple from math import sqrt

class Point(namedtuple(‘Point’, ‘x y’, defaults=[1, 1])):

__slots__ = ()

@property
def hypot(self):
    return sqrt((self.x ** 2 + self.y ** 2))

def __str__(self):
    return f'Point: x={self.x}  y={self.y}  hypot={self.hypot}'

p1 = Point(5, 5) print(p1)

p2 = Point() print(p2)

The default value for x and y is 1.

$ ./defaults.py Point: x=5 y=5 hypot=7.0710678118654755 Point: x=1 y=1 hypot=1.4142135623730951

Python namedtuple helpers

Python provides several helper methods for a namedtuple.

helpers.py

#!/usr/bin/python

from typing import NamedTuple

class Point(NamedTuple):

x: int = 1
y: int = 1

p = Point(5, 5)

print(p._fields) print(p._field_defaults) print(p._asdict())

The _fields is a tuple of strings listing the field names. The _field_defaults is a dictionary mapping field names to default values. The _asdict method returns a new ordered dictionary, which maps field names to their corresponding values.

$ ./helpers.py (‘x’, ‘y’) {‘x’: 1, ‘y’: 1} OrderedDict([(‘x’, 5), (‘y’, 5)])

Python namedtuple - serialize to JSON

The _asdict method can be used to serialize namedtuples into JSON format.

json_output.py

#!/usr/bin/python

from typing import NamedTuple import json

class City(NamedTuple): name: str population: int

c1 = City(‘Bratislava’, 432000) c2 = City(‘Budapest’, 1759000) c3 = City(‘Prague’, 1280000) c4 = City(‘Warsaw’, 1748000)

cities = [c1, c2, c3, c4]

print(json.dumps(c1._asdict()))

json_string = json.dumps([city._asdict() for city in cities]) print(json_string)

With the help of the json.dumps method, we serialize a single city and a list of cities.

$ ./json_output.py {“name”: “Bratislava”, “population”: 432000} [{“name”: “Bratislava”, “population”: 432000}, {“name”: “Budapest”, “population”: 1759000}, {“name”: “Prague”, “population”: 1280000}, {“name”: “Warsaw”, “population”: 1748000}]

Python namedtuple sort

In the following example, we sort a list of namedtuples.

sorting.py

#!/usr/bin/python

from typing import NamedTuple

class City(NamedTuple): id: int name: str population: int

c1 = City(1, ‘Bratislava’, 432000) c2 = City(2, ‘Budapest’, 1759000) c3 = City(3, ‘Prague’, 1280000) c4 = City(4, ‘Warsaw’, 1748000) c5 = City(5, ‘Los Angeles’, 3971000) c6 = City(6, ‘Edinburgh’, 464000) c7 = City(7, ‘Berlin’, 3671000)

cities = [c1, c2, c3, c4, c5, c6, c7]

cities.sort(key=lambda e: e.name)

for city in cities: print(city)

With the help of the sort method and the lambda function, we sort cities by their name.

$ ./sorting.py City(id=7, name=‘Berlin’, population=3671000) City(id=1, name=‘Bratislava’, population=432000) City(id=2, name=‘Budapest’, population=1759000) City(id=6, name=‘Edinburgh’, population=464000) City(id=5, name=‘Los Angeles’, population=3971000) City(id=3, name=‘Prague’, population=1280000) City(id=4, name=‘Warsaw’, population=1748000)

The cities are sorted by their names in ascending order.

Python namedtuple _make helper

The _make is method that makes a new instance of a namedtuple from an existing sequence or iterable.

making.py

#!/usr/bin/python

from collections import namedtuple

City = namedtuple(‘City’ , ’name population’)

c1 = City._make((‘Bratislava’, 432000)) c2 = City._make((‘Budapest’, 1759000))

print(c1) print(c2)

The example creates City namedtuples from tuples with the help of the _make method.

Python namedtuple - read CSV data

Python namedtuples are helpful when we read CSV data.

cities.csv

Bratislava, 432000 Budapest, 1759000 Prague, 1280000 Warsaw, 1748000 Los Angeles, 3971000 New York, 8550000 Edinburgh, 464000 Berlin, 3671000

We have this CSV file.

read_csv.py

#!/usr/bin/python

from collections import namedtuple import csv

City = namedtuple(‘City’ , ’name population’)

f = open(‘cities.csv’, ‘r’)

with f:

reader = csv.reader(f)

for city in map(City._make, reader):
    print(city)

We use the map and the _make functions to create clean code.

$ ./read_csv.py City(name=‘Bratislava’, population=’ 432000’) City(name=‘Budapest’, population=’ 1759000’) City(name=‘Prague’, population=’ 1280000’) City(name=‘Warsaw’, population=’ 1748000’) City(name=‘Los Angeles’, population=’ 3971000’) City(name=‘New York’, population=’ 8550000’) City(name=‘Edinburgh’, population=’ 464000’) City(name=‘Berlin’, population=’ 3671000’)

Python namedtuple - read SQLite database

In the following example, we use a namedtuple to read data from SQLite database.

cities.sql

DROP TABLE IF EXISTS cities; CREATE TABLE cities(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, population INTEGER);

INSERT INTO cities(name, population) VALUES(‘Bratislava’, 432000); INSERT INTO cities(name, population) VALUES(‘Budapest’, 1759000); INSERT INTO cities(name, population) VALUES(‘Prague’, 1280000); INSERT INTO cities(name, population) VALUES(‘Warsaw’, 1748000); INSERT INTO cities(name, population) VALUES(‘Los Angeles’, 3971000); INSERT INTO cities(name, population) VALUES(‘New York’, 8550000); INSERT INTO cities(name, population) VALUES(‘Edinburgh’, 464000); INSERT INTO cities(name, population) VALUES(‘Berlin’, 3671000);

These are SQL statements to create the cities table.

$ sqlite3 ydb.db SQLite version 3.31.1 2020-01-27 19:55:54 Enter “.help” for usage hints. sqlite> .read cities.sql

With the sqlite3 command line tool, we generate the SQLite database and the cities table.

read_sql.py

#!/usr/bin/python

from typing import NamedTuple import sqlite3 as sqlite

class City(NamedTuple):

id: int
name: str
population: int

con = sqlite.connect(‘ydb.db’)

with con:

cur = con.cursor()

cur.execute('SELECT * FROM cities')

for city in map(City._make, cur.fetchall()):
    print(city)

We read all data from the cities table and transform each table row into a City namedtuple.

Source

Python collections - language reference

In this article we have worked with Python namedtuple.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Python tutorials.