csv — CSV File Reading and Writing

Source code: Lib/csv.py

---

Das sogenannte CSV-Format (Comma Separated Values) ist das gängigste Import- und Exportformat für Tabellenkalkulationen und Datenbanken. Das CSV-Format wurde bereits viele Jahre lang verwendet, bevor versucht wurde, das Format in „ RFC 4180 “ standardisiert zu beschreiben. Das Fehlen eines klar definierten Standards führt dazu, dass oft subtile Unterschiede in den Daten bestehen, die von verschiedenen Anwendungen erzeugt und verarbeitet werden. Diese Unterschiede können die Verarbeitung von CSV-Dateien aus verschiedenen Quellen erschweren. Dennoch ist das Format insgesamt so ähnlich, dass es möglich ist, ein einziges Modul zu schreiben, das solche Daten effizient bearbeiten kann, wobei die Details des Ein- und Auslesens der Daten vor dem Programmierer verborgen bleiben – auch wenn die Trennzeichen und Anführungszeichen variieren.

The csv module implements classes to read and write tabular data in CSV format. It allows programmers to say, „write this data in the format preferred by Excel,“ or „read data from this file which was generated by Excel,“ without knowing the precise details of the CSV format used by Excel. Programmers can also describe the CSV formats understood by other applications or define their own special-purpose CSV formats.

The csv module’s reader and writer objects read and write sequences. Programmers can also read and write data in dictionary form using the DictReader and DictWriter classes.

Siehe auch

PEP 305 - CSV File API

The Python Enhancement Proposal which proposed this addition to Python.

Module Contents

The csv module defines the following functions:

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

Gibt ein Leserobjekt zurück, das Zeilen aus der angegebenen csvfile verarbeitet. Eine csvfile muss eine iterierbare Sammlung von Zeichenketten sein, die jeweils dem vom Leser definierten CSV-Format entsprechen. Eine csvfile ist in der Regel ein dateiähnliches Objekt oder eine Liste. Wenn csvfile ein Dateiobjekt ist, sollte es mit ` newline=''` geöffnet werden. ` [1] ` Ein optionaler dialect-Parameter kann angegeben werden, der dazu dient, eine Reihe von Parametern zu definieren, die für einen bestimmten CSV-Dialekt spezifisch sind. Er kann eine Instanz einer Unterklasse der Klasse ` Dialect ` oder einer der Zeichenketten sein, die von der Funktion ` list_dialects() ` zurückgegeben werden. Die anderen optionalen Schlüsselwortargumente fmtparams können angegeben werden, um einzelne Formatierungsparameter im aktuellen Dialekt zu überschreiben. Ausführliche Informationen zu den Dialekt- und Formatierungsparametern findest du im Abschnitt Dialects and Formatting Parameters.

Each row read from the csv file is returned as a list of strings. No automatic data type conversion is performed unless the QUOTE_NONNUMERIC format option is specified (in which case unquoted fields are transformed into floats).

A short usage example:

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

Gibt ein Writer-Objekt zurück, das dafür zuständig ist, die Daten des Benutzers in durch Trennzeichen getrennte Zeichenfolgen auf dem angegebenen dateiähnlichen Objekt zu konvertieren. csvfile kann ein beliebiges Objekt sein, das über eine Methode „ write() “ verfügt. Wenn csvfile ein Dateiobjekt ist, sollte es mit ` newline='' ` oder ` [1]_` geöffnet werden. Ein optionaler Parameter dialect kann angegeben werden, der dazu dient, eine Reihe von Parametern zu definieren, die für einen bestimmten CSV-Dialekt spezifisch sind. Er kann eine Instanz einer Unterklasse der Klasse ` Dialect ` oder eine der von der Funktion ` list_dialects() ` zurückgegebenen Zeichenketten sein. Die anderen optionalen Schlüsselwortargumente fmtparams können angegeben werden, um einzelne Formatierungsparameter im aktuellen Dialekt zu überschreiben. Ausführliche Informationen zu Dialekten und Formatierungsparametern findest du im Abschnitt „ Dialects and Formatting Parameters “. Um die Anbindung an Module, die die DB-API implementieren, so einfach wie möglich zu gestalten, wird der Wert „ None “ als leere Zeichenkette geschrieben. Dies ist zwar keine reversible Umwandlung, erleichtert jedoch das Ausgeben von SQL-NULL-Datenwerten in CSV-Dateien, ohne dass die von einem ` cursor.fetch* -Aufruf zurückgegebenen Daten vorverarbeitet werden müssen. Alle anderen Nicht-Zeichenfolgen-Daten werden vor dem Schreiben mit ` :func:`str ` in Zeichenfolgen umgewandelt.

