codecs — Codec-Registrierung und Basisklassen

Quellcode: Lib/codecs.py

---

Dieses Modul definiert Basisklassen für Standard-Python-Codecs (Encoder und Decoder) und bietet Zugriff auf die interne Python-Codec-Registrierung, die den Suchprozess für Codecs und Fehlerbehandlung verwaltet. Die meisten Standardcodecs sind Textkodierungen, die Text in Bytes kodieren (und Bytes in Text dekodieren), aber es gibt auch bereitgestellte Codecs, die Text in Text und Bytes in Bytes kodieren. Benutzerdefinierte Codecs können zwischen beliebigen Datentypen kodieren und dekodieren, aber einige Modulfunktionen sind darauf beschränkt, speziell für Textkodierungen oder für Codecs, die in bytes kodieren, verwendet zu werden.

Das Modul definiert die folgenden Funktionen zum Kodieren und Dekodieren mit jedem Codec

codecs.encode(obj, encoding='utf-8', errors='strict')

Kodiert obj unter Verwendung des für encoding registrierten Codecs.

Errors kann angegeben werden, um das gewünschte Fehlerbehandlungsschema festzulegen. Der Standard-Fehlerbehandler ist 'strict', was bedeutet, dass Kodierungsfehler ValueError (oder eine spezifischere Unterklasse des Codecs, wie z. B. UnicodeEncodeError) auslösen.

Referenzieren Sie Codec-Basisklassen für weitere Informationen zur Fehlerbehandlung von Codecs.

codecs.decode(obj, encoding='utf-8', errors='strict')

Dekodiert obj unter Verwendung des für encoding registrierten Codecs.

Errors kann angegeben werden, um das gewünschte Fehlerbehandlungsschema festzulegen. Der Standard-Fehlerbehandler ist 'strict', was bedeutet, dass Dekodierungsfehler ValueError (oder eine spezifischere Unterklasse des Codecs, wie z. B. UnicodeDecodeError) auslösen. Referenzieren Sie Codec-Basisklassen für weitere Informationen zur Fehlerbehandlung von Codecs.

codecs.charmap_build(string)

Gibt eine Abbildung zurück, die für die Kodierung mit einer benutzerdefinierten Single-Byte-Kodierung geeignet ist. Gegeben eine str string von bis zu 256 Zeichen, die eine Dekodierungstabelle darstellt, wird entweder ein kompaktes internes Abbildungsobjekt EncodingMap oder ein dictionary zurückgegeben, das Zeichenordinale zu Byte-Werten abbildet. Löst bei ungültiger Eingabe eine TypeError aus.

Die vollständigen Details für jeden Codec können auch direkt nachgeschlagen werden

codecs.lookup(encoding, /)

Sucht die Codec-Informationen in der Python-Codec-Registrierung und gibt ein CodecInfo-Objekt wie unten definiert zurück.

Kodierungen werden zuerst im Cache der Registrierung gesucht. Wenn nicht gefunden, wird die Liste der registrierten Suchfunktionen durchsucht. Wenn kein CodecInfo-Objekt gefunden wird, wird eine LookupError ausgelöst. Andernfalls wird das CodecInfo-Objekt im Cache gespeichert und an den Aufrufer zurückgegeben.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Codec-Details beim Abfragen der Codec-Registrierung. Die Konstruktorargumente werden in Attributen mit demselben Namen gespeichert

name

Der Name der Kodierung.

encode

decode

Die zustandslosen Kodierungs- und Dekodierungsfunktionen. Dies müssen Funktionen oder Methoden sein, die dieselbe Schnittstelle wie die Methoden encode() und decode() von Codec-Instanzen haben (siehe Codec-Schnittstelle). Die Funktionen oder Methoden sollen zustandslos arbeiten.

incrementalencoder

incrementaldecoder

Inkrementelle Encoder- und Decoderklassen oder Factory-Funktionen. Diese müssen die von den Basisklassen IncrementalEncoder und IncrementalDecoder definierten Schnittstellen bereitstellen. Inkrementelle Codecs können einen Zustand beibehalten.

streamwriter

streamreader

Stream-Writer- und Reader-Klassen oder Factory-Funktionen. Diese müssen die von den Basisklassen StreamWriter und StreamReader definierten Schnittstellen bereitstellen. Stream-Codecs können einen Zustand beibehalten.

Um den Zugriff auf die verschiedenen Codec-Komponenten zu vereinfachen, bietet das Modul diese zusätzlichen Funktionen, die lookup() für die Codec-Suche verwenden

codecs.getencoder(encoding)

Sucht den Codec für die angegebene Kodierung und gibt seine Encoder-Funktion zurück.

Löst eine LookupError aus, wenn die Kodierung nicht gefunden werden kann.

codecs.getdecoder(encoding)

Sucht den Codec für die angegebene Kodierung und gibt seine Decoder-Funktion zurück.

Löst eine LookupError aus, wenn die Kodierung nicht gefunden werden kann.

codecs.getincrementalencoder(encoding)

Sucht den Codec für die angegebene Kodierung und gibt seine inkrementelle Encoder-Klasse oder Factory-Funktion zurück.

Löst eine LookupError aus, wenn die Kodierung nicht gefunden werden kann oder der Codec keinen inkrementellen Encoder unterstützt.

codecs.getincrementaldecoder(encoding)

Sucht den Codec für die angegebene Kodierung und gibt seine inkrementelle Decoder-Klasse oder Factory-Funktion zurück.

Löst eine LookupError aus, wenn die Kodierung nicht gefunden werden kann oder der Codec keinen inkrementellen Decoder unterstützt.

codecs.getreader(encoding)

Sucht den Codec für die angegebene Kodierung und gibt seine StreamReader-Klasse oder Factory-Funktion zurück.

Löst eine LookupError aus, wenn die Kodierung nicht gefunden werden kann.

codecs.getwriter(encoding)

Sucht den Codec für die angegebene Kodierung und gibt seine StreamWriter-Klasse oder Factory-Funktion zurück.

Löst eine LookupError aus, wenn die Kodierung nicht gefunden werden kann.

Benutzerdefinierte Codecs werden durch Registrierung einer geeigneten Codec-Suchfunktion verfügbar gemacht

codecs.register(search_function, /)

Registriert eine Codec-Suchfunktion. Suchfunktionen sollen ein Argument entgegennehmen, nämlich den Kodierungsnamen in Kleinbuchstaben, wobei Bindestriche und Leerzeichen durch Unterstriche ersetzt werden, und ein CodecInfo-Objekt zurückgeben. Wenn eine Suchfunktion eine gegebene Kodierung nicht finden kann, sollte sie None zurückgeben.

Geändert in Version 3.9: Bindestriche und Leerzeichen werden durch Unterstriche ersetzt.

codecs.unregister(search_function, /)

Registriert eine Codec-Suchfunktion ab und leert den Cache der Registrierung. Wenn die Suchfunktion nicht registriert ist, wird nichts unternommen.

Hinzugefügt in Version 3.10.

Während die eingebaute open() und das zugehörige Modul io der empfohlene Ansatz für die Arbeit mit kodierten Textdateien sind, stellt dieses Modul zusätzliche Dienstprogramme und Klassen bereit, die die Verwendung einer breiteren Palette von Codecs bei der Arbeit mit Binärdateien ermöglichen

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

Öffnet eine kodierte Datei im angegebenen mode und gibt eine Instanz von StreamReaderWriter zurück, die eine transparente Kodierung/Dekodierung bietet. Die zugrunde liegende Datei wird geschlossen, wenn die verpackte Version geschlossen wird.

Hinweis

Wenn encoding nicht None ist, werden die zugrunde liegenden kodierten Dateien immer im Binärmodus geöffnet. Keine automatische Konvertierung von '\n' wird beim Lesen und Schreiben durchgeführt. Das mode-Argument kann jeder binäre Modus sein, der für die eingebaute open()-Funktion akzeptabel ist; das 'b' wird automatisch hinzugefügt.

encoding gibt die zu verwendende Kodierung für die Datei an. Jede Kodierung, die in Bytes kodiert und aus Bytes dekodiert werden kann, ist erlaubt, und die von den Dateimethoden unterstützten Datentypen hängen vom verwendeten Codec ab.

errors kann angegeben werden, um die Fehlerbehandlung zu definieren. Es ist standardmäßig 'strict', was dazu führt, dass ein ValueError ausgelöst wird, wenn ein Kodierungsfehler auftritt.

