# `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)

  Return a reader object that will process lines from the given csvfile. A csvfile must be an iterable of strings, each in the reader's defined csv format. A csvfile is most commonly a file-like object or list. If csvfile is a file object, it should be opened with `newline=''`. [1] An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the `Dialect` class or one of the strings returned by the `list_dialects()` function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about the dialect and formatting parameters, see 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)

  Return a writer object responsible for converting the user's data into delimited strings on the given file-like object. csvfile can be any object with a `write()` method. If csvfile is a file object, it should be opened with `newline=''` [1]. An optional dialect parameter can be given which is used to define a set of parameters specific to a particular CSV dialect. It may be an instance of a subclass of the `Dialect` class or one of the strings returned by the `list_dialects()` function. The other optional fmtparams keyword arguments can be given to override individual formatting parameters in the current dialect. For full details about dialects and formatting parameters, see the Dialectes et paramètres de formatage section. To make it as easy as possible to interface with modules which implement the DB API, the value `None` is written as the empty string. While this isn't a reversible transformation, it makes it easier to dump SQL NULL data values to CSV files without preprocessing the data returned from a `cursor.fetch*` call. All other non-string data are stringified with `str()` before being written.

  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)

  Create an object which operates like a regular writer but maps dictionaries onto output rows. The fieldnames parameter is a `sequence` of keys that identify the order in which values in the dictionary passed to the `writerow()` method are written to file f. The optional restval parameter specifies the value to be written if the dictionary is missing a key in fieldnames. If the dictionary passed to the `writerow()` method contains a key not found in fieldnames, the optional extrasaction parameter indicates what action to take. If it is set to `'raise'`, the default value, a `ValueError` is raised. If it is set to `'ignore'`, extra values in the dictionary are ignored. Any other optional or keyword arguments are passed to the underlying `writer` instance.

  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.

  Instructs the reader to convert all non-quoted fields to type 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é.

  Instructs `reader` to perform no special processing of quote characters.

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

To make it easier to specify the format of input and output records, specific formatting parameters are grouped together into dialects. A dialect is a subclass of the `Dialect` class containing various attributes describing the format of the CSV file. When creating `reader` or `writer` objects, the programmer can specify a string or a subclass of the `Dialect` class as the dialect parameter. In addition to, or instead of, the dialect parameter, the programmer can also specify individual formatting parameters, which have the same names as the attributes defined below for the `Dialect` class.

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.

  Modifié dans la version 3.11: Un `escapechar` vide n'est pas autorisé.

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.

  Modifié dans la version 3.11: Un `quotechar` vide n'est pas autorisé.

Dialect.quoting

  Controls when quotes should be generated by the writer and recognised by the reader. It can take on any of the QUOTE_* constants and defaults to `QUOTE_MINIMAL`.

Dialect.skipinitialspace

  Quand il vaut `True`, les espaces suivant directement delimiter sont ignorés. Il vaut `False` par défaut.

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

`writer` objects (`DictWriter` instances and objects returned by the `writer()` function) have the following public methods. A row must be an iterable of strings or numbers for `writer` objects and a dictionary mapping fieldnames to strings or numbers (by passing them through `str()` first) for `DictWriter` objects. Note that complex numbers are written out surrounded by parens. This may cause some problems for other programs which read CSV files (assuming they support complex numbers at all).

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.getencoding()`). 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).