"csv" --- Lesen und Schreiben von CSV-Dateien
*********************************************

**Quellcode:** 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 geringfügige 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 sind die Trennzeichen und
Anführungszeichen zwar unterschiedlich, das Gesamtformat ist jedoch
ähnlich genug, dass es möglich ist, ein einziges Modul zu schreiben,
das solche Daten effizient bearbeiten kann und dabei die Details des
Lesens und Schreibens der Daten vor dem Programmierer verbirgt.

Das Modul "csv" implementiert Klassen zum Lesen und Schreiben von
tabellarischen Daten im CSV-Format. Es ermöglicht Programmierern,
Anweisungen wie „Schreibe diese Daten in dem von Excel bevorzugten
Format“ oder „Lies Daten aus dieser von Excel erstellten Datei“ zu
geben, ohne die genauen Details des von Excel verwendeten CSV-Formats
kennen zu müssen.  Programmierer können außerdem die von anderen
Anwendungen unterstützten CSV-Formate beschreiben oder eigene CSV-
Formate für spezielle Zwecke definieren.

Die Objekte "reader" und "writer" des Moduls "csv" lesen und schreiben
Sequenzen. Programmierer können Daten auch in Form von Wörterbüchern
mithilfe der Klassen "DictReader" und "DictWriter" lesen und
schreiben.

Siehe auch:

  **PEP 305** - CSV-Datei-API
     Der Python Enhancement Proposal, in dem diese Erweiterung für
     Python vorgeschlagen wurde.


Inhalt des Moduls
=================

Das Modul "csv" definiert die folgenden Funktionen:

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
   Dialekte und Formatierungsparameter.

   Jede aus der CSV-Datei gelesene Zeile wird als Liste von
   Zeichenketten zurückgegeben. Es findet keine automatische
   Datentypkonvertierung statt, es sei denn, die Formatoption
   "QUOTE_NONNUMERIC" ist angegeben (in diesem Fall werden Felder ohne
   Anführungszeichen in Fließkommazahlen umgewandelt).

   Ein kurzes Anwendungsbeispiel:

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

   wobei "eggs.csv" Folgendes enthält:

      Spam Spam Spam Spam Spam |Baked Beans|
      Spam |Leckeres Spam| |Wunderbares Spam|

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

   Gibt ein Writer-Objekt zurück, das die Daten des Benutzers in durch
   Trennzeichen getrennte Zeichenketten für das angegebene
   dateiähnliche Objekt umwandelt. *csvfile* kann ein beliebiges
   Objekt mit einer "write()"-Methode sein. Wenn *csvfile* ein
   Dateiobjekt ist, sollte es mit "newline=''" geöffnet werden [1].
   Ein optionaler *dialect*-Parameter kann angegeben werden, der zur
   Definition eines Satzes von Parametern für einen bestimmten CSV-
   Dialekt verwendet wird. Es kann sich um eine Instanz einer
   Unterklasse der Klasse "Dialect" oder um eine der von der Funktion
   "list_dialects()" zurückgegebenen Zeichenketten handeln. Die
   anderen optionalen *fmtparams*-Schlüsselwortargumente können
   angegeben werden, um einzelne Formatierungsparameter im aktuellen
   Dialekt zu überschreiben. Vollständige Details zu Dialekten und
   Formatierungsparametern findest du im Abschnitt Dialekte und
   Formatierungsparameter. Um die Schnittstelle zu Modulen, die die
   DB-API implementieren, so einfach wie möglich zu gestalten, wird
   der Wert "None" als leere Zeichenkette geschrieben. Auch wenn dies
   keine umkehrbare Umwandlung ist, erleichtert es das Exportieren von
   SQL-NULL-Datenwerten in CSV-Dateien, ohne die von einem
   "cursor.fetch*"-Aufruf zurückgegebenen Daten vorher zu verarbeiten.
   Alle anderen Nicht-Zeichenketten-Daten werden vor dem Schreiben mit
   "str()" in Zeichenketten umgewandelt.

   Ein kurzes Anwendungsbeispiel:

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

   das die Datei "eggs.csv" schreibt, die Folgendes enthält:

      Spam Spam Spam Spam Spam |Baked Beans|
      Spam |Leckeres Spam| |Wunderbares Spam|

