collections.namedtuple

Crée des tuples à champs nommés : vous lisez les données avec student.points au lieu de student[2], et l’objet reste immuable.

Renvoie
Une nouvelle classe qui hérite de tuple.
Sur cette page

Exemple

#
Python
from collections import namedtuple

Student = namedtuple("Student", ["name", "world", "points"])

lea = Student("Léa", 7, 250)
print(lea)
print(lea.name, lea.points)
print(lea[1], len(lea))

name, world, points = lea
print(f"{name} est dans le monde {world}")
Résultatrésultat enregistré, vous pouvez le vérifier
Student(name='Léa', world=7, points=250)
Léa 250
7 3
Léa est dans le monde 7

Définition et utilisation

#

La fonction namedtuple() du module collections crée une nouvelle classe de tuples dont chaque champ a un nom. Au lieu de vous rappeler que, dans le tuple ("Léa", 7, 250), les points sont à l’indice 2, vous écrivez student.points. Les objets restent de simples tuples, l’indexation, le déballage, la comparaison et len() fonctionnent donc.

Comme tout tuple, l’objet est immuable : l’assignation à un champ lève AttributeError. Une nouvelle version avec un champ modifié est créée par la méthode _replace(), et _asdict() transforme l’objet en dictionnaire. L’attribut _fields contient les noms des champs, et _make() crée un objet à partir de n’importe quelle séquence, par exemple une ligne d’un fichier CSV. Le tiret bas dans ces noms ne signifie pas qu’ils sont privés, il évite seulement les conflits avec les noms de vos champs.

Une notation plus moderne est une classe héritant de typing.NamedTuple, où les champs sont déclarés avec des annotations de types, comme dans @dataclass. Lorsque vous avez besoin d’un objet dont les champs peuvent changer, choisissez @dataclass.

Syntaxe

#
Syntaxe
from collections import namedtuple

Nom = namedtuple("Nom", ["champ1", "champ2"], defaults=None)
objet = Nom(valeur1, valeur2)
objet.champ1
objet._replace(champ1=nouvelle_valeur)
objet._asdict()

Paramètres

#
  • typename

    str

    Le nom de la nouvelle classe, visible notamment dans repr(). En général le même que le nom de la variable.
  • field_names

    liste de chaînes ou chaîne

    Les noms des champs, par exemple ["x", "y"] ou "x y".
  • defaults

    séquence, facultative

    Les valeurs par défaut des derniers champs.

Plus d’exemples

#
Immuabilité, _replace() et _asdict()
Python
from collections import namedtuple

Student = namedtuple("Student", "name points level", defaults=[1])

jean = Student("Jean", 80)
print(jean)

try:
    jean.points = 120
except AttributeError:
    print("Le champ ne peut pas être modifié")

promoted = jean._replace(points=120, level=2)
print(promoted)
print(promoted._asdict())
print(Student._fields)
Résultatrésultat enregistré, vous pouvez le vérifier
Student(name='Jean', points=80, level=1)
Le champ ne peut pas être modifié
Student(name='Jean', points=120, level=2)
{'name': 'Jean', 'points': 120, 'level': 2}
('name', 'points', 'level')
typing.NamedTuple avec annotations de types
Python
from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float = 0.0

    def distance(self):
        return (self.x ** 2 + self.y ** 2) ** 0.5

p = Point(3, 4)
print(p, p.distance())
print(Point(1.5))
print(sorted([Point(2, 1), Point(1, 5), Point(1, 2)]))
Résultatrésultat enregistré, vous pouvez le vérifier
Point(x=3, y=4) 5.0
Point(x=1.5, y=0.0)
[Point(x=1, y=2), Point(x=1, y=5), Point(x=2, y=1)]

Les annotations ne convertissent pas les types : Point(3, 4) stocke des entiers. Le tri compare les champs un par un, comme pour les tuples ordinaires.

_make() et lignes d’un fichier CSV
Python
import csv
from collections import namedtuple

lines = ["name,world,points", "Léa,7,250", "Jean,2,80"]
reader = csv.reader(lines)
Row = namedtuple("Row", next(reader))

for row in map(Row._make, reader):
    print(row.name, int(row.points))
Résultatrésultat enregistré, vous pouvez le vérifier
Léa 250
Jean 80

Bonnes pratiques

#
  • Les méthodes _replace(), _asdict() et _make() sont publiques malgré le tiret bas. Il protège d’un conflit avec les noms de vos champs.
  • Un namedtuple convient bien pour renvoyer plusieurs valeurs depuis une fonction : vous déballez le résultat comme un tuple ou le lisez par les noms de champs.
  • Si les champs doivent changer, ou si la classe a besoin de nombreuses méthodes, utilisez @dataclass.

Entrées associées

#

Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.