buffering hat dieselbe Bedeutung wie für die eingebaute open()-Funktion. Es ist standardmäßig -1, was bedeutet, dass die Standard-Puffergröße verwendet wird.

Geändert in Version 3.11: Der Modus 'U' wurde entfernt.

Veraltet seit Version 3.14: codecs.open() wurde durch open() abgelöst.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

Gibt eine Instanz von StreamRecoder zurück, eine verpackte Version von file, die eine transparente Transkodierung bietet. Die Originaldatei wird geschlossen, wenn die verpackte Version geschlossen wird.

In die verpackte Datei geschriebene Daten werden gemäß der angegebenen data_encoding dekodiert und dann mit file_encoding als Bytes in die Originaldatei geschrieben. Bytes, die aus der Originaldatei gelesen werden, werden gemäß file_encoding dekodiert, und das Ergebnis wird mit data_encoding kodiert.

Wenn file_encoding nicht angegeben ist, wird standardmäßig data_encoding verwendet.

errors kann angegeben werden, um die Fehlerbehandlung zu definieren. Es ist standardmäßig 'strict', was dazu führt, dass ValueError ausgelöst wird, wenn ein Kodierungsfehler auftritt.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

Verwendet einen inkrementellen Encoder, um die vom iterator bereitgestellten Eingaben iterativ zu kodieren. iterator muss str-Objekte liefern. Diese Funktion ist ein Generator. Das Argument errors (sowie alle anderen Schlüsselwortargumente) wird an den inkrementellen Encoder weitergegeben.

Diese Funktion erfordert, dass der Codec Text- str-Objekte zur Kodierung akzeptiert. Daher unterstützt sie keine Byte-zu-Byte-Encoder wie z. B. base64_codec.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

Verwendet einen inkrementellen Decoder, um die vom iterator bereitgestellten Eingaben iterativ zu dekodieren. iterator muss bytes-Objekte liefern. Diese Funktion ist ein Generator. Das Argument errors (sowie alle anderen Schlüsselwortargumente) wird an den inkrementellen Decoder weitergegeben.

Diese Funktion erfordert, dass der Codec bytes-Objekte zur Dekodierung akzeptiert. Daher unterstützt sie keine Text-zu-Text-Encoder wie z. B. rot_13, obwohl rot_13 äquivalent mit iterencode() verwendet werden kann.

codecs.readbuffer_encode(buffer, errors=None, /)

Gibt ein tuple zurück, das die rohen Bytes von buffer, ein buffer-kompatibles Objekt oder str (vor der Verarbeitung in UTF-8 kodiert) und ihre Länge in Bytes enthält.

Das Argument errors wird ignoriert.

>>> codecs.readbuffer_encode(b"Zito")
(b'Zito', 4)

Das Modul stellt außerdem die folgenden Konstanten bereit, die für das Lesen und Schreiben auf plattformabhängigen Dateien nützlich sind

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

Diese Konstanten definieren verschiedene Byte-Sequenzen, die Unicode Byte Order Marks (BOMs) für mehrere Kodierungen sind. Sie werden in UTF-16- und UTF-32-Datenströmen verwendet, um die verwendete Byte-Reihenfolge anzugeben, und in UTF-8 als Unicode-Signatur. BOM_UTF16 ist entweder BOM_UTF16_BE oder BOM_UTF16_LE, abhängig von der nativen Byte-Reihenfolge der Plattform, BOM ist ein Alias für BOM_UTF16, BOM_LE für BOM_UTF16_LE und BOM_BE für BOM_UTF16_BE. Die anderen repräsentieren die BOM in UTF-8- und UTF-32-Kodierungen.

Codec-Basisklassen

Das Modul codecs definiert eine Reihe von Basisklassen, die die Schnittstellen für die Arbeit mit Codec-Objekten definieren und auch als Grundlage für benutzerdefinierte Codec-Implementierungen dienen können.

Jeder Codec muss vier Schnittstellen definieren, um als Codec in Python verwendbar zu sein: zustandloser Encoder, zustandloser Decoder, Stream-Reader und Stream-Writer. Die Stream-Reader und -Writer verwenden typischerweise den zustandslosen Encoder/Decoder, um die Dateiprotokolle zu implementieren. Codec-Autoren müssen auch definieren, wie der Codec Kodierungs- und Dekodierungsfehler behandelt.

Fehlerbehandler

Um die Fehlerbehandlung zu vereinfachen und zu standardisieren, können Codecs verschiedene Fehlerbehandlungsschemata implementieren, indem sie das Argument errors akzeptieren.

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German ß, ♬'

Die folgenden Fehlerbehandler können mit allen Standardkodierungen von Python-Codecs verwendet werden

Wert	Bedeutung
'strict'	Löst UnicodeError (oder eine Unterklasse) aus, dies ist der Standard. Implementiert in strict_errors().
'ignore'	Ignoriert die fehlerhaften Daten und fährt ohne weitere Benachrichtigung fort. Implementiert in ignore_errors().
'replace'	Ersetzt durch ein Ersatzzeichen. Beim Kodieren wird ? (ASCII-Zeichen) verwendet. Beim Dekodieren wird � (U+FFFD, das offizielle Ersetzungszeichen) verwendet. Implementiert in replace_errors().
'backslashreplace'	Ersetzt durch Backslash-Escape-Sequenzen. Beim Kodieren wird die hexadezimale Form des Unicode-Codepunkts mit den Formaten \xhh \uxxxx \Uxxxxxxxx verwendet. Beim Dekodieren wird die hexadezimale Form des Byte-Werts mit dem Format \xhh verwendet. Implementiert in backslashreplace_errors().
'surrogateescape'	Beim Dekodieren wird ein Byte durch einen einzelnen Surrogate-Code im Bereich von U+DC80 bis U+DCFF ersetzt. Dieser Code wird dann wieder in dasselbe Byte umgewandelt, wenn der Fehlerbehandler 'surrogateescape' zum Kodieren der Daten verwendet wird. (Siehe PEP 383 für weitere Informationen.)

Die folgenden Fehlerbehandler sind nur für die Kodierung (innerhalb von Textkodierungen) anwendbar

Wert	Bedeutung
'xmlcharrefreplace'	Ersetzt durch eine numerische Zeichenreferenz in XML/HTML, die eine dezimale Form des Unicode-Codepunkts mit dem Format &#num; ist. Implementiert in xmlcharrefreplace_errors().
'namereplace'	Ersetzt durch \N{...}-Escape-Sequenzen, wobei in den geschweiften Klammern die Name-Eigenschaft aus der Unicode-Zeichen-Datenbank steht. Implementiert in namereplace_errors().

Zusätzlich ist der folgende Fehlerbehandler spezifisch für die angegebenen Codecs

Wert	Codecs	Bedeutung
'surrogatepass'	utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le	Erlaubt die Kodierung und Dekodierung von Surrogate-Codepunkten (U+D800 - U+DFFF) als normale Codepunkte. Andernfalls behandeln diese Codecs das Vorhandensein von Surrogate-Codepunkten in str als Fehler.

Hinzugefügt in Version 3.1: Die Fehlerbehandlungsroutinen 'surrogateescape' und 'surrogatepass'.

Geändert in Version 3.4: Die Fehlerbehandlungsroutine 'surrogatepass' funktioniert jetzt mit utf-16* und utf-32* Codecs.

Hinzugefügt in Version 3.5: Die Fehlerbehandlungsroutine 'namereplace'.

Geändert in Version 3.5: Die Fehlerbehandlungsroutine 'backslashreplace' funktioniert jetzt mit Dekodierung und Übersetzung.

Die Menge der erlaubten Werte kann durch Registrieren einer neuen benannten Fehlerbehandlungsroutine erweitert werden

codecs.register_error(name, error_handler, /)

Registriert die Fehlerbehandlungsfunktion error_handler unter dem Namen name. Das Argument error_handler wird bei der Kodierung und Dekodierung im Fehlerfall aufgerufen, wenn name als Fehlerparameter angegeben wird.

