Compact structured records
Representing a small fixed-shape record returned by a function or parsed from input.
Python · Class
namedtuple
namedtuple() builds tuple subclasses with readable named fields. The resulting records remain indexable and iterable like tuples while also supporting attribute access.
How it works
namedtuple() creates a tuple subclass whose instances retain tuple behavior while exposing declared fields as attributes. Field names may be supplied as a sequence or as a whitespace- or comma-separated string; optional defaults fill trailing fields when values are omitted.
Syntax
collections.namedtuple(typename, field_names, *, rename=False, defaults=None, module=None)Parameters
| Name | Type | Description |
|---|---|---|
typename | str | Name for the generated tuple subclass. |
field_names | sequence[str] | str | Field names as a string sequence or whitespace- and/or comma-separated string. |
rename | bool | If true, replace invalid or duplicate names with valid generated names. |
defaults | iterable | Defaults for omitted rightmost fields. |
module | str | Value assigned to the generated type's __module__ attribute. |
Returns
A new tuple subclass named typename, with the declared fields available by attribute lookup as well as indexing and iteration.
Key points
- Use named tuples when a fixed tuple record needs clearer field semantics without abandoning tuple compatibility.
- A named-tuple instance supports both ordinary tuple operations and attribute-based field lookup.
- The factory creates a reusable class; call that class to construct individual records.
- Declare fields with a string sequence such as ['x', 'y'], or use the documented compact string form.
- Generated instances include descriptive documentation, which helps interactive use and inspection.
- The generated representation labels values with field names, making logs and debugging easier to read.
Common mistakes
- Field names cannot begin with an underscore, even when the name would otherwise be a valid identifier.
Example: Named tuple with a default field
from collections import namedtuple
Point = namedtuple("Point", "x y", defaults=[0])
point = Point(3)
assert point.x == 3
assert point.y == 0
assert point[0] == 3
assert point._fields == ("x", "y")
print(point)Creates a tuple-compatible Point type with named fields and a default for y, then accesses the result by attribute and index.
When to use it
Tuple-compatible APIs
Passing records through code that expects tuples while making individual fields readable.
Self-documenting diagnostics
Providing readable values in logs, debugging sessions, and interactive inspection.
Interview questions
QWhat does namedtuple() return, and what capabilities do its instances have?
It returns a new tuple subclass named by typename. Instances can be indexed and iterated like tuples, while also supporting attribute access for their declared fields.
Follow-up: Why might namedtuple be preferable to a dictionary for a fixed record? It preserves compact tuple behavior and positional compatibility while making field access self-documenting.
QWhat forms can field_names take, and what restrictions apply?
field_names can be a sequence of strings or one string whose names are separated by whitespace and/or commas. Each name must be a valid Python identifier and cannot start with an underscore.
Follow-up: How can malformed names be handled? Set rename=True to replace invalid or duplicate names automatically, then check the generated field names.
QHow do defaults and module affect the generated named-tuple type?
defaults supplies default values for omitted trailing fields, and module can set the generated type's __module__ attribute. The signature makes both options keyword-only after field_names.
Follow-up: Which fields receive defaults? The defaults correspond to the rightmost fields, so omitted values must form a suffix of the field list.
Related
tuplecollections.OrderedDictcollections.defaultdictcollections.deque