csv.register_dialect(name, /, dialect='excel', **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 Dialekte und
   Formatierungsparameter.

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

   Gibt die Namen aller registrierten Dialekte zurück.

csv.field_size_limit()
csv.field_size_limit(new_limit)

   Gibt die aktuell vom Parser zugelassene maximale Feldgröße zurück.
   Wenn *new_limit* angegeben wird, wird dies zur neuen Obergrenze.

Das Modul "csv" definiert die folgenden Klassen:

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 in den Ergebnissen nicht aufgeführt. Wird
   *fieldnames* angegeben, werden diese verwendet und die erste Zeile
   in die Ergebnisse aufgenommen. Unabhängig davon, wie die Feldnamen
   ermittelt werden, behält das Dictionary ihre ursprüngliche
   Reihenfolge bei.

   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".

   Ein kurzes Anwendungsbeispiel:

      >>> 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'}

   wobei "names.csv" Folgendes enthält:

      Vorname,Nachname
      Eric,Idle
      John,Cleese

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)

   Erstelle 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" im
   Gegensatz zur Klasse "DictReader" nicht optional ist.

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

   Ein kurzes Anwendungsbeispiel:

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

   das die Datei "names.csv" schreibt, die Folgendes enthält:

      Vorname,Nachname
      Gebacken,Bohnen
      Reizend,Spam
      Wunderbar,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.

      Wenn mehrere Trennzeichen gleichermaßen gut zum Beispiel passen
      – beispielsweise wenn sowohl "','" als auch "';'" jede Zeile
      konsistent aufteilen –, werden die im Attribut "preferred"
      aufgeführten Trennzeichen in dieser Reihenfolge bevorzugt,
      unabhängig davon, wie oft jedes einzelne davon vorkommt.

   has_header(sample)

      Analysiert den Beispieltext (von dem angenommen wird, dass er im
      CSV-Format vorliegt) und gibt "True" zurück, wenn die erste
      Zeile offenbar aus einer Reihe von Spaltenüberschriften besteht.
      Bei der Prüfung jeder Spalte wird eines von zwei zentralen
      Kriterien herangezogen, um abzuschätzen, ob das Beispiel eine
      Kopfzeile enthält:

      * Die zweite bis zur n-ten Zeile enthalten numerische Werte

      * Die zweite bis zur n-ten Zeile enthalten Zeichenfolgen, bei
        denen sich die Länge mindestens eines Werts von der des
        vermeintlichen Kopfes dieser Spalte unterscheidet.

      Es werden 21 Zeilen nach der Kopfzeile untersucht, wenn mehr als
      die Hälfte der Spalten und Zeilen die Kriterien erfüllen, wird
      "True" zurückgegeben.

   Bemerkung:

     Diese Methode ist eine grobe Heuristik und kann sowohl zu falsch-
     positiven als auch zu falsch-negativen Ergebnissen führen.

   Die Klasse "Sniffer" verfügt über das folgende Attribut:

   preferred

      Die Liste der bevorzugten Kriterien zur Entscheidung bei
      Gleichstand, geordnet nach Priorität. Sie kann geändert werden.
      Der Standardwert lautet "[',', '\t', ';', ' ', ':']".

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)
       # ... hier den Inhalt der CSV-Datei verarbeiten ...

Das Modul "csv" definiert die folgenden Konstanten:

csv.QUOTE_ALL

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

csv.QUOTE_MINIMAL

   Weist Objekte von "writer" an, nur diejenigen Felder in
   Anführungszeichen zu setzen, die Sonderzeichen wie *delimiter*,
   *quotechar*, "'\r'", "'\n'" oder eines der Zeichen in
   *lineterminator* enthalten. Wenn *doublequote* auf "False" gesetzt
   ist und *escapechar* festgelegt ist, wird das *quotechar* mit einem
   Escape-Zeichen versehen, anstatt das Feld in Anführungszeichen zu
   setzen.

