Search code examples
pythontypestuplesterminologynamedtuple

What are "named tuples" in Python?


  • What are named tuples and how do I use them?
  • When should I use named tuples instead of normal tuples, or vice versa?
  • Are there "named lists" too? (i.e. mutable named tuples)

For the last question specifically, see also Existence of mutable named tuple in Python?.


Solution

  • 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 sqrt
    line_length = sqrt((pt1[0]-pt2[0])**2 + (pt1[1]-pt2[1])**2)
    

    Using a named tuple it becomes more readable:

    from collections import namedtuple
    Point = namedtuple('Point', 'x y')
    pt1 = Point(1.0, 5.0)
    pt2 = Point(2.5, 1.5)
    
    from math import sqrt
    line_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 referencing
    line_length = sqrt((pt1[0]-pt2[0])**2 + (pt1[1]-pt2[1])**2)
     # use tuple unpacking
    x1, 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.0
    AttributeError: 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.