email.header: Internationalisierte Header

Quellcode: Lib/email/header.py

Dieses Modul ist Teil der Legacy-API (Compat32) für E-Mails. In der aktuellen API wird die Kodierung und Dekodierung von Headern transparent von der dictionary-ähnlichen API der Klasse EmailMessage gehandhabt. Neben der Verwendung in Legacy-Code kann dieses Modul nützlich sein für Anwendungen, die die beim Kodieren von Headern verwendeten Zeichensätze vollständig kontrollieren müssen.

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

RFC 2822 ist der Basisstandard, der das Format von E-Mail-Nachrichten beschreibt. Er leitet sich vom älteren Standard RFC 822 ab, der weit verbreitet war, als die meisten E-Mails nur aus ASCII-Zeichen bestanden. RFC 2822 ist eine Spezifikation, die davon ausgeht, dass E-Mails nur 7-Bit-ASCII-Zeichen enthalten.

Natürlich ist E-Mail weltweit im Einsatz und wurde internationalisiert, sodass sprachspezifische Zeichensätze jetzt in E-Mail-Nachrichten verwendet werden können. Der Basisstandard verlangt weiterhin, dass E-Mail-Nachrichten nur über 7-Bit-ASCII-Zeichen übertragen werden. Daher wurde eine Reihe von RFCs geschrieben, die beschreiben, wie E-Mails, die Nicht-ASCII-Zeichen enthalten, in ein RFC 2822-konformes Format kodiert werden. Diese RFCs umfassen RFC 2045, RFC 2046, RFC 2047 und RFC 2231. Das Paket email unterstützt diese Standards in seinen Modulen email.header und email.charset.

Wenn Sie Nicht-ASCII-Zeichen in Ihre E-Mail-Header aufnehmen möchten, z. B. in den Feldern Betreff oder An, sollten Sie die Klasse Header verwenden und das Feld im Message-Objekt einer Instanz von Header zuweisen, anstatt einen String für den Headerwert zu verwenden. Importieren Sie die Klasse Header aus dem Modul email.header. Zum Beispiel

>>> from email.message import Message
>>> from email.header import Header
>>> msg = Message()
>>> h = Header('p\xf6stal', 'iso-8859-1')
>>> msg['Subject'] = h
>>> msg.as_string()
'Subject: =?iso-8859-1?q?p=F6stal?=\n\n'

Beachten Sie hier, wie wir wollten, dass das Feld Betreff ein Nicht-ASCII-Zeichen enthält? Dies haben wir durch die Erstellung einer Instanz von Header und die Übergabe des Zeichensatzes, in dem der Byte-String kodiert wurde, erreicht. Als die nachfolgende Message-Instanz abgeflacht wurde, wurde das Feld Betreff korrekt RFC 2047-kodiert. MIME-fähige Mail-Reader würden diesen Header mit dem eingebetteten ISO-8859-1-Zeichen anzeigen.

Hier ist die Beschreibung der Klasse Header

class email.header.Header(s=None, charset=None, maxlinelen=None, header_name=None, continuation_ws=' ', errors='strict')

Erstellt einen MIME-konformen Header, der Strings in verschiedenen Zeichensätzen enthalten kann.

Optional s ist der anfängliche Headerwert. Wenn None (Standard) ist, wird der anfängliche Headerwert nicht gesetzt. Sie können den Header später mit append()-Aufrufen erweitern. s kann eine Instanz von bytes oder str sein, siehe jedoch die Dokumentation zu append() für die Semantik.

Optional charset dient zwei Zwecken: Es hat die gleiche Bedeutung wie das charset-Argument für die Methode append(). Es setzt auch den Standard-Zeichensatz für alle nachfolgenden append()-Aufrufe, die das charset-Argument weglassen. Wenn charset nicht im Konstruktor angegeben ist (Standard), wird der Zeichensatz us-ascii sowohl als anfänglicher Zeichensatz für s als auch als Standard für nachfolgende append()-Aufrufe verwendet.

Die maximale Zeilenlänge kann explizit über maxlinelen angegeben werden. Um die erste Zeile auf einen kürzeren Wert zu kürzen (um den Feld-Header zu berücksichtigen, der nicht in s enthalten ist, z. B. Betreff), übergeben Sie den Namen des Feldes in header_name. Der Standardwert für maxlinelen ist 78 und der Standardwert für header_name ist None, was bedeutet, dass er für die erste Zeile eines langen, geteilten Headers nicht berücksichtigt wird.

Optional continuation_ws muss ein RFC 2822-konformes Faltungsleerzeichen sein und ist normalerweise entweder ein Leerzeichen oder ein Tabulatorzeichen. Dieses Zeichen wird Zeilenumbrüchen vorangestellt. continuation_ws ist standardmäßig ein einzelnes Leerzeichen.

Optional errors wird direkt an die Methode append() weitergegeben.

append(s, charset=None, errors='strict')

Fügt den String s zum MIME-Header hinzu.

Optional charset sollte, wenn angegeben, eine Charset-Instanz sein (siehe email.charset) oder der Name eines Zeichensatzes, der in eine Charset-Instanz konvertiert wird. Ein Wert von None (Standard) bedeutet, dass der im Konstruktor angegebene charset verwendet wird.

s kann eine Instanz von bytes oder str sein. Wenn es sich um eine Instanz von bytes handelt, dann ist charset die Kodierung dieses Byte-Strings, und ein UnicodeError wird ausgelöst, wenn der String mit diesem Zeichensatz nicht dekodiert werden kann.