A short usage example:

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]])

Ordne dialect dem name zu. name muss eine Zeichenkette sein. Der Dialekt kann entweder durch die Übergabe einer Unterklasse von Dialect oder durch fmtparams-Schlüsselwortargumente oder beides angegeben werden, wobei Schlüsselwortargumente die Parameter des Dialekts überschreiben. Ausführliche Informationen zu Dialekten und Formatierungsparametern findest du im Abschnitt Dialects and Formatting Parameters.

csv.unregister_dialect(name)

Löscht den mit name verknüpften Dialekt aus dem Dialektregister. Es wird eine Ausnahme vom Typ Error ausgelöst, wenn name kein registrierter Dialektname ist.

csv.get_dialect(name)

Gibt den mit name verknüpften Dialekt zurück. Es wird ein Fehler vom Typ Error ausgelöst, wenn name kein registrierter Dialektname ist. Diese Funktion gibt ein unveränderliches Dialect zurück.

csv.list_dialects()

Return the names of all registered dialects.

csv.field_size_limit([new_limit])

Returns the current maximum field size allowed by the parser. If new_limit is given, this becomes the new limit.

The csv module defines the following classes:

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

Erstelle ein Objekt, das wie ein gewöhnlicher Reader funktioniert, jedoch die Informationen in jeder Zeile einem „ dict “ zuordnet, dessen Schlüssel durch den optionalen Parameter fieldnames vorgegeben werden.

Der Parameter fieldnames ist eine Sequenz. Wird fieldnames weggelassen, werden die Werte in der ersten Zeile der Datei f als Feldnamen verwendet und nicht in die Ergebnisse aufgenommen. Wird fieldnames angegeben, werden diese verwendet und die erste Zeile erscheint mit in den Ergebnissen. Unabhängig davon, wie die Feldnamen bestimmt werden, bewahrt das Dictionary deren ursprüngliche Reihenfolge.

Wenn eine Zeile mehr Felder enthält als Feldnamen vorhanden sind, werden die übrigen Daten in eine Liste aufgenommen und unter dem durch restkey angegebenen Feldnamen gespeichert (Standardwert ist None). Wenn eine nicht leere Zeile weniger Felder enthält als Feldnamen vorhanden sind, werden die fehlenden Werte mit dem Wert von restval aufgefüllt (Standardwert ist None).

Alle anderen optionalen Argumente oder Schlüsselwortargumente werden an die zugrunde liegende Instanz von reader übergeben.

Wenn das an fieldnames übergebene Argument ein Iterator ist, wird es in eine list umgewandelt.

Geändert in Version 3.6: Die zurückgegebenen Zeilen haben nun den Typ OrderedDict.

Geändert in Version 3.8: Die zurückgegebenen Zeilen haben nun den Typ dict.

A short usage example:

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