csv.QUOTE_NONNUMERIC

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

   Weist Objekte von "reader" an, alle Felder ohne Anführungszeichen
   in den Typ "float" zu konvertieren.

   Bemerkung:

     Einige numerische Typen wie "bool", "Fraction" oder "IntEnum"
     haben eine Darstellung als Zeichenkette, die sich nicht in
     "float"  umwandeln lässt. Sie können in den Modi
     "QUOTE_NONNUMERIC" und "QUOTE_STRINGS" nicht gelesen werden.

csv.QUOTE_NONE

   Weist "writer"-Objekte an, Felder niemals in Anführungszeichen zu
   setzen. Wenn das aktuelle *delimiter*, *quotechar*, *escapechar*,
   "'\r'", "'\n'" oder eines der Zeichen in *lineterminator* in den
   Ausgabedaten vorkommt, wird ihm das aktuelle *escapechar*-Zeichen
   vorangestellt. Wenn *escapechar* nicht gesetzt ist, löst der Writer
   eine "Error" aus, sobald Zeichen auftreten, die einer Escape-
   Verarbeitung bedürfen. Setze *quotechar* auf "None", um dessen
   Escape-Verarbeitung zu verhindern.

   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.

   Weist „ "reader" “-Objekte an, ein leeres (nicht in
   Anführungszeichen gesetztes) Feld als "None" zu interpretieren und
   sich ansonsten wie unter "QUOTE_ALL" beschrieben zu verhalten.

   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.

Das Modul "csv" definiert die folgende Ausnahme:

exception csv.Error

   Wird von einer der Funktionen ausgelöst, wenn ein Fehler erkannt
   wird.


Dialekte und Formatierungsparameter
===================================

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.

Dialekte unterstützen die folgenden Attribute:

Dialect.delimiter

   Eine Zeichenkette mit einem Zeichen, die zur Trennung von Feldern
   verwendet wird. Der Standardwert lautet „ "','" “.

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

   Eine Zeichenkette mit einem Zeichen, die vom Autor verwendet wird,
   um Zeichen zu maskieren, die maskiert werden müssen:

      * Das *Trennzeichen*, das *Anführungszeichen*, "'\r'", "'\n'"
        und alle Zeichen in *Zeilenbegrenzer* werden mit einem Escape-
        Zeichen versehen, wenn *quoting* auf "QUOTE_NONE" gesetzt ist.

      * Das *quotechar* wird mit einem Escape-Zeichen versehen, wenn
        *doublequote* auf "False" gesetzt ist;

      * das *Escape-Zeichen* selbst.

   Beim Einlesen entzieht das *escapechar* dem nachfolgenden Zeichen
   jegliche Sonderbedeutung. Standardmäßig ist "None" eingestellt,
   wodurch das Escaping deaktiviert wird.

   Geändert in Version 3.10: Bisher wurde das *escapechar* selbst
   nicht mit einem Escape-Zeichen versehen, wodurch es beim Einlesen
   verloren ging.

   Geändert in Version 3.11: Ein leeres *escapechar* ist nicht
   zulässig.

Dialect.lineterminator

   Die Zeichenkette, mit der die von "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

   Eine Zeichenkette aus einem Zeichen, die zum Einfassen von Feldern
   verwendet wird, die Sonderzeichen wie das *delimiter* oder das
   *quotechar* enthalten oder die Zeilenumbruchzeichen enthalten
   ("'\r'", "'\n'" oder eines der Zeichen in *lineterminator*). Der
   Standardwert ist "'"'". Kann auf "None" gesetzt werden, um das
   Escaping von "'"'" zu verhindern, wenn *quoting* auf "QUOTE_NONE"
   gesetzt ist.

   Geändert in Version 3.11: Ein leeres *quotechar* ist nicht
   zulässig.

