csv — Lecture et écriture de fichiers CSV

Code source : Lib/csv.py

Le format CSV (Comma Separated Values, valeurs séparées par des virgules) est le format le plus commun dans l'importation et l'exportation de feuilles de calculs et de bases de données. Le format fut utilisé pendant des années avant qu'aient lieu des tentatives de standardisation avec la RFC 4180. L'absence de format bien défini signifie que des différences subtiles existent dans la production et la consommation de données par différentes applications. Ces différences peuvent gêner lors du traitement de fichiers CSV depuis des sources multiples. Cependant, bien que les séparateurs et délimiteurs varient, le format global est suffisamment similaire pour qu'un module unique puisse manipuler efficacement ces données, masquant au programmeur les détails de lecture/écriture des données.

Le module csv implémente des classes pour lire et écrire des données tabulaires au format CSV. Il vous permet de dire « écris ces données dans le format préféré par Excel » ou « lis les données de ce fichier généré par Excel », sans connaître les détails précis du format CSV utilisé par Excel. Vous pouvez aussi décrire les formats CSV utilisés par d'autres applications ou définir vos propres spécialisations.

Les objets reader et writer du module csv lisent et écrivent des séquences. Vous pouvez aussi lire/écrire les données dans un dictionnaire en utilisant les classes DictReader et DictWriter.

Voir aussi

PEP 305 ­— Interface des fichiers CSV

La proposition d'amélioration de Python (PEP) qui a proposé cet ajout au langage.

Contenu du module

Le module csv définit les fonctions suivantes :

csv.reader(csvfile, dialect='excel', **fmtparams)

Renvoie un objet lecteur, qui itérera sur les lignes de l'objet csvfile donné. csvfile peut être n'importe quel objet supportant le protocole itérateur et renvoyant une chaîne de caractères chaque fois que sa méthode __next__() est appelée — les fichiers objets et les listes sont tous deux valables. Si csvfile est un fichier, il doit être ouvert avec newline=''. 1 Un paramètre dialect optionnel peut être fourni pour définir un ensemble de paramètres spécifiques à un dialecte CSV particulier. Il peut s'agir d'une instance de sous-classe de Dialect ou de l'une des chaînes renvoyées par la fonction list_dialects(). Les autres arguments nommés optionnels (fmtparams) peuvent être spécifiés pour redéfinir des paramètres de formatage particuliers dans le dialecte utilisé. Pour des détails complets sur les dialectes et paramètres de formatage, voir la section Dialectes et paramètres de formatage.

Chaque ligne lue depuis le fichier CSV est renvoyée comme une liste de chaînes de caractères. Aucune conversion automatique de type des données n'est effectuée à moins que l'option de formatage QUOTE_NONNUMERIC soit spécifiée (dans ce cas, les champs sans guillemets sont transformés en nombres flottants).

Un court exemple d'utilisation :

>>> import csv
>>> with open('eggs.csv', newline='') as csvfile:
...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
...     for row in spamreader:
...         print(', '.join(row))
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam
csv.writer(csvfile, dialect='excel', **fmtparams)

Renvoie un transcripteur (objet writer) responsable de convertir les données de l'utilisateur en chaînes délimitées sur l'objet fichier-compatible donné. csvfile peut être n'importe quel objet avec une méthode write(). Si csvfile est un objet fichier, il doit être ouvert avec newline=''. 1 Un paramètre dialect optionnel peut être fourni pour définir un ensemble de paramètres spécifiques à un dialecte CSV particulier. Il peut s'agir d'une instance d’une sous-classe de Dialect ou de l'une des chaînes renvoyées par la fonction list_dialects(). Les autres arguments nommés optionnels (fmtparams) peuvent être spécifiés pour redéfinir des paramètres de formatage particuliers dans le dialecte utilisé. Pour tous les détails sur les dialectes et paramètres de formatage, voir la section Dialectes et paramètres de formatage. Pour faciliter au mieux l'interfaçage avec d'autres modules implémentant l'interface DB, la valeur None est convertie en une chaîne vide. Bien que ce ne soit pas une transformation réversible, cela simplifie l'exportation de données SQL NULL vers des fichiers CSV sans pré-traiter les données renvoyées par un appel à cursor.fetch*. Toutes les autres données qui ne sont pas des chaînes de caractères sont transformées en chaînes par un appel à str() avant d'être écrites.