Bei der Kodierung wird error_handler mit einer UnicodeEncodeError-Instanz aufgerufen, die Informationen über den Speicherort des Fehlers enthält. Der Fehlerbehandler muss entweder diese oder eine andere Ausnahme auslösen oder ein Tupel mit einem Ersatz für den nicht kodierbaren Teil der Eingabe und einer Position zurückgeben, an der die Kodierung fortgesetzt werden soll. Der Ersatz kann entweder str oder bytes sein. Wenn der Ersatz Bytes sind, kopiert der Encoder sie einfach in den Ausgabepuffer. Wenn der Ersatz ein String ist, kodiert der Encoder den Ersatz. Die Kodierung wird am ursprünglichen Eingabestring an der angegebenen Position fortgesetzt. Negative Positionsangaben werden als relativ zum Ende des Eingabestrings behandelt. Wenn die resultierende Position außerhalb des Gültigkeitsbereichs liegt, wird eine IndexError ausgelöst.

Die Dekodierung und Übersetzung funktioniert ähnlich, mit dem Unterschied, dass UnicodeDecodeError oder UnicodeTranslateError an den Handler übergeben werden und der Ersatz vom Fehlerhandler direkt in die Ausgabe eingefügt wird.

Zuvor registrierte Fehlerbehandler (einschließlich der Standardfehlerbehandler) können anhand ihres Namens abgerufen werden

codecs.lookup_error(name, /)

Gibt die Fehlerbehandlungsroutine zurück, die zuvor unter dem Namen name registriert wurde.

Löst eine LookupError aus, wenn der Handler nicht gefunden werden kann.

Die folgenden Standardfehlerbehandler werden auch als Modulfunktionen zur Verfügung gestellt

codecs.strict_errors(exception)

Implementiert die Fehlerbehandlung 'strict'.

Jeder Kodierungs- oder Dekodierungsfehler löst eine UnicodeError aus.

codecs.ignore_errors(exception)

Implementiert die Fehlerbehandlung 'ignore'.

Fehlerhafte Daten werden ignoriert; Kodierung oder Dekodierung wird ohne weitere Benachrichtigung fortgesetzt.

codecs.replace_errors(exception)

Implementiert die Fehlerbehandlung 'replace'.

Ersetzt bei Kodierungsfehlern ein ? (ASCII-Zeichen) oder bei Dekodierungsfehlern ein � (U+FFFD, das offizielle Ersetzungszeichen).

codecs.backslashreplace_errors(exception)

Implementiert die Fehlerbehandlung 'backslashreplace'.

Fehlerhafte Daten werden durch eine Backslash-Escape-Sequenz ersetzt. Bei der Kodierung wird die hexadezimale Form des Unicode-Codepunkts mit den Formaten \xhh \uxxxx \Uxxxxxxxx verwendet. Bei der Dekodierung wird die hexadezimale Form des Byte-Werts mit dem Format \xhh verwendet.

Geändert in Version 3.5: Funktioniert mit Dekodierung und Übersetzung.

codecs.xmlcharrefreplace_errors(exception)

Implementiert die Fehlerbehandlung 'xmlcharrefreplace' (nur bei der Kodierung innerhalb der Textkodierung).

Das nicht kodierbare Zeichen wird durch eine entsprechende numerische XML/HTML-Zeichenreferenz ersetzt, die eine dezimale Form des Unicode-Codepunkts im Format &#num; ist.

codecs.namereplace_errors(exception)

Implementiert die Fehlerbehandlung 'namereplace' (nur bei der Kodierung innerhalb der Textkodierung).

Das nicht kodierbare Zeichen wird durch eine \N{...}-Escape-Sequenz ersetzt. Die Zeichenmenge in den Klammern ist die Name-Eigenschaft der Unicode Character Database. Zum Beispiel wird der deutsche Kleinbuchstabe 'ß' in die Byte-Sequenz \N{LATIN SMALL LETTER SHARP S} konvertiert.

Hinzugefügt in Version 3.5.

Zustandslose Kodierung und Dekodierung

Die Basisklasse Codec definiert diese Methoden, die auch die Schnittstellen der zustandslosen Encoder und Decoder definieren.

class codecs.Codec

encode(input, errors='strict')

Kodiert das Objekt input und gibt ein Tupel (Ausgabeobjekt, verbrauchte Länge) zurück. Beispielsweise konvertiert eine Textkodierung ein String-Objekt in ein Bytes-Objekt unter Verwendung einer bestimmten Zeichensatzkodierung (z. B. cp1252 oder iso-8859-1).

Das Argument errors definiert die anzuwendende Fehlerbehandlung. Standardmäßig wird die Behandlung 'strict' verwendet.

Die Methode darf keinen Zustand in der Instanz Codec speichern. Verwenden Sie StreamWriter für Codecs, die zur effizienten Kodierung einen Zustand beibehalten müssen.

Der Encoder muss in der Lage sein, eine Eingabe der Länge Null zu verarbeiten und in diesem Fall ein leeres Objekt des Ausgabetyp zurückzugeben.

decode(input, errors='strict')

Dekodiert das Objekt input und gibt ein Tupel (Ausgabeobjekt, verbrauchte Länge) zurück. Bei einer Textkodierung konvertiert die Dekodierung beispielsweise ein Bytes-Objekt, das mit einer bestimmten Zeichensatzkodierung kodiert wurde, in ein String-Objekt.

Für Textkodierungen und Bytes-zu-Bytes-Codecs muss input ein Bytes-Objekt oder ein Objekt sein, das die schreibgeschützte Puffer-Schnittstelle bereitstellt – zum Beispiel Puffer-Objekte und speicherzugeordnete Dateien.

Das Argument errors definiert die anzuwendende Fehlerbehandlung. Standardmäßig wird die Behandlung 'strict' verwendet.

Die Methode darf keinen Zustand in der Instanz Codec speichern. Verwenden Sie StreamReader für Codecs, die zur effizienten Dekodierung einen Zustand beibehalten müssen.

Der Decoder muss in der Lage sein, eine Eingabe der Länge Null zu verarbeiten und in diesem Fall ein leeres Objekt des Ausgabetyp zurückzugeben.

Inkrementelle Kodierung und Dekodierung

Die Klassen IncrementalEncoder und IncrementalDecoder stellen die grundlegende Schnittstelle für inkrementelle Kodierung und Dekodierung bereit. Die Kodierung/Dekodierung der Eingabe erfolgt nicht mit einem einzigen Aufruf der zustandslosen Encoder/Decoder-Funktion, sondern mit mehreren Aufrufen der Methode encode()/decode() des inkrementellen Encoders/Decoders. Der inkrementelle Encoder/Decoder verfolgt den Kodierungs-/Dekodierungsprozess während der Methodenaufrufe.

Die zusammengefasste Ausgabe von Aufrufen der Methode encode()/decode() ist dieselbe, als wären alle einzelnen Eingaben zu einer einzigen zusammengefasst und diese Eingabe mit dem zustandslosen Encoder/Decoder kodiert/dekodiert worden.

IncrementalEncoder-Objekte

Die Klasse IncrementalEncoder wird verwendet, um eine Eingabe schrittweise zu kodieren. Sie definiert die folgenden Methoden, die jeder inkrementelle Encoder definieren muss, um mit der Python-Codec-Registry kompatibel zu sein.

class codecs.IncrementalEncoder(errors='strict')

Konstruktor für eine Instanz von IncrementalEncoder.

Alle inkrementellen Encoder müssen diese Konstruktorschnittstelle bereitstellen. Sie können zusätzliche Schlüsselwortargumente hinzufügen, aber nur die hier definierten werden von der Python-Codec-Registry verwendet.

Der IncrementalEncoder kann verschiedene Fehlerbehandlungsmechanismen implementieren, indem das Schlüsselwortargument errors bereitgestellt wird. Mögliche Werte finden Sie unter Fehlerbehandler.

Das Argument errors wird einem Attribut mit demselben Namen zugewiesen. Die Zuweisung zu diesem Attribut ermöglicht den Wechsel zwischen verschiedenen Fehlerbehandlungsstrategien während der Lebensdauer des Objekts IncrementalEncoder.

encode(object, final=False)

Kodiert object (unter Berücksichtigung des aktuellen Zustands des Encoders) und gibt das resultierende kodierte Objekt zurück. Wenn dies der letzte Aufruf von encode() ist, muss final true sein (Standard ist false).

reset()

Setzt den Encoder in den Anfangszustand zurück. Die Ausgabe wird verworfen: rufen Sie .encode(object, final=True) auf, übergeben Sie bei Bedarf einen leeren Byte- oder Textstring, um den Encoder zurückzusetzen und die Ausgabe zu erhalten.