Erstellen Sie ein Objekt, das wie ein gewöhnlicher Writer funktioniert, aber Dictionarys auf Ausgabezeilen abbildet. Der Parameter fieldnames ist eine Sequenz aus Schlüsseln, die die Reihenfolge festlegen, in der die Werte des an die Methode writerow() übergebenen Dictionarys in die Datei f geschrieben werden. Der optionale Parameter restval gibt den Wert an, der geschrieben werden soll, wenn im Dictionary ein Schlüssel fehlt, der in fieldnames enthalten ist. Wenn das an die Methode ` writerow() ` übergebene Dictionary einen Schlüssel enthält, der nicht in *fieldnames* zu finden ist, gibt der optionale Parameter *extrasaction* an, welche Aktion durchgeführt werden soll. Ist er auf den Standardwert ` 'raise'` gesetzt, wird eine ` ValueError ` ausgelöst. Ist er auf ` 'ignore'` gesetzt, werden zusätzliche Werte im Dictionary ignoriert. Alle anderen optionalen oder Schlüsselwortargumente werden an die zugrunde liegende Instanz von ` writer ` übergeben.

Beachte, dass der Parameter fieldnames der Klasse „ DictWriter “ – anders als bei der Klasse „ DictReader “ – nicht optional ist.

Wenn das an fieldnames übergebene Argument ein Iterator ist, wird es in eine list umgewandelt.

A short usage example:

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

Die Klasse Dialect ist eine Containerklasse, deren Attribute Informationen darüber enthalten, wie mit doppelten Anführungszeichen, Leerzeichen, Trennzeichen usw. umgegangen werden soll. Da es keine strenge CSV-Spezifikation gibt, erzeugen verschiedene Anwendungen CSV-Daten, die sich geringfügig voneinander unterscheiden. Instanzen von Dialect legen fest, wie sich Instanzen von reader und writer verhalten.

Alle verfügbaren Dialect-Namen werden von list_dialects() zurückgegeben und können über deren Initialisierungsfunktionen (__init__) wie folgt in bestimmten reader und writer-Klassen registriert werden:

import csv

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

class csv.excel

Die Klasse excel definiert die üblichen Eigenschaften einer von Excel erstellten CSV-Datei. Sie ist unter dem Dialektnamen 'excel' registriert.

class csv.excel_tab

Die Klasse excel_tab definiert die üblichen Eigenschaften einer von Excel erstellten, durch Tabulatoren getrennten Datei. Sie ist unter dem Dialektnamen 'excel-tab' registriert.

class csv.unix_dialect

Die Klasse unix_dialect definiert die üblichen Eigenschaften einer auf UNIX-Systemen erzeugten CSV-Datei, d. h. mit '\n' als Zeilenabschlusszeichen und Anführungszeichen um alle Felder. Sie ist unter dem Dialektnamen 'unix' registriert.

Added in version 3.2.

class csv.Sniffer

Die Klasse Sniffer dient dazu, das Format einer CSV-Datei zu ermitteln.

Die Klasse Sniffer stellt zwei Methoden bereit:

sniff(sample, delimiters=None)

Analysiere das angegebene Beispiel und gib eine Unterklasse von Dialect zurück, die die gefundenen Parameter widerspiegelt. Wenn der optionale Parameter delimiters angegeben wird, wird er als Zeichenkette interpretiert, die mögliche gültige Trennzeichen enthält.

has_header(sample)

Analysiere den Beispieltext (vermutlich im CSV-Format) und geben Sie „ True “ zurück, wenn die erste Zeile offenbar aus einer Reihe von Spaltenüberschriften besteht. Bei der Überprüfung jeder Spalte werden zwei Schlüsselkriterien herangezogen, um zu beurteilen, ob die Spalte eine Überschrift enthält:

• the second through n-th rows contain numeric values

• the second through n-th rows contain strings where at least one value’s length differs from that of the putative header of that column.

Twenty rows after the first row are sampled; if more than half of columns + rows meet the criteria, True is returned.

Bemerkung

This method is a rough heuristic and may produce both false positives and negatives.

Ein Beispiel für die Verwendung von 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 ...

The csv module defines the following constants:

csv.QUOTE_ALL

Weist Objekte von writer an, alle Felder in Anführungszeichen zu setzen.

csv.QUOTE_MINIMAL

Instructs writer objects to only quote those fields which contain special characters such as delimiter, quotechar or any of the characters in lineterminator.

csv.QUOTE_NONNUMERIC

Weist Objekte von writer an, alle nicht-numerischen Felder in Anführungszeichen zu setzen.

