email.charset: Darstellung von Zeichensätzen

Quellcode: Lib/email/charset.py

Dieses Modul ist Teil der Legacy-API (Compat32) für E-Mails. In der neuen API wird nur die Alias-Tabelle verwendet.

Der restliche Text in diesem Abschnitt ist die ursprüngliche Dokumentation des Moduls.

Dieses Modul stellt eine Klasse Charset zur Darstellung von Zeichensätzen und Zeichenkonvertierungen in E-Mail-Nachrichten bereit, sowie eine Registrierung von Zeichensätzen und mehrere Hilfsmethoden zur Manipulation dieser Registrierung. Instanzen von Charset werden in mehreren anderen Modulen innerhalb des email-Pakets verwendet.

Importieren Sie diese Klasse aus dem Modul email.charset.

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

Ordnet Zeichensätze ihren E-Mail-Eigenschaften zu.

Diese Klasse liefert Informationen über die Anforderungen, die für einen bestimmten Zeichensatz in E-Mails gelten. Sie bietet auch praktische Routinen für die Konvertierung zwischen Zeichensätzen, vorausgesetzt, die entsprechenden Codecs sind verfügbar. Gegeben einen Zeichensatz, wird sie ihr Bestes tun, um Informationen darüber zu liefern, wie dieser Zeichensatz in einer E-Mail-Nachricht RFC-konform verwendet werden kann.

Bestimmte Zeichensätze müssen mit quoted-printable oder base64 kodiert werden, wenn sie in E-Mail-Headern oder -Bodies verwendet werden. Bestimmte Zeichensätze müssen komplett konvertiert werden und sind in E-Mails nicht erlaubt.

Das optionale Argument input_charset ist wie unten beschrieben; es wird immer in Kleinbuchstaben umgewandelt. Nach der Alias-Normalisierung wird es auch als Lookup in der Registrierung von Zeichensätzen verwendet, um die Header-Kodierung, die Body-Kodierung und den Output-Konvertierungs-Codec zu ermitteln, der für den Zeichensatz verwendet werden soll. Wenn input_charset z. B. iso-8859-1 ist, werden Header und Bodies mit quoted-printable kodiert und es ist kein Output-Konvertierungs-Codec erforderlich. Wenn input_charset euc-jp ist, werden Header mit base64 kodiert, Bodies nicht kodiert, aber der Output-Text wird vom Zeichensatz euc-jp in den Zeichensatz iso-2022-jp konvertiert.

Instanzen von Charset haben die folgenden Datenattribute:

input_charset

Der anfänglich angegebene Zeichensatz. Gängige Aliase werden in ihre *offiziellen* E-Mail-Namen umgewandelt (z. B. wird latin_1 in iso-8859-1 umgewandelt). Standardmäßig 7-Bit us-ascii.

header_encoding

Wenn der Zeichensatz kodiert werden muss, bevor er in einem E-Mail-Header verwendet werden kann, wird dieses Attribut auf charset.QP (für quoted-printable), charset.BASE64 (für base64-Kodierung) oder charset.SHORTEST für die kürzeste der QP- oder BASE64-Kodierungen gesetzt. Andernfalls ist es None.

body_encoding

Wie header_encoding, beschreibt aber die Kodierung für den Body der E-Mail-Nachricht, die tatsächlich von der Header-Kodierung abweichen kann. charset.SHORTEST ist für body_encoding nicht erlaubt.

output_charset

Einige Zeichensätze müssen konvertiert werden, bevor sie in E-Mail-Headern oder -Bodies verwendet werden können. Wenn input_charset einer davon ist, enthält dieses Attribut den Namen des Zeichensatzes, zu dem der Output konvertiert wird. Andernfalls ist es None.

input_codec

Der Name des Python-Codecs, der verwendet wird, um den input_charset in Unicode zu konvertieren. Wenn kein Konvertierungs-Codec erforderlich ist, ist dieses Attribut None.

output_codec

Der Name des Python-Codecs, der verwendet wird, um Unicode in den output_charset zu konvertieren. Wenn kein Konvertierungs-Codec erforderlich ist, hat dieses Attribut denselben Wert wie input_codec.

Instanzen von Charset haben auch die folgenden Methoden:

get_body_encoding()

Gibt die für die Body-Kodierung verwendete Content-Transfer-Kodierung zurück.