getstate()

Gibt den aktuellen Zustand des Encoders zurück, der eine Ganzzahl sein muss. Die Implementierung sollte sicherstellen, dass 0 der häufigste Zustand ist. (Komplexere Zustände als Ganzzahlen können in eine Ganzzahl umgewandelt werden, indem der Zustand marshalled/pickled und die Bytes des resultierenden Strings in eine Ganzzahl kodiert werden.)

setstate(state)

Setzt den Zustand des Encoders auf state. state muss ein von getstate() zurückgegebener Encoderzustand sein.

IncrementalDecoder-Objekte

Die Klasse IncrementalDecoder wird verwendet, um eine Eingabe schrittweise zu dekodieren. Sie definiert die folgenden Methoden, die jeder inkrementelle Decoder definieren muss, um mit der Python-Codec-Registry kompatibel zu sein.

class codecs.IncrementalDecoder(errors='strict')

Konstruktor für eine Instanz von IncrementalDecoder.

Alle inkrementellen Decoder müssen diese Konstruktorschnittstelle bereitstellen. Sie können zusätzliche Schlüsselwortargumente hinzufügen, aber nur die hier definierten werden von der Python-Codec-Registry verwendet.

Der IncrementalDecoder kann verschiedene Fehlerbehandlungsmechanismen implementieren, indem das Schlüsselwortargument errors bereitgestellt wird. Mögliche Werte finden Sie unter Fehlerbehandler.

Das Argument errors wird einem Attribut mit demselben Namen zugewiesen. Die Zuweisung zu diesem Attribut ermöglicht den Wechsel zwischen verschiedenen Fehlerbehandlungsstrategien während der Lebensdauer des Objekts IncrementalDecoder.

decode(object, final=False)

Dekodiert object (unter Berücksichtigung des aktuellen Zustands des Decoders) und gibt das resultierende dekodierte Objekt zurück. Wenn dies der letzte Aufruf von decode() ist, muss final true sein (Standard ist false). Wenn final true ist, muss der Decoder die Eingabe vollständig dekodieren und alle Puffer leeren. Wenn dies nicht möglich ist (z. B. wegen unvollständiger Byte-Sequenzen am Ende der Eingabe), muss er die Fehlerbehandlung wie im zustandslosen Fall einleiten (was eine Ausnahme auslösen kann).

reset()

Setzt den Decoder in den Anfangszustand zurück.

getstate()

Gibt den aktuellen Zustand des Decoders zurück. Dies muss ein Tupel mit zwei Elementen sein, das erste muss der Puffer mit der noch un dekodierten Eingabe sein. Das zweite muss eine Ganzzahl sein und kann zusätzliche Zustandsinformationen enthalten. (Die Implementierung sollte sicherstellen, dass 0 die häufigste zusätzliche Zustandsinformation ist.) Wenn diese zusätzliche Zustandsinformation 0 ist, muss es möglich sein, den Decoder in den Zustand zu versetzen, der keine gepufferte Eingabe und 0 als zusätzliche Zustandsinformation hat, so dass die vorher gepufferte Eingabe an den Decoder übergeben wird, um ihn in den vorherigen Zustand zurückzusetzen, ohne eine Ausgabe zu erzeugen. (Zusätzliche Zustandsinformationen, die komplexer als Ganzzahlen sind, können in eine Ganzzahl umgewandelt werden, indem die Informationen marshalled/pickled und die Bytes des resultierenden Strings in eine Ganzzahl kodiert werden.)

setstate(state)

Setzt den Zustand des Decoders auf state. state muss ein von getstate() zurückgegebener Decoderzustand sein.

Stream-Kodierung und Dekodierung

Die Klassen StreamWriter und StreamReader bieten generische Arbeitsinterfaces, die zur Implementierung neuer Kodierungs-Submodule sehr einfach genutzt werden können. Siehe encodings.utf_8 als Beispiel dafür, wie dies geschieht.

StreamWriter-Objekte

Die Klasse StreamWriter ist eine Unterklasse von Codec und definiert die folgenden Methoden, die jeder Stream-Writer definieren muss, um mit der Python-Codec-Registry kompatibel zu sein.

class codecs.StreamWriter(stream, errors='strict')

Konstruktor für eine Instanz von StreamWriter.

Alle Stream-Writer müssen diese Konstruktorschnittstelle bereitstellen. Sie können zusätzliche Schlüsselwortargumente hinzufügen, aber nur die hier definierten werden von der Python-Codec-Registry verwendet.

Das Argument stream muss ein dateiähnliches Objekt sein, das zum Schreiben von Text oder Binärdaten geöffnet ist, je nach spezifischem Codec.

Der StreamWriter kann verschiedene Fehlerbehandlungsmechanismen implementieren, indem das Schlüsselwortargument errors bereitgestellt wird. Siehe Fehlerbehandler für die Standardfehlerbehandler, die der zugrunde liegende Stream-Codec unterstützen kann.

Das Argument errors wird einem Attribut mit demselben Namen zugewiesen. Die Zuweisung zu diesem Attribut ermöglicht den Wechsel zwischen verschiedenen Fehlerbehandlungsstrategien während der Lebensdauer des Objekts StreamWriter.

write(object)

Schreibt den Inhalt des Objekts kodiert in den Stream.

writelines(list)

Schreibt das verkettete Iterable von Strings in den Stream (möglicherweise unter Wiederverwendung der Methode write()). Unendliche oder sehr große Iterables werden nicht unterstützt. Die Standard-Bytes-zu-Bytes-Codecs unterstützen diese Methode nicht.

reset()

Setzt die für die interne Zustandsverwaltung verwendeten Codec-Puffer zurück.

Der Aufruf dieser Methode sollte sicherstellen, dass die Daten in der Ausgabe in einen sauberen Zustand versetzt werden, der das Anhängen neuer Daten ermöglicht, ohne den gesamten Stream durchsuchen zu müssen, um den Zustand wiederherzustellen.

Zusätzlich zu den oben genannten Methoden muss der StreamWriter alle anderen Methoden und Attribute des zugrunde liegenden Streams erben.

StreamReader-Objekte

Die Klasse StreamReader ist eine Unterklasse von Codec und definiert die folgenden Methoden, die jeder Stream-Reader definieren muss, um mit der Python-Codec-Registry kompatibel zu sein.

class codecs.StreamReader(stream, errors='strict')

Konstruktor für eine Instanz von StreamReader.

Alle Stream-Reader müssen diese Konstruktorschnittstelle bereitstellen. Sie können zusätzliche Schlüsselwortargumente hinzufügen, aber nur die hier definierten werden von der Python-Codec-Registry verwendet.

Das Argument stream muss ein dateiähnliches Objekt sein, das zum Lesen von Text oder Binärdaten geöffnet ist, je nach spezifischem Codec.

Der StreamReader kann verschiedene Fehlerbehandlungsmechanismen implementieren, indem das Schlüsselwortargument errors bereitgestellt wird. Siehe Fehlerbehandler für die Standardfehlerbehandler, die der zugrunde liegende Stream-Codec unterstützen kann.

Das Argument errors wird einem gleichnamigen Attribut zugewiesen. Die Zuweisung zu diesem Attribut ermöglicht es, während der Lebensdauer des StreamReader-Objekts zwischen verschiedenen Fehlerbehandlungsstrategien zu wechseln.

Die Menge der erlaubten Werte für das Argument errors kann mit register_error() erweitert werden.

read(size=-1, chars=-1, firstline=False)

Dekodiert Daten aus dem Stream und gibt das Ergebnisobjekt zurück.

Das Argument chars gibt die Anzahl der zu dekodierenden Code-Punkte oder Bytes an, die zurückgegeben werden sollen. Die Methode read() gibt niemals mehr Daten zurück, als angefordert wurde, kann aber weniger zurückgeben, wenn nicht genügend Daten verfügbar sind.

Das Argument size gibt die ungefähre maximale Anzahl von kodierten Bytes oder Code-Punkten an, die zur Dekodierung gelesen werden sollen. Der Dekodierer kann diese Einstellung nach Bedarf ändern. Der Standardwert -1 bedeutet, so viel wie möglich zu lesen und zu dekodieren. Dieser Parameter soll verhindern, dass riesige Dateien in einem Schritt dekodiert werden müssen.