Un court exemple d'utilisation :

import csv
with open('eggs.csv', 'w', newline='') as csvfile:
    spamwriter = csv.writer(csvfile, delimiter=' ',
                            quotechar='|', quoting=csv.QUOTE_MINIMAL)
    spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
    spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
csv.register_dialect(name[, dialect[, **fmtparams]])

Associe dialect avec name. name doit être une chaîne de caractères. Le dialecte peut être spécifié en passant une instance d'une sous-classe de Dialect, des arguments nommés fmtparams, ou les deux, avec les arguments nommés redéfinissant les paramètres du dialecte. Pour tous les détails sur les dialectes et paramètres de formatage, voir la section Dialectes et paramètres de formatage.

csv.unregister_dialect(name)

Supprime le dialecte associé à name depuis le registre des dialectes. Une Error est levée si name n'est pas un nom de dialecte enregistré.

csv.get_dialect(name)

Renvoie le dialecte associé à name. Une Error est levée si name n'est pas un nom de dialecte enregistré. Cette fonction renvoie un objet Dialect immuable.

csv.list_dialects()

Renvoie les noms de tous les dialectes enregistrés.

csv.field_size_limit([new_limit])

Renvoie la taille de champ maximale actuelle autorisée par l'analyseur. Si new_limit est donnée, elle devient la nouvelle limite.

Le module csv définit les classes suivantes :

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)

Crée un objet qui opère comme un lecteur ordinaire mais assemble les informations de chaque ligne dans un dict dont les clés sont données par le paramètre optionnel fieldnames.

Le paramètre fieldnames est une séquence. Si fieldnames est omis, les valeurs de la première ligne du fichier f sont utilisées comme noms de champs. Sans se soucier de comment sont déterminés les noms de champs, le dictionnaire préserve leur ordre original.

Si une ligne a plus de champs que fieldnames, les données excédentaires sont mises dans une liste stockée dans le champ spécifié par restkey (None par défaut). Si une ligne non-vide a moins de champs que fieldnames, les valeurs manquantes sont remplacées par la valeur de restval (None par défaut).

Tous les autres arguments optionnels ou nommés sont passés à l'instance reader sous-jacente.

Modifié dans la version 3.6: Les lignes renvoyées sont maintenant de type OrderedDict.

Modifié dans la version 3.8: Les lignes renvoyées sont maintenant de type dict.

Un court exemple d'utilisation :

>>> import csv
>>> with open('names.csv', newline='') as csvfile:
...     reader = csv.DictReader(csvfile)
...     for row in reader:
...         print(row['first_name'], row['last_name'])
...
Eric Idle
John Cleese

>>> print(row)
{'first_name': 'John', 'last_name': 'Cleese'}
class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

Crée un objet qui opère comme un transcripteur ordinaire mais qui produit les lignes de sortie depuis des dictionnaires. Le paramètre fieldnames est une séquence de clés qui indique l'ordre dans lequel les valeurs du dictionnaire passé à la méthode writerow() doivent être écrites vers le fichier f. Le paramètre optionnel restval spécifie la valeur à écrire si une clé de fieldnames manque dans le dictionnaire. Si le dictionnaire passé à writerow() possède une clé non présente dans fieldnames, le paramètre optionnel extrasaction indique quelle action réaliser. S'il vaut 'raise', sa valeur par défaut, une ValueError est levée. S'il vaut 'ignore', les valeurs excédentaires du dictionnaire sont ignorées. Les autres arguments optionnels ou nommés sont passés à l'instance writer sous-jacente.

