namedtuple в Python: кортеж с именами полей

В предыдущем уроке функция вернула пару значений, и распаковка дала каждой величине имя. Но как только пара начинает путешествовать по программе — лежать в списке, передаваться в другую функцию, — имена остаются только в голове автора. Запись point[0] не говорит, координата это или имя пользователя. namedtuple из стандартного модуля collections закрывает именно эту дыру: кортеж, у которого у каждого поля есть имя. Внутри — всё тот же tuple из урока 11, снаружи — читаемые поля.

Проблема: индексы без имён

Обычный кортеж не помнит, что он значит. Две записи — точка на плоскости и гость с числом визитов — выглядят снаружи одинаково:

point = (3, 4)
guest = ('Анна', 3)

print(point[0] + point[1])
print(guest[0], guest[1])

7
Анна 3

Код работает, но каждый, кто его читает — включая вас через месяц, — вынужден помнить: нулевой индекс у guest это имя, первый — число визитов. Перепутать места при создании записи Python не заметит: guest = (3, 'Анна') — тоже кортеж, только смыслы поменяны местами. Чем сложнее запись, тем дороже эта памятка.

namedtuple: имя для каждого поля

namedtuple — это фабрика классов: она принимает имя типа и список полей, а возвращает новый класс кортежа. Один раз описали поля — дальше создаёте записи как объекты:

from collections import namedtuple

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

p = Point(3, 4)
print(p.x, p.y)
print(p)
print(type(p).__name__)

3 4
Point(x=3, y=4)
Point

Три строки дали то, чего у обычного кортежа не было. Доступ по имени: p.x вместо p[0], и перепутать поля при чтении невозможно. Печать кортежа показывает и поля, и значения: Point(x=3, y=4) — запись сама рассказывает, из чего состоит. А вызов type показывает, что namedtuple действительно создал новый класс с именем Point: переменная Point — это класс, p — его экземпляр.

Это всё ещё кортеж

Главная сила namedtuple — он не заменяет кортеж, а наследует его. namedtuple остаётся кортежем со всеми правами: доступ по индексу, длина, распаковка и сравнение с обычным tuple работают без оговорок.

from collections import namedtuple

Point = namedtuple('Point', ['x', 'y'])
p = Point(3, 4)

print(p[0], p[1])
print(len(p))
x, y = p
print('распаковка:', x, y)
print(p == (3, 4))

3 4
2
распаковка: 3 4
True

Равенство с обычным кортежем сработало: namedtuple сравнивается по значениям, и (3, 4) ему родной. Значит, namedtuple можно передавать туда, где ждут кортеж: в функции из урока 14, в ключи словаря, в множества — он хешируем, как любой кортеж из неизменяемых значений. Старый код с индексами продолжит работать, новый — читает по именам.

Поля строкой и значения по умолчанию

Список полей — не единственная запись: строка с именами через пробел короче и встречается в чужом коде чаще. А параметр defaults задаёт значения по умолчанию для полей справа, и тогда часть аргументов можно не указывать:

from collections import namedtuple

Visitor = namedtuple('Visitor', 'name days')
Returning = namedtuple('Returning', ['name', 'days'], defaults=[1])

v = Visitor('Анна', 3)
r = Returning('Борис')

print(v.name, '-', v.days)
print(r.name, '-', r.days)

Анна - 3
Борис - 1

defaults раскладываются на поля справа: у Returning единица досталась полю days, а обязательное имя осталось обязательным. Приём удобен для записей, где чаще всего повторяется одно и то же значение — визит по умолчанию одноразовый, и только постоянные гости требуют второго числа.

Список записей: где namedtuple раскрывается

Один namedtuple — приятность, список namedtuple — рабочий инструмент. Журнал гостей превращается в таблицу, у которой вместо индексов колонки:

from collections import namedtuple

Visitor = namedtuple('Visitor', 'name days')
visitors = [
    Visitor('Анна', 3),
    Visitor('Борис', 1),
    Visitor('Вера', 2),
]

total = 0
for v in visitors:
    print(v.name, '-', v.days)
    total += v.days

print('сумма визитов:', total)
print('самый частый гость:', max(visitors, key=lambda v: v.days).name)

Анна - 3
Борис - 1
Вера - 2
сумма визитов: 6
самый частый гость: Анна

Строка v.name читается без заглядывания в памятку, а max с key=lambda v: v.days находит запись с наибольшим полем и забирает из неё имя. С обычными кортежами то же самое выглядело бы как v[0] и key=lambda v: v[1] — работает, но каждый раз требует расшифровки.

from collections import namedtuple

Point = namedtuple('Point', 'x y')
p = Point(3, 4)
moved = p._replace(y=10)

print(p)
print(moved)

Point(x=3, y=4)
Point(x=3, y=10)

Исходная точка не сдвинулась: _replace построил новый кортеж, и это ровно то поведение, которое у кортежей по умолчанию. Если полям нужно меняться часто и по месту — namedtuple не тот инструмент: берите словарь или класс из курса ООП.

from collections import namedtuple

try:
    Bad = namedtuple('Bad', 'name _days')
except ValueError as e:
    print('ValueError:', e)

ValueError: Field names cannot start with an underscore: '_days'

_asdict: мост к словарю

Когда запись нужно превратить в словарь — отправить в JSON, передать функции, ждущей ключи, — есть готовый метод:

from collections import namedtuple

Visitor = namedtuple('Visitor', 'name days')
v = Visitor('Анна', 3)

d = v._asdict()
print(d)
print(d['days'])

{'name': 'Анна', 'days': 3}
3

Порядок полей в словаре — тот же, что при объявлении namedtuple: словарь Python помнит порядок вставки, и колонки не перемешаются. Обратного хода нет: namedtuple из словаря собирают явно, перечисляя значения по ключам.

Правило выбора простое: если данные — фиксированный набор полей, который читают чаще, чем меняют, — namedtuple даёт имена, не теряя кортежных прав. Если состав полей растёт и меняется — словарь.

Что дальше

namedtuple снял последую проблему кортежей — безымянность. Дальше две практические темы: дубликаты одной строкой — как множество и словарь чистят список от повторов, и общие механизмы множеств и словарей — почему namedtuple годится в ключ, а список нет.

Пять строк на фабрику класса — и записи в программе читаются как записи: у каждого поля имя, у каждого кортежа честный repr с перечислением полей. Старый кортежный код продолжает работать, потому что namedtuple — это кортеж.