Das Flag firstline gibt an, dass es ausreichen würde, nur die erste Zeile zurückzugeben, wenn auf späteren Zeilen Dekodierungsfehler auftreten.

Die Methode sollte eine Greedy-Read-Strategie verwenden, d.h. sie sollte so viele Daten lesen, wie es die Definition der Kodierung und die gegebene Größe zulassen. Wenn z.B. optionale Kodierungsendezeichen oder Zustandsmarkierungen im Stream verfügbar sind, sollten diese ebenfalls gelesen werden.

readline(size=None, keepends=True)

Liest eine Zeile aus dem Eingabestream und gibt die dekodierten Daten zurück.

size, falls angegeben, wird als size-Argument an die read()-Methode des Streams übergeben.

Wenn keepends falsch ist, werden Zeilenenden aus den zurückgegebenen Zeilen entfernt.

readlines(sizehint=None, keepends=True)

Liest alle verfügbaren Zeilen im Eingabestream und gibt sie als Liste von Zeilen zurück.

Zeilenenden werden mithilfe der decode()-Methode des Codecs implementiert und sind in den Listeneinträgen enthalten, wenn keepends wahr ist.

sizehint, falls angegeben, wird als size-Argument an die read()-Methode des Streams übergeben.

reset()

Setzt die für die interne Zustandsverwaltung verwendeten Codec-Puffer zurück.

Beachten Sie, dass keine Stream-Neupositionierung stattfinden sollte. Diese Methode ist hauptsächlich dazu gedacht, sich von Dekodierungsfehlern zu erholen.

Zusätzlich zu den oben genannten Methoden muss der StreamReader alle anderen Methoden und Attribute des zugrundeliegenden Streams erben.

StreamReaderWriter-Objekte

Die StreamReaderWriter ist eine praktische Klasse, die es ermöglicht, Streams zu umschließen, die sowohl im Lese- als auch im Schreibmodus arbeiten.

Das Design ist so gestaltet, dass man die Factory-Funktionen, die von der lookup()-Funktion zurückgegeben werden, zur Konstruktion der Instanz verwenden kann.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

Erzeugt eine StreamReaderWriter-Instanz. stream muss ein dateiähnliches Objekt sein. Reader und Writer müssen Factory-Funktionen oder Klassen sein, die die StreamReader- bzw. StreamWriter-Schnittstelle bereitstellen. Die Fehlerbehandlung erfolgt auf dieselbe Weise wie für die Stream-Reader und -Writer definiert.

StreamReaderWriter-Instanzen definieren die kombinierten Schnittstellen von StreamReader und StreamWriter-Klassen. Sie erben alle anderen Methoden und Attribute vom zugrundeliegenden Stream.

StreamRecoder-Objekte

Die StreamRecoder übersetzt Daten von einer Kodierung in eine andere, was manchmal nützlich ist, wenn man mit verschiedenen Kodierungsumgebungen arbeitet.

Das Design ist so gestaltet, dass man die Factory-Funktionen, die von der lookup()-Funktion zurückgegeben werden, zur Konstruktion der Instanz verwenden kann.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Erzeugt eine StreamRecoder-Instanz, die eine bidirektionale Konvertierung implementiert: encode und decode arbeiten am Frontend – den Daten, die für den Code sichtbar sind, der read() und write() aufruft, während Reader und Writer am Backend arbeiten – den Daten in stream.

Sie können diese Objekte verwenden, um transparente Transkodierungen durchzuführen, z.B. von Latin-1 nach UTF-8 und zurück.

Das Argument stream muss ein dateiähnliches Objekt sein.

Die Argumente encode und decode müssen der Codec-Schnittstelle entsprechen. Reader und Writer müssen Factory-Funktionen oder Klassen sein, die Objekte der StreamReader- bzw. StreamWriter-Schnittstelle bereitstellen.

Die Fehlerbehandlung erfolgt auf dieselbe Weise wie für die Stream-Reader und -Writer definiert.

StreamRecoder-Instanzen definieren die kombinierten Schnittstellen von StreamReader und StreamWriter-Klassen. Sie erben alle anderen Methoden und Attribute vom zugrundeliegenden Stream.

Kodierungen und Unicode

Strings werden intern als Sequenzen von Code-Punkten im Bereich U+0000–U+10FFFF gespeichert. (Siehe PEP 393 für weitere Details zur Implementierung.) Sobald ein String-Objekt außerhalb der CPU und des Speichers verwendet wird, werden Endianness und die Art und Weise, wie diese Arrays als Bytes gespeichert werden, zu einem Problem. Wie bei anderen Codecs wird das Serialisieren eines Strings in eine Byte-Sequenz als Kodierung und das Wiederherstellen des Strings aus der Byte-Sequenz als Dekodierung bezeichnet. Es gibt eine Vielzahl von verschiedenen Text-Serialisierungs-Codecs, die kollektiv als Textkodierungen bezeichnet werden.

Die einfachste Textkodierung (genannt 'latin-1' oder 'iso-8859-1') bildet die Code-Punkte 0–255 auf die Bytes 0x0–0xff ab, was bedeutet, dass ein String-Objekt, das Code-Punkte über U+00FF enthält, mit diesem Codec nicht kodiert werden kann. Dies führt zu einem UnicodeEncodeError, der wie folgt aussieht (obwohl die Details der Fehlermeldung abweichen können): UnicodeEncodeError: `latin-1` codec can't encode character '\u1234' in position 3: ordinal not in range(256).

Es gibt eine weitere Gruppe von Kodierungen (die sogenannten Charmap-Kodierungen), die eine andere Teilmenge aller Unicode-Code-Punkte wählen und festlegen, wie diese Code-Punkte auf die Bytes 0x0–0xff abgebildet werden. Um zu sehen, wie dies geschieht, öffnen Sie z.B. encodings/cp1252.py (eine Kodierung, die hauptsächlich unter Windows verwendet wird). Dort gibt es eine String-Konstante mit 256 Zeichen, die zeigt, welches Zeichen welchem Byte-Wert zugeordnet ist.

Alle diese Kodierungen können nur 256 der 1114112 in Unicode definierten Code-Punkte kodieren. Eine einfache und geradlinige Methode, die jeden Unicode-Code-Punkt speichern kann, ist, jeden Code-Punkt als vier aufeinanderfolgende Bytes zu speichern. Es gibt zwei Möglichkeiten: die Bytes in Big-Endian- oder Little-Endian-Reihenfolge zu speichern. Diese beiden Kodierungen werden als UTF-32-BE bzw. UTF-32-LE bezeichnet. Ihr Nachteil ist, dass z.B. bei Verwendung von UTF-32-BE auf einer Little-Endian-Maschine immer Bytes beim Kodieren und Dekodieren vertauscht werden müssen. UTF-32 vermeidet dieses Problem: Bytes sind immer in natürlicher Endianness. Wenn diese Bytes von einer CPU mit anderer Endianness gelesen werden, müssen Bytes jedoch vertauscht werden. Um die Endianness einer UTF-16- oder UTF-32-Byte-Sequenz erkennen zu können, gibt es die sogenannte BOM ("Byte Order Mark"). Dies ist das Unicode-Zeichen U+FEFF. Dieses Zeichen kann jeder UTF-16- oder UTF-32-Byte-Sequenz vorangestellt werden. Die byte-vertauschte Version dieses Zeichens (0xFFFE) ist ein illegales Zeichen, das in einem Unicode-Text nicht vorkommen darf. Wenn also das erste Zeichen in einer UTF-16- oder UTF-32-Byte-Sequenz ein U+FFFE zu sein scheint, müssen die Bytes beim Dekodieren vertauscht werden. Leider hatte das Zeichen U+FEFF eine zweite Funktion als ZERO WIDTH NO-BREAK SPACE: ein Zeichen ohne Breite, das kein Wortumbruch erlaubt. Es kann z.B. verwendet werden, um einem Ligaturen-Algorithmus Hinweise zu geben. Mit Unicode 4.0 wurde die Verwendung von U+FEFF als ZERO WIDTH NO-BREAK SPACE als veraltet erklärt (mit U+2060 (WORD JOINER) übernimmt diese Rolle). Trotzdem muss Unicode-Software U+FEFF in beiden Rollen handhaben können: als BOM ist es ein Mittel zur Bestimmung des Speicherlayouts der kodierten Bytes und verschwindet, sobald die Byte-Sequenz in einen String dekodiert wurde; als ZERO WIDTH NO-BREAK SPACE ist es ein normales Zeichen, das wie jedes andere dekodiert wird.