Instructs reader objects to convert all non-quoted fields to type float.

csv.QUOTE_NONE

Instructs writer objects to never quote fields. When the current delimiter occurs in output data it is preceded by the current escapechar character. If escapechar is not set, the writer will raise Error if any characters that require escaping are encountered.

Weist Objekte von reader an, keine spezielle Verarbeitung von Anführungszeichen durchzuführen.

csv.QUOTE_NOTNULL

Weist die Objekte von writer an, alle Felder in Anführungszeichen zu setzen, die nicht None sind. Dies ähnelt QUOTE_ALL, mit dem Unterschied, dass bei einem Feldwert vom Typ None eine leere (nicht in Anführungszeichen gesetzte) Zeichenkette geschrieben wird.

Instructs reader objects to interpret an empty (unquoted) field as None and to otherwise behave as QUOTE_ALL.

Added in version 3.12.

csv.QUOTE_STRINGS

Weist Objekte von writer an, Felder, die Zeichenketten sind, stets in Anführungszeichen zu setzen. Dies entspricht in etwa der Einstellung QUOTE_NONNUMERIC, mit dem Unterschied, dass bei einem Feldwert von None eine leere (nicht in Anführungszeichen gesetzte) Zeichenkette geschrieben wird.

Weist Objekte von reader an, eine leere (nicht in Anführungszeichen gesetzte) Zeichenkette als None zu interpretieren und sich ansonsten wie unter QUOTE_NONNUMERIC beschrieben zu verhalten.

Added in version 3.12.

Bemerkung

Due to a bug, constants QUOTE_NOTNULL and QUOTE_STRINGS do not affect behaviour of reader objects. This bug is fixed in Python 3.13.

The csv module defines the following exception:

exception csv.Error

Raised by any of the functions when an error is detected.

Dialects and Formatting Parameters

Um die Angabe des Formats von Eingabe- und Ausgabesätzen zu vereinfachen, werden bestimmte Formatierungsparameter zu Dialekten zusammengefasst. Ein Dialekt ist eine Unterklasse der Klasse Dialect, die verschiedene Attribute enthält, welche das Format der CSV-Datei beschreiben. Beim Erstellen von Objekten vom Typ reader oder writer kann der Programmierer eine Zeichenkette oder eine Unterklasse der Klasse Dialect als Dialektparameter angeben. Zusätzlich zum oder anstelle des Parameters dialect kann der Programmierer auch einzelne Formatierungsparameter angeben, die dieselben Namen tragen wie die unten für die Klasse Dialect definierten Attribute.

Dialects support the following attributes:

Dialect.delimiter

A one-character string used to separate fields. It defaults to ','.

Dialect.doublequote

Legt fest, wie Instanzen von quotechar, die innerhalb eines Feldes vorkommen, selbst in Anführungszeichen gesetzt werden sollen. Bei der Einstellung True wird das Zeichen verdoppelt. Bei der Einstellung False wird das escapechar als Präfix vor dem quotechar verwendet. Die Standardeinstellung ist True.

Bei der Ausgabe wird, wenn doublequote auf False gesetzt ist und kein escapechar festgelegt wurde, ein Error ausgelöst, sobald ein quotechar in einem Feld gefunden wird.

Dialect.escapechar

A one-character string used by the writer to escape the delimiter if quoting is set to QUOTE_NONE and the quotechar if doublequote is False. On reading, the escapechar removes any special meaning from the following character. It defaults to None, which disables escaping.

Geändert in Version 3.11: An empty escapechar is not allowed.

Dialect.lineterminator

