What are "named tuples" in Python?

Named tuples are basically easy-to-create, lightweight object types. Named tuple instances can be referenced using object-like variable dereferencing or the standard tuple syntax. They can be used similarly to struct or other common record types, except that they are immutable. They were added in Python 2.6 and Python 3.0, although there is a recipe for implementation in Python 2.4.

For example, it is common to represent a point as a tuple (x, y). This leads to code like the following:

pt1 = (1.0, 5.0)pt2 = (2.5, 1.5)from math import sqrtline_length = sqrt((pt1[0]-pt2[0])**2 + (pt1[1]-pt2[1])**2)

Using a named tuple it becomes more readable:

from collections import namedtuplePoint = namedtuple('Point', 'x y')pt1 = Point(1.0, 5.0)pt2 = Point(2.5, 1.5)from math import sqrtline_length = sqrt((pt1.x-pt2.x)**2 + (pt1.y-pt2.y)**2)

However, named tuples are still backwards compatible with normal tuples, so the following will still work:

Point = namedtuple('Point', 'x y')pt1 = Point(1.0, 5.0)pt2 = Point(2.5, 1.5)from math import sqrt# use index referencingline_length = sqrt((pt1[0]-pt2[0])**2 + (pt1[1]-pt2[1])**2) # use tuple unpackingx1, y1 = pt1

Thus, you should use named tuples instead of tuples anywhere you think object notation will make your code more pythonic and more easily readable. I personally have started using them to represent very simple value types, particularly when passing them as parameters to functions. It makes the functions more readable, without seeing the context of the tuple packing.

Furthermore, you can also replace ordinary immutable classes that have no functions, only fields with them. You can even use your named tuple types as base classes:

class Point(namedtuple('Point', 'x y')):    [...]

However, as with tuples, attributes in named tuples are immutable:

>>> Point = namedtuple('Point', 'x y')>>> pt1 = Point(1.0, 5.0)>>> pt1.x = 2.0AttributeError: can't set attribute

If you want to be able change the values, you need another type. There is a handy recipe for mutable recordtypes which allow you to set new values to attributes.

>>> from rcdtype import *>>> Point = recordtype('Point', 'x y')>>> pt1 = Point(1.0, 5.0)>>> pt1 = Point(1.0, 5.0)>>> pt1.x = 2.0>>> print(pt1[0])    2.0

I am not aware of any form of "named list" that lets you add new fields, however. You may just want to use a dictionary in this situation. Named tuples can be converted to dictionaries using pt1._asdict() which returns {'x': 1.0, 'y': 5.0} and can be operated upon with all the usual dictionary functions.

As already noted, you should check the documentation for more information from which these examples were constructed.

namedtuple is a factory function for making a tuple class. With that class we can create tuples that are callable by name also.

import collections#Create a namedtuple class with names "a" "b" "c"Row = collections.namedtuple("Row", ["a", "b", "c"])   row = Row(a=1,b=2,c=3) #Make a namedtuple from the Row class we createdprint row    #Prints: Row(a=1, b=2, c=3)print row.a  #Prints: 1print row[0] #Prints: 1row = Row._make([2, 3, 4]) #Make a namedtuple from a list of valuesprint row   #Prints: Row(a=2, b=3, c=4)

What are named tuples?

A named tuple is a tuple.

It does everything a tuple can.

But it's more than just a tuple.

It's a specific subclass of a tuple that is programmatically created to your specification, with named fields and a fixed length.

This, for example, creates a subclass of tuple, and aside from being of fixed length (in this case, three), it can be used everywhere a tuple is used without breaking. This is known as Liskov substitutability.

New in Python 3.6, we can use a class definition with typing.NamedTuple to create a namedtuple:

from typing import NamedTupleclass ANamedTuple(NamedTuple):    """a docstring"""    foo: int    bar: str    baz: list

The above is the same as the below, except the above additionally has type annotations and a docstring. The below is available in Python 2+:

>>> from collections import namedtuple>>> class_name = 'ANamedTuple'>>> fields = 'foo bar baz'>>> ANamedTuple = namedtuple(class_name, fields)

This instantiates it:

>>> ant = ANamedTuple(1, 'bar', [])

We can inspect it and use its attributes:

>>> antANamedTuple(foo=1, bar='bar', baz=[])>>> ant.foo1>>> ant.bar'bar'>>> ant.baz.append('anything')>>> ant.baz['anything']

Deeper explanation