Dies ist entweder der String quoted-printable oder base64, je nach verwendeter Kodierung, oder es ist eine Funktion. In diesem Fall sollten Sie die Funktion mit einem einzigen Argument aufrufen, dem Message-Objekt, das gerade kodiert wird. Die Funktion sollte dann den Header Content-Transfer-Encoding selbst auf das passende setzen.

Gibt den String quoted-printable zurück, wenn body_encoding QP ist, gibt den String base64 zurück, wenn body_encoding BASE64 ist, und gibt andernfalls den String 7bit zurück.

get_output_charset()

Gibt den Output-Zeichensatz zurück.

Dies ist das Attribut output_charset, wenn dieses nicht None ist, andernfalls ist es input_charset.

header_encode(string)

Kodiert den String string für den Header.

Die Art der Kodierung (base64 oder quoted-printable) basiert auf dem Attribut header_encoding.

header_encode_lines(string, maxlengths)

Kodiert einen string für den Header, indem er zuerst in Bytes konvertiert wird.

Dies ist ähnlich wie header_encode(), mit dem Unterschied, dass der String an die maximalen Zeilenlängen angepasst wird, die durch das Argument maxlengths angegeben sind. maxlengths muss ein Iterator sein: jedes Element, das von diesem Iterator zurückgegeben wird, liefert die nächste maximale Zeilenlänge.

body_encode(string)

Kodiert den String string für den Body.

Die Art der Kodierung (base64 oder quoted-printable) basiert auf dem Attribut body_encoding.

Die Klasse Charset bietet außerdem eine Reihe von Methoden zur Unterstützung von Standardoperationen und integrierten Funktionen.

__str__()

Gibt input_charset als String zurück, der in Kleinbuchstaben umgewandelt wurde. __repr__() ist ein Alias für __str__().

__eq__(other)

Diese Methode ermöglicht es Ihnen, zwei Instanzen von Charset auf Gleichheit zu vergleichen.

__ne__(other)

Diese Methode ermöglicht es Ihnen, zwei Instanzen von Charset auf Ungleichheit zu vergleichen.

Das Modul email.charset bietet auch die folgenden Funktionen zum Hinzufügen neuer Einträge zur globalen Registrierung von Zeichensätzen, Aliasen und Codecs:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

Fügt Zeicheneigenschaften zur globalen Registrierung hinzu.

charset ist der Eingabezeichensatz und muss der kanonische Name eines Zeichensatzes sein.

Die optionalen Argumente header_enc und body_enc sind entweder charset.QP für quoted-printable, charset.BASE64 für base64-Kodierung, charset.SHORTEST für die kürzeste der quoted-printable- oder base64-Kodierung, oder None für keine Kodierung. SHORTEST ist nur für header_enc gültig. Der Standardwert ist None für keine Kodierung.

Das optionale Argument output_charset ist der Zeichensatz, in dem der Output sein soll. Konvertierungen erfolgen vom Eingabezeichensatz über Unicode in den Ausgabezeichensatz, wenn die Methode Charset.convert() aufgerufen wird. Der Standardwert ist die Ausgabe im selben Zeichensatz wie die Eingabe.

Sowohl input_charset als auch output_charset müssen Unicode-Codec-Einträge in der Zeichenketten-zu-Codec-Zuordnung des Moduls haben; verwenden Sie add_codec(), um Codecs hinzuzufügen, die dem Modul nicht bekannt sind. Weitere Informationen finden Sie in der Dokumentation des Moduls codecs.

Die globale Zeichensatz-Registrierung wird im globalen Modul-Dictionary CHARSETS geführt.

email.charset.add_alias(alias, canonical)

Fügt einen Alias für einen Zeichensatz hinzu. alias ist der Aliasname, z. B. latin-1. canonical ist der kanonische Name des Zeichensatzes, z. B. iso-8859-1.

Die globale Zeichensatz-Alias-Registrierung wird im globalen Modul-Dictionary ALIASES geführt.

email.charset.add_codec(charset, codecname)

Fügt einen Codec hinzu, der Zeichen im angegebenen Zeichensatz nach und von Unicode abbildet.

charset ist der kanonische Name eines Zeichensatzes. codecname ist der Name eines Python-Codecs, wie er für das zweite Argument der str-Methode encode() geeignet ist.