Es gibt eine weitere Kodierung, die den gesamten Bereich von Unicode-Zeichen kodieren kann: UTF-8. UTF-8 ist eine 8-Bit-Kodierung, was bedeutet, dass es keine Probleme mit der Byte-Reihenfolge bei UTF-8 gibt. Jedes Byte in einer UTF-8-Byte-Sequenz besteht aus zwei Teilen: Markierungsbits (die höchstwertigen Bits) und Nutzdatenbits. Die Markierungsbits sind eine Folge von null bis vier 1-Bits, gefolgt von einem 0-Bit. Unicode-Zeichen werden wie folgt kodiert (wobei x Nutzdatenbits sind, die bei Verkettung das Unicode-Zeichen ergeben)

Bereich	Kodierung
U-00000000 … U-0000007F	0xxxxxxx
U-00000080 … U-000007FF	110xxxxx 10xxxxxx
U-00000800 … U-0000FFFF	1110xxxx 10xxxxxx 10xxxxxx
U-00010000 … U-0010FFFF	11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

Das niederwertigste Bit des Unicode-Zeichens ist das rechteste x-Bit.

Da UTF-8 eine 8-Bit-Kodierung ist, wird keine BOM benötigt, und jedes U+FEFF-Zeichen in der dekodierten Zeichenkette (auch wenn es das erste Zeichen ist) wird als ZERO WIDTH NO-BREAK SPACE behandelt.

Ohne externe Informationen ist es unmöglich, zuverlässig festzustellen, welche Kodierung zum Kodieren eines Strings verwendet wurde. Jede Charmap-Kodierung kann beliebige Byte-Sequenzen dekodieren. Das ist jedoch mit UTF-8 nicht möglich, da UTF-8-Byte-Sequenzen eine Struktur haben, die keine beliebigen Byte-Sequenzen zulässt. Um die Zuverlässigkeit der Erkennung einer UTF-8-Kodierung zu erhöhen, hat Microsoft für sein Notepad-Programm eine Variante von UTF-8 (die Python "utf-8-sig" nennt) erfunden: Bevor eines der Unicode-Zeichen in die Datei geschrieben wird, wird eine UTF-8-kodierte BOM (die als Byte-Sequenz wie folgt aussieht: 0xef, 0xbb, 0xbf) geschrieben. Da es eher unwahrscheinlich ist, dass eine Charmap-kodierte Datei mit diesen Byte-Werten beginnt (was z.B. zu

kleiner lateinischer Buchstabe i mit diaerese

rechtszeigende doppelte Winkel-Anführungszeichen

invertiertes Fragezeichen

in iso-8859-1) abbilden würde, erhöht dies die Wahrscheinlichkeit, dass eine utf-8-sig-Kodierung korrekt aus der Byte-Sequenz erraten werden kann. Hier wird die BOM also nicht verwendet, um die zur Generierung der Byte-Sequenz verwendete Byte-Reihenfolge zu bestimmen, sondern als Signatur, die beim Erraten der Kodierung hilft. Beim Kodieren schreibt der utf-8-sig-Codec 0xef, 0xbb, 0xbf als erste drei Bytes in die Datei. Beim Dekodieren überspringt utf-8-sig diese drei Bytes, wenn sie als erste drei Bytes in der Datei erscheinen. In UTF-8 wird die Verwendung der BOM nicht empfohlen und sollte generell vermieden werden.

Standardkodierungen

Python wird mit einer Reihe von integrierten Codecs geliefert, die entweder als C-Funktionen oder mit Dictionaries als Abbildungstabellen implementiert sind. Die folgende Tabelle listet die Codecs nach Namen auf, zusammen mit einigen gängigen Aliassen und den Sprachen, für die die Kodierung wahrscheinlich verwendet wird. Weder die Liste der Aliase noch die Liste der Sprachen ist erschöpfend. Beachten Sie, dass Schreibweisen, die sich nur in Groß-/Kleinschreibung oder durch Verwendung eines Bindestrichs anstelle eines Unterstrichs unterscheiden, ebenfalls gültige Aliase sind, da sie bei der Normalisierung durch normalize_encoding() äquivalent sind. Zum Beispiel ist 'utf-8' ein gültiger Alias für den 'utf_8'-Codec.

Hinweis

Die folgende Tabelle listet die gebräuchlichsten Aliase auf. Für eine vollständige Liste siehe die Quelldatei aliases.py.

Unter Windows sind cpXXX-Codecs für alle Codepages verfügbar. Nur die in der folgenden Tabelle aufgeführten Codecs sind auf anderen Plattformen garantiert vorhanden.