To understand named tuples, you first need to know what a tuple is. A tuple is essentially an immutable (can't be changed in-place in memory) list.

Here's how you might use a regular tuple:

>>> student_tuple = 'Lisa', 'Simpson', 'A'>>> student_tuple('Lisa', 'Simpson', 'A')>>> student_tuple[0]'Lisa'>>> student_tuple[1]'Simpson'>>> student_tuple[2]'A'

You can expand a tuple with iterable unpacking:

>>> first, last, grade = student_tuple>>> first'Lisa'>>> last'Simpson'>>> grade'A'

Named tuples are tuples that allow their elements to be accessed by name instead of just index!

You make a namedtuple like this:

>>> from collections import namedtuple>>> Student = namedtuple('Student', ['first', 'last', 'grade'])

You can also use a single string with the names separated by spaces, a slightly more readable use of the API:

>>> Student = namedtuple('Student', 'first last grade')

How to use them?

You can do everything tuples can do (see above) as well as do the following:

>>> named_student_tuple = Student('Lisa', 'Simpson', 'A')>>> named_student_tuple.first'Lisa'>>> named_student_tuple.last'Simpson'>>> named_student_tuple.grade'A'>>> named_student_tuple._asdict()OrderedDict([('first', 'Lisa'), ('last', 'Simpson'), ('grade', 'A')])>>> vars(named_student_tuple)OrderedDict([('first', 'Lisa'), ('last', 'Simpson'), ('grade', 'A')])>>> new_named_student_tuple = named_student_tuple._replace(first='Bart', grade='C')>>> new_named_student_tupleStudent(first='Bart', last='Simpson', grade='C')

A commenter asked:

In a large script or programme, where does one usually define a named tuple?

The types you create with namedtuple are basically classes you can create with easy shorthand. Treat them like classes. Define them on the module level, so that pickle and other users can find them.

The working example, on the global module level:

>>> from collections import namedtuple>>> NT = namedtuple('NT', 'foo bar')>>> nt = NT('foo', 'bar')>>> import pickle>>> pickle.loads(pickle.dumps(nt))NT(foo='foo', bar='bar')

And this demonstrates the failure to lookup the definition:

>>> def foo():...     LocalNT = namedtuple('LocalNT', 'foo bar')...     return LocalNT('foo', 'bar')... >>> pickle.loads(pickle.dumps(foo()))Traceback (most recent call last):  File "<stdin>", line 1, in <module>_pickle.PicklingError: Can't pickle <class '__main__.LocalNT'>: attribute lookup LocalNT on __main__ failed

Why/when should I use named tuples instead of normal tuples?

Use them when it improves your code to have the semantics of tuple elements expressed in your code.

You can use them instead of an object if you would otherwise use an object with unchanging data attributes and no functionality.

You can also subclass them to add functionality, for example:

class Point(namedtuple('Point', 'x y')):    """adding functionality to a named tuple"""        __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)

Why/when should I use normal tuples instead of named tuples?

It would probably be a regression to switch from using named tuples to tuples. The upfront design decision centers around whether the cost from the extra code involved is worth the improved readability when the tuple is used.

There is no extra memory used by named tuples versus tuples.

Is there any kind of "named list" (a mutable version of the named tuple)?

You're looking for either a slotted object that implements all of the functionality of a statically sized list or a subclassed list that works like a named tuple (and that somehow blocks the list from changing in size.)

A now expanded, and perhaps even Liskov substitutable, example of the first:

from collections import Sequenceclass MutableTuple(Sequence):     """Abstract Base Class for objects that work like mutable    namedtuples. Subclass and define your named fields with     __slots__ and away you go.    """    __slots__ = ()    def __init__(self, *args):        for slot, arg in zip(self.__slots__, args):            setattr(self, slot, arg)    def __repr__(self):        return type(self).__name__ + repr(tuple(self))    # more direct __iter__ than Sequence's    def __iter__(self):         for name in self.__slots__:            yield getattr(self, name)    # Sequence requires __getitem__ & __len__:    def __getitem__(self, index):        return getattr(self, self.__slots__[index])    def __len__(self):        return len(self.__slots__)

And to use, just subclass and define __slots__:

class Student(MutableTuple):    __slots__ = 'first', 'last', 'grade' # customize >>> student = Student('Lisa', 'Simpson', 'A')>>> studentStudent('Lisa', 'Simpson', 'A')>>> first, last, grade = student>>> first'Lisa'>>> last'Simpson'>>> grade'A'>>> student[0]'Lisa'>>> student[2]'A'>>> len(student)3>>> 'Lisa' in studentTrue>>> 'Bart' in studentFalse>>> student.first = 'Bart'>>> for i in student: print(i)... BartSimpsonA