Notez que contrairement à la classe DictReader, le paramètre fieldnames de DictWriter n'est pas optionnel.

Un court exemple d'utilisation :

import csv

with open('names.csv', 'w', newline='') as csvfile:
    fieldnames = ['first_name', 'last_name']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

    writer.writeheader()
    writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
    writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
    writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})
class csv.Dialect

La classe Dialect est une classe dont les attributs contiennent des informations sur la façon de gérer les guillemets, les espaces, les délimiteurs, etc. En raison de l’absence d’une spécification CSV stricte, différentes applications produisent des données CSV subtilement différentes. Les instances Dialect définissent le comportement des instances reader et writer.

Tous les noms disponibles de Dialect sont renvoyés par list_dialects(), et ils peuvent être enregistrés avec des classes reader et writer spécifiques en passant par leur fonction d’initialisation (__init__) comme ici :

import csv

with open('students.csv', 'w', newline='') as csvfile:
    writer = csv.writer(csvfile, dialect='unix')
                                 ^^^^^^^^^^^^^^
class csv.excel

La classe excel définit les propriétés usuelles d'un fichier CSV généré par Excel. Elle est enregistrée avec le nom de dialecte 'excel'.

class csv.excel_tab

La classe excel_tab définit les propriétés usuelles d'un fichier CSV généré par Excel avec des tabulations comme séparateurs. Elle est enregistrée avec le nom de dialecte 'excel-tab'.

class csv.unix_dialect

La classe unix_dialect définit les propriétés usuelles d'un fichier CSV généré sur un système Unix, c'est-à-dire utilisant '\n' comme marqueur de fin de ligne et délimitant tous les champs par des guillemets. Elle est enregistrée avec le nom de dialecte 'unix'.

Nouveau dans la version 3.2.

class csv.Sniffer

La classe Sniffer est utilisée pour déduire le format d'un fichier CSV.

La classe Sniffer fournit deux méthodes :

sniff(sample, delimiters=None)

Analyse l'extrait donné (sample) et renvoie une sous-classe Dialect reflétant les paramètres trouvés. Si le paramètre optionnel delimiters est donné, il est interprété comme une chaîne contenant tous les caractères valides de séparation possibles.

has_header(sample)

Analyse l'extrait de texte (présumé être au format CSV) et renvoie True si la première ligne semble être une série d'en-têtes de colonnes. En inspectant chaque colonne, l’un des deux critères clés sera pris en compte pour estimer si l’échantillon contient un en-tête :

  • les deuxième à n-ième lignes contiennent des valeurs numériques

  • les deuxième à n-ième lignes contiennent des chaînes dont la longueur d’au moins une valeur diffère de celle de l’en-tête putatif de cette colonne.

L'échantillon est composé des vingt lignes après la première ligne ; si plus de la moitié des colonnes + lignes répondent aux critères, True est renvoyé.

Note

Cette méthode est une heuristique discutable et peut produire tant des faux-positifs que des faux-négatifs.

Un exemple d'utilisation de Sniffer :

with open('example.csv', newline='') as csvfile:
    dialect = csv.Sniffer().sniff(csvfile.read(1024))
    csvfile.seek(0)
    reader = csv.reader(csvfile, dialect)
    # ... process CSV file contents here ...

Le module csv définit les constantes suivantes :

csv.QUOTE_ALL

Indique aux objets writer de délimiter tous les champs par des guillemets.

csv.QUOTE_MINIMAL

Indique aux objets writer de ne délimiter ainsi que les champs contenant un caractère spécial comme delimiter, quotechar ou n'importe quel caractère de lineterminator.

csv.QUOTE_NONNUMERIC

Indique aux objets writer de délimiter ainsi tous les champs non-numériques.

Indique au lecteur de convertir tous les champs non délimités par des guillemets vers des float.

csv.QUOTE_NONE