CPython-Implementierungsdetail: Einige gängige Kodierungen können die Codec-Lookup-Mechanismen umgehen, um die Leistung zu verbessern. Diese Optimierungsmöglichkeiten werden von CPython nur für eine begrenzte Anzahl von (nicht-case-sensitiven) Aliassen erkannt: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (nur Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32 und dieselben mit Unterstrichen anstelle von Bindestrichen. Die Verwendung alternativer Aliase für diese Kodierungen kann zu einer langsameren Ausführung führen.

Geändert in Version 3.6: Optimierungsmöglichkeit für us-ascii erkannt.

Viele der Zeichensätze unterstützen dieselben Sprachen. Sie unterscheiden sich in einzelnen Zeichen (z.B. ob das EURO-ZEICHEN unterstützt wird oder nicht) und in der Zuordnung von Zeichen zu Codepositionen. Für die europäischen Sprachen im Besonderen existieren typischerweise folgende Varianten

• ein ISO 8859-Zeichensatz

• eine Microsoft Windows-Codepage, die typischerweise von einem 8859-Zeichensatz abgeleitet ist, aber Steuerzeichen durch zusätzliche grafische Zeichen ersetzt

• eine IBM EBCDIC-Codepage

• eine IBM PC-Codepage, die ASCII-kompatibel ist

Codec	Aliase	Sprachen
ascii	646, us-ascii	Englisch
big5	big5-tw, csbig5	Traditionelles Chinesisch
big5hkscs	big5-hkscs, hkscs	Traditionelles Chinesisch
cp037	IBM037, IBM039	Englisch
cp273	273, IBM273, csIBM273	Deutsch Hinzugefügt in Version 3.4.
cp424	EBCDIC-CP-HE, IBM424	Hebräisch
cp437	437, IBM437	Englisch
cp500	EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500	Westeuropa
cp720		Arabisch
cp737		Griechisch
cp775	IBM775	Baltische Sprachen
cp850	850, IBM850	Westeuropa
cp852	852, IBM852	Mittel- und Osteuropa
cp855	855, IBM855	Belarussisch, Bulgarisch, Mazedonisch, Russisch, Serbisch
cp856		Hebräisch
cp857	857, IBM857	Türkisch
cp858	858, IBM858	Westeuropa
cp860	860, IBM860	Portugiesisch
cp861	861, CP-IS, IBM861	Isländisch
cp862	862, IBM862	Hebräisch
cp863	863, IBM863	Kanadisch
cp864	IBM864	Arabisch
cp865	865, IBM865	Dänisch, Norwegisch
cp866	866, IBM866	Russisch
cp869	869, CP-GR, IBM869	Griechisch
cp874		Thai
cp875		Griechisch
cp932	932, ms932, mskanji, ms-kanji, windows-31j	Japanisch
cp949	949, ms949, uhc	Koreanisch
cp950	950, ms950	Traditionelles Chinesisch
cp1006		Urdu
cp1026	ibm1026	Türkisch
cp1125	1125, ibm1125, cp866u, ruscii	Ukrainisch Hinzugefügt in Version 3.4.
cp1140	ibm1140	Westeuropa
cp1250	windows-1250	Mittel- und Osteuropa
cp1251	windows-1251	Belarussisch, Bulgarisch, Mazedonisch, Russisch, Serbisch
cp1252	windows-1252	Westeuropa
cp1253	windows-1253	Griechisch
cp1254	windows-1254	Türkisch
cp1255	windows-1255	Hebräisch
cp1256	windows-1256	Arabisch
cp1257	windows-1257	Baltische Sprachen
cp1258	windows-1258	Vietnamesisch
euc_jp	eucjp, ujis, u-jis	Japanisch
euc_jis_2004	jisx0213, eucjis2004	Japanisch
euc_jisx0213	eucjisx0213	Japanisch
euc_kr	euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001	Koreanisch
gb2312	chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58	Vereinfachtes Chinesisch
gbk	936, cp936, ms936	Vereinfachtes Chinesisch
gb18030	gb18030-2000	Vereinfachtes Chinesisch
hz	hzgb, hz-gb, hz-gb-2312	Vereinfachtes Chinesisch
iso2022_jp	csiso2022jp, iso2022jp, iso-2022-jp	Japanisch
iso2022_jp_1	iso2022jp-1, iso-2022-jp-1	Japanisch
iso2022_jp_2	iso2022jp-2, iso-2022-jp-2	Japanisch, Koreanisch, Vereinfachtes Chinesisch, Westeuropa, Griechisch
iso2022_jp_2004	iso2022jp-2004, iso-2022-jp-2004	Japanisch
iso2022_jp_3	iso2022jp-3, iso-2022-jp-3	Japanisch
iso2022_jp_ext	iso2022jp-ext, iso-2022-jp-ext	Japanisch
iso2022_kr	csiso2022kr, iso2022kr, iso-2022-kr	Koreanisch
latin_1	iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1	Westeuropa
iso8859_2	iso-8859-2, latin2, L2	Mittel- und Osteuropa
iso8859_3	iso-8859-3, latin3, L3	Esperanto, Maltesisch
iso8859_4	iso-8859-4, latin4, L4	Nordeuropa
iso8859_5	iso-8859-5, kyrillisch	Belarussisch, Bulgarisch, Mazedonisch, Russisch, Serbisch
iso8859_6	iso-8859-6, arabisch	Arabisch
iso8859_7	iso-8859-7, griechisch, greek8	Griechisch
iso8859_8	iso-8859-8, hebräisch	Hebräisch
iso8859_9	iso-8859-9, latin5, L5	Türkisch
iso8859_10	iso-8859-10, latin6, L6	Nordische Sprachen
iso8859_11	iso-8859-11, Thai	Thai-Sprachen
iso8859_13	iso-8859-13, latin7, L7	Baltische Sprachen
iso8859_14	iso-8859-14, latin8, L8	Keltische Sprachen
iso8859_15	iso-8859-15, latin9, L9	Westeuropa
iso8859_16	iso-8859-16, latin10, L10	Südosteuropa
johab	cp1361, ms1361	Koreanisch
koi8_r		Russisch
koi8_t		Tadschikisch Hinzugefügt in Version 3.5.
koi8_u		Ukrainisch
kz1048	kz_1048, strk1048_2002, rk1048	Kasachisch Hinzugefügt in Version 3.5.
mac_cyrillic	maccyrillic	Belarussisch, Bulgarisch, Mazedonisch, Russisch, Serbisch
mac_greek	macgreek	Griechisch
mac_iceland	maciceland	Isländisch
mac_latin2	maclatin2, maccentraleurope, mac_centeuro	Mittel- und Osteuropa
mac_roman	macroman, macintosh	Westeuropa
mac_turkish	macturkish	Türkisch
ptcp154	csptcp154, pt154, cp154, cyrillic-asian	Kasachisch
shift_jis	csshiftjis, shiftjis, sjis, s_jis	Japanisch
shift_jis_2004	shiftjis2004, sjis_2004, sjis2004	Japanisch
shift_jisx0213	shiftjisx0213, sjisx0213, s_jisx0213	Japanisch
utf_32	U32, utf32	alle Sprachen
utf_32_be	UTF-32BE	alle Sprachen
utf_32_le	UTF-32LE	alle Sprachen
utf_16	U16, utf16	alle Sprachen
utf_16_be	UTF-16BE	alle Sprachen
utf_16_le	UTF-16LE	alle Sprachen
utf_7	U7, unicode-1-1-utf-7	alle Sprachen
utf_8	U8, UTF, utf8, cp65001	alle Sprachen
utf_8_sig		alle Sprachen

Geändert in Version 3.4: Die Encoder utf-16* und utf-32* erlauben keine Kodierung von Ersatzcode-Punkten (U+D800–U+DFFF) mehr. Die Decoder utf-32* dekodieren keine Byte-Sequenzen mehr, die Ersatzcode-Punkten entsprechen.

Geändert in Version 3.8: cp65001 ist nun ein Alias für utf_8.

Geändert in Version 3.14: Unter Windows sind cpXXX-Codecs für alle Codepages verfügbar.

Python-spezifische Kodierungen

Eine Reihe von vordefinierten Codecs sind Python-spezifisch, sodass ihre Codec-Namen außerhalb von Python keine Bedeutung haben. Diese sind in den folgenden Tabellen nach den erwarteten Eingabe- und Ausgabetypen aufgelistet (beachten Sie, dass Textkodierungen der häufigste Anwendungsfall für Codecs sind, die zugrundeliegende Codec-Infrastruktur jedoch beliebige Datentransformationen unterstützt, nicht nur Textkodierungen). Für asymmetrische Codecs beschreibt die angegebene Bedeutung die Kodierungsrichtung.

Textkodierungen

Die folgenden Codecs bieten eine Kodierung von str zu bytes und eine Dekodierung von bytes-ähnlichem Objekt zu str, ähnlich wie bei Unicode-Textkodierungen.

Codec	Aliase	Bedeutung
idna		Implementiert RFC 3490, siehe auch encodings.idna. Nur errors='strict' wird unterstützt.
mbcs	ansi, dbcs	Nur Windows: Kodiert den Operanden gemäß der ANSI-Codepage (CP_ACP).
oem		Nur Windows: Kodiert den Operanden gemäß der OEM-Codepage (CP_OEMCP). Hinzugefügt in Version 3.6.
palmos		Kodierung von PalmOS 3.5.
punycode		Implementiert RFC 3492. Zustandsbehaftete Codecs werden nicht unterstützt.
raw_unicode_escape		Latin-1-Kodierung mit \uXXXX und \UXXXXXXXX für andere Code-Punkte. Vorhandene Backslashes werden in keiner Weise maskiert. Es wird im Python-Pickle-Protokoll verwendet.
undefined		Dieser Codec sollte nur zu Testzwecken verwendet werden. Löst für alle Konvertierungen eine Ausnahme aus, auch für leere Strings. Der Fehlerbehandler wird ignoriert.
unicode_escape		Eine Kodierung, die als Inhalt eines Unicode-Literals im ASCII-kodierten Python-Quellcode geeignet ist, mit der Ausnahme, dass Anführungszeichen nicht maskiert werden. Dekodiert aus Latin-1-Quellcode. Beachten Sie, dass Python-Quellcode standardmäßig UTF-8 verwendet.

Geändert in Version 3.8: Der Codec "unicode_internal" wurde entfernt.

Binäre Transformationen

Die folgenden Codecs bieten binäre Transformationen: bytes-ähnliches Objekt zu bytes-Abbildungen. Sie werden nicht von bytes.decode() unterstützt (welches nur str-Ausgabe erzeugt).

Codec	Aliase	Bedeutung	Encoder / Decoder
base64_codec [1]	base64, base_64	Konvertiert das Operanden in mehrzeiliges MIME-Base64 (das Ergebnis enthält immer ein nachgestelltes '\n'). Geändert in Version 3.4: Akzeptiert jedes bytes-ähnliche Objekt als Eingabe für Kodierung und Dekodierung.	base64.encodebytes() / base64.decodebytes()
bz2_codec	bz2	Komprimiert den Operanden mit bz2.	bz2.compress() / bz2.decompress()
hex_codec	hex	Konvertiert den Operanden in eine hexadezimale Darstellung mit zwei Ziffern pro Byte.	binascii.b2a_hex() / binascii.a2b_hex()
quopri_codec	quopri, quotedprintable, quoted_printable	Konvertiert den Operanden in MIME quoted-printable.	quopri.encode() mit quotetabs=True / quopri.decode()
uu_codec	uu	Konvertiert den Operanden mittels uuencode.
zlib_codec	zip, zlib	Komprimiert den Operanden mit gzip.	zlib.compress() / zlib.decompress()

[1]

Neben bytes-ähnlichen Objekten akzeptiert 'base64_codec' auch reine ASCII-Instanzen von str zur Dekodierung.

Hinzugefügt in Version 3.2: Wiederherstellung der binären Transformationen.

Geändert in Version 3.4: Wiederherstellung der Aliase für die binären Transformationen.

Standalone Codec-Funktionen

Die folgenden Funktionen bieten Kodierungs- und Dekodierungsfunktionalität, die Codecs ähnelt, sind aber nicht als benannte Codecs über codecs.encode() oder codecs.decode() verfügbar. Sie werden intern verwendet (z.B. von pickle) und verhalten sich ähnlich wie der in Python 3 entfernte string_escape-Codec.

codecs.escape_encode(input, errors=None)

Kodiert input mittels Escape-Sequenzen. Ähnlich wie repr() auf Bytes escaped Byte-Werte erzeugt.

input muss ein bytes-Objekt sein.

Gibt ein Tupel (output, length) zurück, wobei output ein bytes-Objekt und length die Anzahl der verbrauchten Bytes ist.

codecs.escape_decode(input, errors=None)

Dekodiert input von Escape-Sequenzen zurück zu den ursprünglichen Bytes.

input muss ein bytes-ähnliches Objekt sein.

Gibt ein Tupel (output, length) zurück, wobei output ein bytes-Objekt und length die Anzahl der verbrauchten Bytes ist.

Text-Transformationen

Der folgende Codec bietet eine Text-Transformation: eine str zu str-Abbildung. Sie wird nicht von str.encode() unterstützt (welches nur bytes-Ausgabe erzeugt).

Codec	Aliase	Bedeutung
rot_13	rot13	Gibt die Caesar-Chiffre-Verschlüsselung des Operanden zurück.

Hinzugefügt in Version 3.2: Wiederherstellung der rot_13 Text-Transformation.

Geändert in Version 3.4: Wiederherstellung des rot13-Alias.

encodings — Encodings-Paket

Dieses Modul implementiert die folgenden Funktionen

encodings.normalize_encoding(encoding)

Normalisiert den Encoding-Namen encoding.

Die Normalisierung funktioniert wie folgt: Alle nicht-alphanumerischen Zeichen außer dem Punkt, der für Python-Paketnamen verwendet wird, werden zusammengefasst und durch einen einzelnen Unterstrich ersetzt, führende und nachgestellte Unterstriche werden entfernt. Zum Beispiel wird '  -;#' zu '_'.

Beachten Sie, dass encoding nur ASCII enthalten darf.

Hinweis

Die folgenden Funktionen sollten nicht direkt verwendet werden, außer zu Testzwecken; stattdessen sollte codecs.lookup() verwendet werden.

encodings.search_function(encoding)

Sucht nach dem Codec-Modul, das dem angegebenen Encoding-Namen encoding entspricht.

Diese Funktion normalisiert zuerst encoding mit normalize_encoding(), sucht dann nach einem entsprechenden Alias. Sie versucht, ein Codec-Modul aus dem encodings-Paket entweder unter dem Alias oder unter dem normalisierten Namen zu importieren. Wenn das Modul gefunden wird und eine gültige getregentry()-Funktion definiert, die ein codecs.CodecInfo-Objekt zurückgibt, wird der Codec zwischengespeichert und zurückgegeben.

Wenn das Codec-Modul eine getaliases()-Funktion definiert, werden alle zurückgegebenen Aliase für zukünftige Verwendung registriert.

encodings.win32_code_page_search_function(encoding)

Sucht nach einer Windows-Codepage-Kodierung encoding der Form cpXXXX.

Wenn die Codepage gültig und unterstützt ist, wird ein codecs.CodecInfo-Objekt dafür zurückgegeben.

Verfügbarkeit: Windows.

Hinzugefügt in Version 3.14.

Dieses Modul implementiert die folgende Ausnahme

exception encodings.CodecRegistryError

Wird ausgelöst, wenn ein Codec ungültig oder inkompatibel ist.

encodings.idna — Internationalisierte Domainnamen in Anwendungen

Dieses Modul implementiert RFC 3490 (Internationalized Domain Names in Applications) und RFC 3492 (Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)). Es baut auf der punycode-Kodierung und stringprep auf.

