Data Structures and Collections

Sun, 01 May 2022 00:00:00 +0000

Namedtuple

Sat, 02 May 2020 00:00:00 +0000

TL;DR

collection.namedtuple is a memory-efficient shortcut to defining an immutable class in Python manually.
Namedtuples can help clean up your code by enforcing an easier to understand structure on your data, which also improves readability.
Namedtuples provide a few useful helper methods that all start with an _ underscore—but are part of the public interface.

What is `namedtuple`?

Python’s tuple is a simple immutable data structure for grouping arbitrary objects. It has two shortcomings:

The data you store in it can only be pulled out by accessing it through integer indexes. You can’t give names to individual properties stored in a tuple. This can impact code readability.
It’s hard to ensure that two tuples have the same number of fields and the same properties stored on them.

namedtuple aims to solve these two problems. namedtuple is a factory function for making a tuple class. With that class we can create tuples that are callable by name also.

namedtuple is immutable just like regular tuple
- Once you store data in top-level attribute on a namedtuple, you can’t modify it by updating the attribute.
- All attributes on a namedtuple object follow the “write once, read many” principle.
Each object stored in them can be accessed through a unique (human-readable) string identifier.

→ This frees you from having to remember integer indexes, or resorting to workarounds like defining integer constants as mnemonics for your indexes. 👏

How `namedtuple` works?

Let’s take a look at an example:

from collections import namedtuple

User = namedtuple("User", ["name", "id", "gender"])
user = User("Ecko", 1, "male")

>>> user
User(name='Ecko', id=1, gender='male')

"User" as the first argument to the namedtuple factory function is referred to as the “typename” in the Python docs. It’s the name of the new class that’s being created by calling the namedtuple function, which needs to be explicitly specified.

The code above is equivalent to

class User:
 def __init__(self, name, id, gender):
 self.name = name
 self.id = id
 self.gender = gender

user = User("Ecko", 1, "male")

Why `namedtuple`?

Namedtuple objects are implemented as regular Python classes internally. When it comes to memory usage, they are also “better” than regular classes and just as memory efficient as regular tuples. 👍

A good way to view them is to think that namedtuples are a memory-efficient shortcut to defining an immutable class in Python manually.

Operations

Unpacking

Tuple unpacking and the *-operator for function argument unpacking also work as expected:

name, id, gender = user
print(f"name: {name}, id: {id}, gender: {gender}")

name: Ecko, id: 1, gender: male

print(*user)

Ecko 1 male

Accessing Values

Values can be accessed either by identifier or by index.

By identifier:

>>> user.name
Ecko

By index:

>>> user[0]
Ecko

Built-in Helper Functions

namedtuple has some useful helper methods.

Their names all start with an underscore character _
- With namedtuples the underscore naming convention has a different meaning though: These helper methods and properties are part of namedtuple’s public interface.
- The helpers were named that way to avoid naming collisions with user-defined tuple fields.

`_asdict`

Returns the contents of a namedtuple as a dictionary

>>> user._asdict()
OrderedDict([('name', 'Ecko'), ('id', 1), ('gender', 'male')])

This is great for avoiding typos in the field names when generating JSON-output, for example:

>>> import json
>>> json.dumps(user._asdict())
'{"name": "Ecko", "id": 1, "gender": "male"}'

We can convert a dictionary into a namedtuple with ** operator

>>> user_dict = {"name": "Ben", "id": 2, "gender": "male"}
>>> User(**user_dict)
User(name='Ben', id=2, gender='male')

`_replace()`

Creates a (shallow) copy of a tuple and allows you to selectively replace some of its fields.

user._replace(id=2)

User(name='Ecko', id=2, gender='male')

`_make()`

Classmethod can be used to create new instances of a namedtuple from a sequence or iterable

User._make(["Ilona", 3, "female"])

User(name='Ilona', id=3, gender='female')

When to Use `namedtuple`?

If you’re going to create a bunch of instances of a class and NOT change the attributes after you set them in __init__, you can consider to use namedtuple.
- Example: Definition of classes in torchvision.datasets.cityscapes
Namedtuples can be an easy way to clean up your code and to make it more readable by enforcing a better structure for your data. You should use namedtuple anywhere you think object notation will make your code more pythonic and more easily readable
But try NOT to use namedtuples for their own sake if they don’t help you write “cleaner” and more maintainable code.

Collection | Haobin Tan

Data Structures and Collections

Namedtuple

What is `namedtuple`?

How `namedtuple` works?

Why `namedtuple`?

Operations

Unpacking

Accessing Values

Built-in Helper Functions

`_asdict`

`_replace()`

`_make()`

When to Use `namedtuple`?

Reference

Collection | Haobin Tan

Data Structures and Collections

Namedtuple

What is namedtuple?

How namedtuple works?

Why namedtuple?

Operations

Unpacking

Accessing Values

Built-in Helper Functions

_asdict

_replace()

_make()

When to Use namedtuple?

Reference

What is `namedtuple`?

How `namedtuple` works?

Why `namedtuple`?

`_asdict`

`_replace()`

`_make()`

When to Use `namedtuple`?