7.3.5. namedtuple() - фабричная функция для кортежей с именованными полями

Именованные кортежи определяют имена для каждой позиции в кортеже  и позволяют создавать более читаемый и понятный код. Они могут быть использованы в тех же случаях, что и обычные кортежи, а обращаться к полям можно не только по индексу, но и по имени.

collections.namedtuple(typename, field_names, verbose=False, rename=False)

Возвращает новый подкласс кортежа с именем typename. Новый подкласс используется для создания кортежеподобных объектов, поля которых доступны как для просмотра через атрибуты, так и для индексации и итерации. Экземпляры этого подкласса так же содержат строку документации (с именем типа и именами полей)  и полезный метод __repr__(),который отображает содержимое кортежа в форме name=value.

field_names - одна строка, где каждое имя поля отделено от другого пробелами и/или запятыми, например 'x y' or 'x, y'. Кроме того, в этом параметре можно передать последовательность строк ['x', 'y'].

Любые корректные идентификаторы Python могут использоваться в качестве имён полей, за исключением имён, начинающихся с нижнего подчёркивания. Корректные идентификаторы состоят из букв, цифр и нижних подчёркиваний, но не начинается с цифры или нижнего подчёркивания, а так же не может совпадать с одним из keyword например class, for, return, global, pass, или raise.

Если rename=true, некорректные имена полей автоматически заменяются позиционными именами, например ['abc', 'def', 'ghi', 'abc'] будет преобразовано в ['abc', '_1', 'ghi', '_3'], заменив ключевое слово def и повторяющееся имя поля abc.

Если verbose = true, определение класса будет напечатано после того, как класс будет создан. Эта опция устаревшая, вместо неё проще распечатать атрибут _source.

Экземпляры именованного кортежа не имеют своего личного словаря, так что они занимают не больше места, чем обычные кортежи..

Изменения в версии 3.1: Добавлена поддержка метода rename.

>>>

>>> # простой пример
>>> Point = namedtuple('Point', ['x', 'y'])
>>> p = Point(11, y=22)     # создаём экземпляр с позиционными или именованными аргументами
>>> p[0] + p[1]             # можно получать значения по индексу, как в обычном кортеже (11, 22)
33
>>> x, y = p                # распаковывается как обычный кортеж
>>> x, y
(11, 22)
>>> p.x + p.y               # поля доступны и по именам
33
>>> p                       # метод __repr__ с форматом name=value
Point(x=11, y=22)

Именованные кортежи особенно полезны для задания имён полей кортежей, возвращаемых модулями csv или sqlite3:

EmployeeRecord = namedtuple('EmployeeRecord', 'name, age, title, department, paygrade')

import csv
for emp in map(EmployeeRecord._make, csv.reader(open("employees.csv", "rb"))):
    print(emp.name, emp.title)

import sqlite3
conn = sqlite3.connect('/companydata')
cursor = conn.cursor()
cursor.execute('SELECT name, age, title, department, paygrade FROM employees')
for emp in map(EmployeeRecord._make, cursor.fetchall()):
    print(emp.name, emp.title)

В дополнение к методам, унаследованным от кортежей, именованные кортежи поддерживают три дополнительных метода и два атрибута. Для того, чтобы предотвратить конфликты с именами полей, эти методы и атрибуты начинаются с нижних подчёркиваний.

classmethod somenamedtuple._make(iterable)

Метод класса, который создаёт новый экземпляр из существующей последовательности или итератора.

>>>

>>> t = [11, 22]
>>> Point._make(t)
Point(x=11, y=22)

somenamedtuple._asdict()

Возвращает новый OrderedDict который отображает имена полей на соответствующие значения. Обратите внимание, что этот метод уже не требуется, так как тот же самый эффект может быть достигнут при помощи встроенной функции vars():

>>>

>>> vars(p)
OrderedDict([('x', 11), ('y', 22)])

Изменения в версии 3.1: Возвращает OrderedDict вместо обычного dict.

somenamedtuple._replace(kwargs)

Возвращает новый экземпляр именованного кортежа, заменяя определённые пля новыми значениями:

>>>

>>> p = Point(x=11, y=22)
>>> p._replace(x=33)
Point(x=33, y=22)

>>> for partnum, record in inventory.items():
...     inventory[partnum] = record._replace(price=newprices[partnum], timestamp=time.now())

somenamedtuple._source

Строка с исходным кодом Python, используемым для создания класса именованного кортежа. Этот код позволяет легко получить документацию для именованного кортежа. Его можно вывести на экран, выполнить при помощи exec(), или сохранить в файл и импортировать.

Добавлено в версии 3.3.

somenamedtuple._fields

Кортеж строк с именами полей. Полезен для интроспекции и для создания новых типов именованных кортежей из уже существующих.

>>>

>>> p._fields            # просмотреть имена полей
('x', 'y')

>>> Color = namedtuple('Color', 'red green blue')
>>> Pixel = namedtuple('Pixel', Point._fields + Color._fields)
>>> Pixel(11, 22, 128, 255, 0)
Pixel(x=11, y=22, red=128, green=255, blue=0)

Чтобы получить значения полей, чьи имена сохранены как строки, используйте функцию getattr():

>>>

>>> getattr(p, 'x')
11

Что преобразовать словарь в именованный кортеж используйте операцию распаковывания словаря (как описано в Unpacking Argument Lists):

>>>

>>> d = {'x': 11, 'y': 22}
>>> Point(**d)
Point(x=11, y=22)

Так как именованный кортеж - это обычный класс Python, к нему легко добавлять новую функциональность или изменить уже существующую, просто создавая его подклассы. Тут показано как добавить подсчитываемое поле и изменить формат отображения класса:

>>>

>>> class Point(namedtuple('Point', 'x y')):
    __slots__ = ()
    @property
    def hypot(self):
        return (self.x ** 2 + self.y ** 2) ** 0.5
    def __str__(self):
        return 'Point: x=%6.3f  y=%6.3f  hypot=%6.3f' % (self.x, self.y, self.hypot)

>>>

>>> for p in Point(3, 4), Point(14, 5/7):
    print(p)
Point: x= 3.000  y= 4.000  hypot= 5.000
Point: x=14.000  y= 0.714  hypot=14.018

Подкласс, показанный выше, устанавливает атрибут __slots__ в пустой кортеж. Это помогает сократить использование памяти, не допуская создавать словари для экземпляров.

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

>>>

>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))

Значения по умолчанию можно реализовать используя метод _replace() для настройки экземпляра прототипа

>>>

>>> Account = namedtuple('Account', 'owner balance transaction_count')
>>> default_account = Account('<owner name>', 0.0, 0)
>>> johns_account = default_account._replace(owner='John')
>>> janes_account = default_account._replace(owner='Jane')

Перечисляемые константы можно задать при помощи именованного кортежа, но  проще сделать это используя  простой класс:

>>>

>>> Status = namedtuple('Status', 'open pending closed')._make(range(3))
>>> Status.open, Status.pending, Status.closed
(0, 1, 2)
>>> class Status:
    open, pending, closed = range(3)

См также

• Именованные кортежи для Python 2.4.
• Абстрактный базовый класс именованного кортежа с примешиваемым метаклассом от Jan Kaliszewski. Помимо предоставления абстрактного базового класса для именованных кортежей, он так же поддерживает альтернативный конструктор, основанный на метаклассе.