Dialect.quoting

   Steuert, wann der Writer Anführungszeichen erzeugen und der Reader
   sie erkennen soll. Mögliche Werte sind alle QUOTE_*-Konstanten. Der
   Standardwert ist "QUOTE_MINIMAL", wenn *quotechar* nicht "None"
   ist, andernfalls "QUOTE_NONE".

Dialect.skipinitialspace

   Bei "True" werden Leerzeichen, die unmittelbar auf das
   *Trennzeichen* folgen, ignoriert. Die Standardeinstellung lautet
   "False". Bei der Kombination von „ "delimiter=' '" “ mit
   "skipinitialspace=True" sind nicht in Anführungszeichen gesetzte
   leere Felder nicht zulässig.

Dialect.strict

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


Leserobjekte
============

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 Dictionary (falls es sich um eine Instanz von "DictReader"
   handelt) zurück, geparst gemäß dem aktuellen "Dialect".
   Normalerweise rufst du dies als "next(reader)" auf.

Reader-Objekte verfügen über die folgenden öffentlichen Attribute:

csvreader.dialect

   Eine schreibgeschützte Beschreibung des vom Parser verwendeten
   Dialekts.

csvreader.line_num

   Die Anzahl der Zeilen, die aus dem Quell-Iterator gelesen wurden.
   Dies ist nicht mit der Anzahl der zurückgegebenen Datensätze
   identisch, da Datensätze sich über mehrere Zeilen erstrecken
   können.

DictReader-Objekte verfügen über das folgende öffentliche Attribut:

DictReader.fieldnames

   Wird dieses Attribut beim Anlegen des Objekts nicht als Parameter
   übergeben, wird es beim ersten Zugriff oder beim Lesen des ersten
   Datensatzes aus der Datei initialisiert.


Schreibobjekte
==============

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

   Schreibe den Parameter *row* in das Dateiobjekt des Writers,
   formatiert gemäß dem aktuellen "Dialect". Gib den Rückgabewert des
   Aufrufs der Methode *write* des zugrunde liegenden Dateiobjekts
   zurück.

   Geändert in Version 3.5: Unterstützung für beliebige iterierbare
   Objekte hinzugefügt.

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

   Eine rein informative Beschreibung des vom Verfasser verwendeten
   Dialekts.

DictWriter-Objekte verfügen über die folgende öffentliche Methode:

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

Das einfachste Beispiel für das Einlesen einer CSV-Datei:

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

Eine Datei in einem anderen Format lesen:

   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)

Da "open()" zum Öffnen einer CSV-Datei zum Lesen verwendet wird, wird
die Datei standardmäßig mithilfe von UTF-8 in Unicode dekodiert. Um
eine Datei mit einer anderen Kodierung zu dekodieren, verwende das
Argument "encoding" von „open::“

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

Das Gleiche gilt für das Schreiben in einer anderen Kodierung als der
Standardkodierung: Gib beim Öffnen der Ausgabedatei das Argument
„encoding“ an.

Einen neuen Dialekt registrieren:

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

Eine etwas fortgeschrittenere Anwendung des Readers – Fehler erkennen
und melden:

   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(f'file {filename}, line {reader.line_num}: {e}')

Und obwohl das Modul das Parsen von Zeichenketten nicht direkt
unterstützt, lässt sich dies problemlos bewerkstelligen:

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

-[ Fußnoten ]-

[1] Wenn "newline=''" nicht angegeben wird, werden Zeilenumbrüche
    innerhalb von Feldern in Anführungszeichen nicht korrekt
    interpretiert, und auf Plattformen, die beim Schreiben die
    Zeilenenden "\r\n" verwenden, wird ein zusätzliches "\r"
    hinzugefügt. Die Angabe von "newline=''" sollte immer unbedenklich
    sein, da das CSV-Modul eine eigene (*universelle*)  Behandlung von
    Zeilenumbrüchen durchführt.