Wenn Sie den IDNA 2008-Standard aus RFC 5891 und RFC 5895 benötigen, verwenden Sie das Drittanbieter-Modul idna.

Diese RFCs definieren zusammen ein Protokoll zur Unterstützung von Nicht-ASCII-Zeichen in Domainnamen. Ein Domainname, der Nicht-ASCII-Zeichen enthält (wie z.B. www.Alliancefrançaise.nu), wird in eine ASCII-kompatible Kodierung (ACE, z.B. www.xn--alliancefranaise-npb.nu) konvertiert. Die ACE-Form des Domainnamens wird dann an allen Stellen verwendet, an denen das Protokoll keine beliebigen Zeichen zulässt, wie z.B. bei DNS-Abfragen, HTTP Host-Feldern usw. Diese Konvertierung erfolgt in der Anwendung; wenn möglich unsichtbar für den Benutzer: Die Anwendung sollte Unicode-Domain-Labels transparent in IDNA auf dem Draht konvertieren und ACE-Labels zurück in Unicode konvertieren, bevor sie dem Benutzer präsentiert werden.

Python unterstützt diese Konvertierung auf verschiedene Weise: der idna-Codec führt eine Konvertierung zwischen Unicode und ACE durch, trennt eine Eingabezeichenkette anhand der in Abschnitt 3.1 von RFC 3490 definierten Trennzeichen in Labels und konvertiert jedes Label wie erforderlich in ACE, und umgekehrt trennt er eine Eingabe-Byte-Zeichenkette anhand des Trennzeichens . in Labels und konvertiert gefundene ACE-Labels in Unicode. Darüber hinaus konvertiert das Modul socket Unicode-Hostnamen transparent in ACE, sodass Anwendungen sich keine Gedanken über die Konvertierung von Hostnamen machen müssen, wenn sie diese an das Socket-Modul übergeben. Darüber hinaus akzeptieren Module, die Hostnamen als Funktionsparameter haben, wie z.B. http.client und ftplib, Unicode-Hostnamen (http.client sendet dann auch transparent einen IDNA-Hostnamen im Host-Feld, falls es dieses Feld überhaupt sendet).

Beim Empfang von Hostnamen aus dem Netzwerk (z.B. bei Reverse-Namensauflösungen) erfolgt keine automatische Konvertierung in Unicode: Anwendungen, die solche Hostnamen dem Benutzer präsentieren möchten, sollten sie in Unicode dekodieren.

Das Modul encodings.idna implementiert auch das Nameprep-Verfahren, das bestimmte Normalisierungen an Hostnamen durchführt, um die Groß-/Kleinschreibungsunabhängigkeit von internationalen Domainnamen zu erreichen und ähnliche Zeichen zu vereinheitlichen. Die Nameprep-Funktionen können bei Bedarf direkt verwendet werden.

encodings.idna.nameprep(label)

Gibt die namensvorbereitete Version von label zurück. Die Implementierung geht derzeit von Abfrage-Strings aus, daher ist AllowUnassigned true.

encodings.idna.ToASCII(label)

Konvertiert ein Label in ASCII, wie in RFC 3490 beschrieben. UseSTD3ASCIIRules wird als false angenommen.

encodings.idna.ToUnicode(label)

Konvertiert ein Label in Unicode, wie in RFC 3490 beschrieben.

encodings.mbcs — Windows ANSI Codepage

Dieses Modul implementiert die ANSI-Codepage (CP_ACP).

Verfügbarkeit: Windows.

Geändert in Version 3.2: Vor 3.2 wurde das Argument errors ignoriert; 'replace' wurde immer zum Kodieren verwendet und 'ignore' zum Dekodieren.

Geändert in Version 3.3: Unterstützt jeden Fehlerbehandler.

encodings.utf_8_sig — UTF-8-Codec mit BOM-Signatur

Dieses Modul implementiert eine Variante des UTF-8-Codecs. Beim Kodieren wird ein UTF-8-kodierter BOM vor die UTF-8-kodierten Bytes gestellt. Für den zustandsbehafteten Encoder geschieht dies nur einmal (beim ersten Schreiben in den Byte-Stream). Beim Dekodieren wird ein optionaler UTF-8-kodierter BOM am Anfang der Daten übersprungen.