Indique aux objets writer de ne jamais délimiter les champs par des guillemets. Quand le delimiter utilisé apparaît dans les données, il est précédé sur la sortie par un caractère escapechar. Si escapechar n'est pas précisé, le transcripteur lèvera une Error si un caractère nécessitant un échappement est rencontré.

Indique au reader de ne pas opérer de traitement spécial sur les guillemets.

Le module csv définit les exceptions suivantes :

exception csv.Error

Levée par les fonctions du module quand une erreur détectée.

Dialectes et paramètres de formatage

Pour faciliter la spécification du format des entrées et sorties, les paramètres de formatage spécifiques sont regroupés en dialectes. Un dialecte est une sous-classe de Dialect avec un ensemble de méthodes spécifiques et une méthode validate(). Quand un objet reader ou writer est créé, vous pouvez spécifier une chaîne ou une sous-classe de Dialect comme paramètre dialect. En plus du paramètre dialect, ou à sa place, vous pouvez aussi préciser des paramètres de formatage individuels, qui ont les mêmes noms que les attributs de Dialect définis ci-dessous.

Les dialectes supportent les attributs suivants :

Dialect.delimiter

Une chaîne d'un seul caractère utilisée pour séparer les champs. Elle vaut ',' par défaut.

Dialect.doublequote

Contrôle comment les caractères quotechar dans le champ doivent être retranscrits. Quand ce paramètre vaut True, le caractère est doublé. Quand il vaut False, le caractère escapechar est utilisé comme préfixe à quotechar. Il vaut True par défaut.

En écriture, si doublequote vaut False et qu'aucun escapechar n'est précisé, une Error est levée si un quotechar est trouvé dans le champ.

Dialect.escapechar

Une chaîne d'un seul caractère utilisée par le transcripteur pour échapper delimiter si quoting vaut QUOTE_NONE, et pour échapper quotechar si doublequote vaut False. À la lecture, escapechar retire toute signification spéciale au caractère qui le suit. Elle vaut par défaut None, ce qui désactive l'échappement.

Dialect.lineterminator

La chaîne utilisée pour terminer les lignes produites par un writer. Elle vaut par défaut '\r\n'.

Note

La classe reader est codée en dur pour reconnaître '\r' et '\n' comme marqueurs de fin de ligne, et ignorer lineterminator. Ce comportement pourrait changer dans le futur.

Dialect.quotechar

Une chaîne d'un seul caractère utilisée pour délimiter les champs contenant des caractères spéciaux, comme delimiter ou quotechar, ou contenant un caractère de fin de ligne. Elle vaut '"' par défaut.

Dialect.quoting

Contrôle quand les guillemets doivent être générés par le transcripteur et reconnus par le lecteur. Il peut prendre comme valeur l'une des constantes QUOTE_* (voir la section Contenu du module) et vaut par défaut QUOTE_MINIMAL.

Dialect.skipinitialspace

When True, spaces immediately following the delimiter are ignored. The default is False.

Dialect.strict

Quand il vaut True, une exception Error est levée lors de mauvaises entrées CSV. Il vaut False par défaut.

Objets lecteurs

Les objets lecteurs (instances de DictReader ou objets renvoyés par la fonction reader()) ont les méthodes publiques suivantes :

csvreader.__next__()