Die Zeichenkette, mit der die von der Funktion writer erzeugten Zeilen abgeschlossen werden. Standardmäßig ist dies '\r\n'`.

Bemerkung

Die Funktion reader ist fest so programmiert, dass sie entweder '\r' oder '\n' als Zeilenende erkennt und lineterminator ignoriert. Dieses Verhalten kann sich in Zukunft ändern.

Dialect.quotechar

A one-character string used to quote fields containing special characters, such as the delimiter or quotechar, or which contain new-line characters. It defaults to '"'.

Geändert in Version 3.11: An empty quotechar is not allowed.

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

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

Dialect.strict

Wenn True gesetzt ist, wird bei fehlerhaften CSV-Eingaben die Ausnahme Error ausgelöst. Die Standardeinstellung ist False.

Reader Objects

Reader-Objekte (DictReader -Instanzen und Objekte, die von der Funktion „ reader() “ zurückgegeben werden) haben die folgenden öffentlichen Methoden:

csvreader.__next__()

Gibt die nächste Zeile des iterierbaren Objekts des Readers als Liste (falls das Objekt von reader() zurückgegeben wurde) oder als Dict (falls es sich um eine DictReader -Instanz handelt) zurück, die gemäß der aktuellen Dialect-Einstellung geparst wurde. In der Regel sollten Sie diese Funktion wie folgt aufrufen: next(reader)`.

Reader objects have the following public attributes:

csvreader.dialect

A read-only description of the dialect in use by the parser.

csvreader.line_num

The number of lines read from the source iterator. This is not the same as the number of records returned, as records can span multiple lines.

DictReader objects have the following public attribute:

DictReader.fieldnames

If not passed as a parameter when creating the object, this attribute is initialized upon first access or when the first record is read from the file.

Writer Objects

Objekte von writer (Instanzen von DictWriter und Objekte, die von der Funktion writer() zurückgegeben werden) haben die folgenden öffentlichen Methoden. Bei Objekten von writer muss eine row ein iterierbares Objekt aus Zeichenketten oder Zahlen sein, bei Objekten von DictWriter ein Dictionary, das Feldnamen auf Zeichenketten oder Zahlen abbildet (die zuvor mit str() umgewandelt werden). Beachte, dass komplexe Zahlen in runde Klammern eingeschlossen ausgegeben werden. Das kann bei anderen Programmen, die CSV-Dateien lesen, zu Problemen führen (sofern sie komplexe Zahlen überhaupt unterstützen).

csvwriter.writerow(row)

Write the row parameter to the writer’s file object, formatted according to the current Dialect. Return the return value of the call to the write method of the underlying file object.

Geändert in Version 3.5: Added support of arbitrary iterables.

csvwriter.writerows(rows)

Schreibe alle Elemente in rows (eine iterierbare Struktur aus row-Objekten, wie oben beschrieben) in das Dateiobjekt des Writers, formatiert gemäß dem aktuellen Dialekts

Writer-Objekte haben die folgende öffentliche Attribut:

csvwriter.dialect

A read-only description of the dialect in use by the writer.

DictWriter objects have the following public method:

DictWriter.writeheader()

Schreibt eine Zeile mit den Feldnamen (wie im Konstruktor angegeben) in das Dateiobjekt des Schreibers, formatiert gemäß dem aktuellen Dialekt. Gibt den Rückgabewert des intern verwendeten Aufrufs von csvwriter.writerow() zurück.

Added in version 3.2.

Geändert in Version 3.8: writeheader() gibt nun auch den Wert zurück, den die intern verwendete Methode csvwriter.writerow() zurückgibt.

Beispiele

The simplest example of reading a CSV file:

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

Reading a file with an alternate format:

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

Das entsprechende einfachste Beispiel zum Schreiben lautet:

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

Since open() is used to open a CSV file for reading, the file will by default be decoded into unicode using the system default encoding (see locale.getencoding()). To decode a file using a different encoding, use the encoding argument of open:

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

The same applies to writing in something other than the system default encoding: specify the encoding argument when opening the output file.

Registering a new dialect:

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

A slightly more advanced use of the reader — catching and reporting errors:

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

And while the module doesn’t directly support parsing strings, it can easily be done:

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

Fußnoten

[1] (1,2)

If newline='' is not specified, newlines embedded inside quoted fields will not be interpreted correctly, and on platforms that use \r\n linendings on write an extra \r will be added. It should always be safe to specify newline='', since the csv module does its own (universal) newline handling.