Wenn s eine Instanz von str ist, dann ist charset ein Hinweis auf den Zeichensatz der Zeichen im String.

In beiden Fällen wird beim Erzeugen eines RFC 2822-konformen Headers unter Verwendung der RFC 2047-Regeln der String mit dem Ausgabe-Codec des Zeichensatzes kodiert. Wenn der String mit dem Ausgabe-Codec nicht kodiert werden kann, wird ein UnicodeError ausgelöst.

Optional errors wird als Argument `errors` für den `decode`-Aufruf übergeben, wenn s ein Byte-String ist.

encode(splitchars=';, \t', maxlinelen=None, linesep='\n')

Kodiert einen Nachrichtenheader in ein RFC-konformes Format, wobei lange Zeilen möglicherweise umgebrochen und Nicht-ASCII-Teile in Base64- oder Quoted-Printable-Kodierungen gekapselt werden.

Optional splitchars ist ein String, der Zeichen enthält, die vom Algorithmus zur Zeilenaufteilung während der normalen Header-Aufteilung besonders berücksichtigt werden sollen. Dies dient einer sehr groben Unterstützung der „höheren syntaktischen Pausen“ von RFC 2822: An Trennzeichen angehängte Aufteilungspunkte werden bei der Zeilenaufteilung bevorzugt, wobei die Zeichen in der Reihenfolge bevorzugt werden, in der sie in der Zeile erscheinen. Leerzeichen und Tabulator können in den String aufgenommen werden, um anzuzeigen, ob einem gegenüber dem anderen als Aufteilungspunkt Vorrang eingeräumt werden soll, wenn andere Trennzeichen nicht in der zu teilenden Zeile vorkommen. Splitchars hat keinen Einfluss auf RFC 2047-kodierte Zeilen.

maxlinelen überschreibt, wenn angegeben, den Wert der maximalen Zeilenlänge der Instanz.

linesep gibt die Zeichen an, die zur Trennung der Zeilen des gefalteten Headers verwendet werden. Standardmäßig ist dies der nützlichste Wert für Python-Anwendungscode (\n), aber \r\n kann angegeben werden, um Header mit RFC-konformen Zeilentrennzeichen zu erzeugen.

Geändert in Version 3.2: Das Argument linesep wurde hinzugefügt.

Die Klasse Header bietet auch eine Reihe von Methoden zur Unterstützung von Standardoperatoren und integrierten Funktionen.

__str__()

Gibt eine Annäherung des Header als String zurück, mit unbegrenzter Zeilenlänge. Alle Teile werden mithilfe der angegebenen Kodierung in Unicode konvertiert und entsprechend zusammengefügt. Teile mit einem Zeichensatz von 'unknown-8bit' werden als ASCII unter Verwendung des Fehlerbehandlers 'replace' dekodiert.

Geändert in Version 3.2: Die Handhabung des Zeichensatzes 'unknown-8bit' wurde hinzugefügt.

__eq__(other)

Diese Methode ermöglicht den Vergleich zweier Header-Instanzen auf Gleichheit.

__ne__(other)

Diese Methode ermöglicht den Vergleich zweier Header-Instanzen auf Ungleichheit.

Das Modul email.header bietet auch die folgenden praktischen Funktionen.

email.header.decode_header(header)

Dekodiert einen Nachrichtenheaderwert, ohne den Zeichensatz zu konvertieren. Der Headerwert befindet sich in header.

Aus historischen Gründen kann diese Funktion entweder

  1. Eine Liste von Paaren zurückgeben, die jeden der dekodierten Teile des Headers enthält, (decoded_bytes, charset), wobei decoded_bytes immer eine Instanz von bytes ist und charset entweder

    • Ein Kleinbuchstaben-String ist, der den Namen des angegebenen Zeichensatzes enthält.

    • None für nicht kodierte Teile des Headers.

  2. Eine Liste der Länge 1 mit einem Paar (string, None), wobei string immer eine Instanz von str ist.

Ein email.errors.HeaderParseError kann ausgelöst werden, wenn bestimmte Dekodierungsfehler auftreten (z. B. eine Base64-Dekodierungs-Exception).

Hier sind Beispiele

>>> from email.header import decode_header
>>> decode_header('=?iso-8859-1?q?p=F6stal?=')
[(b'p\xf6stal', 'iso-8859-1')]
>>> decode_header('unencoded_string')
[('unencoded_string', None)]
>>> decode_header('bar =?utf-8?B?ZsOzbw==?=')
[(b'bar ', None), (b'f\xc3\xb3o', 'utf-8')]

Hinweis

Diese Funktion existiert nur zur Rückwärtskompatibilität. Für neuen Code empfehlen wir die Verwendung von email.headerregistry.HeaderRegistry.

email.header.make_header(decoded_seq, maxlinelen=None, header_name=None, continuation_ws=' ')

Erstellt eine Header-Instanz aus einer Sequenz von Paaren, wie sie von decode_header() zurückgegeben wird.

decode_header() nimmt einen Headerwert-String und gibt eine Sequenz von Paaren im Format (decoded_string, charset) zurück, wobei charset der Name des Zeichensatzes ist.

Diese Funktion nimmt eine dieser Paarsequenzen und gibt eine Header-Instanz zurück. Optionale Parameter maxlinelen, header_name und continuation_ws sind wie im Konstruktor von Header.

Hinweis

Diese Funktion existiert nur zur Rückwärtskompatibilität und wird für neue Codes nicht empfohlen.