Renvoie la ligne suivante de l'objet itérable du lecteur en tant que liste (si l'objet est renvoyé depuis reader()) ou dictionnaire (si l'objet est un DictReader), analysé suivant la classe Dialect utilisée. Généralement, vous devez appeler la méthode à l'aide de next(reader).

Les objets lecteurs ont les attributs publics suivants :

csvreader.dialect

Une description en lecture seule du dialecte utilisé par l'analyseur.

csvreader.line_num

Le nombre de lignes lues depuis l'itérateur source. Ce n'est pas équivalent au nombre d'enregistrements renvoyés, puisque certains enregistrements peuvent s'étendre sur plusieurs lignes.

Les objets DictReader ont les attributs publics suivants :

DictReader.fieldnames

S'il n'est pas passé comme paramètre à la création de l'objet, cet attribut est initialisé lors du premier accès ou quand le premier enregistrement est lu depuis le fichier.

Objets transcripteurs

Les objets Writer (instances de DictWriter ou objets renvoyés par la fonction writer()) ont les méthodes publiques suivantes. Une row doit être un itérable de chaînes de caractères ou de nombres pour les objets Writer, et un dictionnaire associant des noms de champs à des chaînes ou des nombres (en les faisant d'abord passer par str()) pour les objets DictWriter. Notez que les nombres complexes sont retranscrits entourés de parenthèses. Cela peut causer quelques problèmes pour d'autres programmes qui liraient ces fichiers CSV (en supposant qu'ils supportent les nombres complexes).

csvwriter.writerow(row)

Écrit le paramètre row vers l’objet fichier du transcripteur, formaté selon la classe Dialect utilisée. Renvoie la valeur de retour de l'appel à la méthode write de l'objet fichier sous-jacent.

Modifié dans la version 3.5: Ajout du support d'itérables arbitraires.

csvwriter.writerows(rows)

Écrit tous les éléments de rows (itérable d'objets row comme décrits précédemment) vers le fichier associé au transcripteur, formatés selon le dialecte utilisé.

Les objets transcripteurs ont l’attribut public suivant :

csvwriter.dialect

Une description en lecture seule du dialecte utilisé par le transcripteur.

Les objets DictWriter ont la méthode publique suivante :

DictWriter.writeheader()

Écrit une ligne avec le nom des en-têtes (comme définies dans le constructeur) dans l'objet fichier associé au transcripteur, formatée selon le dialecte utilisé. Renvoie la valeur de retour de l'appel csvwriter.writerow() utilisé en interne.

Nouveau dans la version 3.2.

Modifié dans la version 3.8: writeheader() renvoie maintenant aussi la valeur renvoyée par la méthode csvwriter.writerow() qu'il utilise en interne.

Exemples

Le plus simple exemple de lecture d'un fichier CSV :

import csv
with open('some.csv', newline='') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

Lire un fichier avec un format alternatif :

import csv
with open('passwd', newline='') as f:
    reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
    for row in reader:
        print(row)

Le plus simple exemple d'écriture correspondant est :

import csv
with open('some.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)

Puisque open() est utilisée pour ouvrir un fichier CSV en lecture, le fichier sera par défaut décodé vers Unicode en utilisant l'encodage par défaut (voir locale.getpreferredencoding()). Pour décoder un fichier utilisant un encodage différent, utilisez l'argument encoding de open :

import csv
with open('some.csv', newline='', encoding='utf-8') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

Cela s’applique également lors de l'écriture dans un autre encodage que celui par défaut du système : spécifiez l'encodage en argument lors de l'ouverture du fichier de sortie.

Enregistrer un nouveau dialecte :

import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', newline='') as f:
    reader = csv.reader(f, 'unixpwd')

Un exemple d'utilisation un peu plus avancé du lecteur --- attrapant et notifiant les erreurs :

import csv, sys
filename = 'some.csv'
with open(filename, newline='') as f:
    reader = csv.reader(f)
    try:
        for row in reader:
            print(row)
    except csv.Error as e:
        sys.exit('file {}, line {}: {}'.format(filename, reader.line_num, e))

Et bien que le module ne permette pas d'analyser directement des chaînes, cela peut être fait facilement :

import csv
for row in csv.reader(['one,two,three']):
    print(row)

Notes

1(1,2)

Si newline='' n'est pas précisé, les caractères de fin de ligne embarqués dans des champs délimités par des guillemets ne seront pas interprétés correctement, et sur les plateformes qui utilisent \r\n comme marqueur de fin de ligne, un \r sera ajouté. Il devrait toujours être sûr de préciser newline='', puisque le module csv gère lui-même les fins de lignes (universelles).