email.message.Message: Repräsentation einer E-Mail-Nachricht mit der compat32 API

Die Klasse Message ist der Klasse EmailMessage sehr ähnlich, jedoch ohne die von letzterer hinzugefügten Methoden und mit leicht abweichendem Standardverhalten für bestimmte andere Methoden. Wir dokumentieren hier auch einige Methoden, die zwar von der Klasse EmailMessage unterstützt werden, aber nur dann empfohlen werden, wenn Sie mit Legacy-Code arbeiten.

Die Philosophie und Struktur der beiden Klassen ist ansonsten gleich.

Dieses Dokument beschreibt das Verhalten unter der Standardrichtlinie (für Message) Compat32. Wenn Sie eine andere Richtlinie verwenden möchten, sollten Sie stattdessen die Klasse EmailMessage verwenden.

Eine E-Mail-Nachricht besteht aus Headern und einer Payload. Header müssen Namen und Werte im Stil von RFC 5322 sein, wobei Feldname und Wert durch einen Doppelpunkt getrennt sind. Der Doppelpunkt ist weder Teil des Feldnamens noch des Feldwerts. Die Payload kann eine einfache Textnachricht, ein Binärobjekt oder eine strukturierte Sequenz von Unter-Nachrichten sein, jede mit ihren eigenen Headern und ihrer eigenen Payload. Letzterer Typ von Payload wird dadurch angezeigt, dass die Nachricht einen MIME-Typ wie multipart/* oder message/rfc822 hat.

Das von einem Message-Objekt bereitgestellte konzeptionelle Modell ist das eines geordneten Wörterbuchs von Headern mit zusätzlichen Methoden für den Zugriff auf spezialisierte Informationen aus den Headern, für den Zugriff auf die Payload, für die Generierung einer serialisierten Version der Nachricht und für das rekursive Durchlaufen des Objektbaums. Beachten Sie, dass doppelte Header unterstützt werden, aber spezielle Methoden verwendet werden müssen, um auf sie zuzugreifen.

Das Message-Pseudo-Wörterbuch wird von den Headernamen indiziert, die ASCII-Werte sein müssen. Die Werte des Wörterbuchs sind Zeichenfolgen, die nur ASCII-Zeichen enthalten sollen; es gibt eine spezielle Handhabung für Nicht-ASCII-Eingaben, die jedoch nicht immer die richtigen Ergebnisse liefert. Header werden in Groß- und Kleinschreibung erhaltener Form gespeichert und zurückgegeben, Feldnamen werden jedoch ohne Berücksichtigung der Groß- und Kleinschreibung abgeglichen. Es kann auch einen einzelnen Umschlag-Header geben, der auch als Unix-From-Header oder From_-Header bezeichnet wird. Die Payload ist entweder eine Zeichenkette oder Bytes im Falle einfacher Nachrichtenobjekte oder eine Liste von Message-Objekten für MIME-Containerdokumente (z. B. multipart/* und message/rfc822).

Hier sind die Methoden der Klasse Message

class email.message.Message(policy=compat32)

Wenn policy angegeben ist (es muss eine Instanz einer Klasse aus email.policy sein), werden die von ihr spezifizierten Regeln verwendet, um die Darstellung der Nachricht zu aktualisieren und zu serialisieren. Wenn policy nicht gesetzt ist, wird die compat32-Richtlinie verwendet, die die Abwärtskompatibilität mit der Python 3.2-Version des E-Mail-Pakets aufrechterhält. Weitere Informationen finden Sie in der Dokumentation zu policy.

Geändert in Version 3.3: Das Schlüsselwortargument policy wurde hinzugefügt.

as_string(unixfrom=False, maxheaderlen=0, policy=None)

Gibt die gesamte Nachricht als Zeichenkette zurück. Wenn das optionale unixfrom True ist, wird der Umschlag-Header in die zurückgegebene Zeichenkette aufgenommen. unixfrom ist standardmäßig False. Aus Gründen der Abwärtskompatibilität ist maxheaderlen standardmäßig 0. Wenn Sie also einen anderen Wert wünschen, müssen Sie ihn explizit überschreiben (der für max_line_length in der Richtlinie angegebene Wert wird von dieser Methode ignoriert). Das Argument policy kann verwendet werden, um die Standardrichtlinie der Nachrichteninstanz zu überschreiben. Dies kann verwendet werden, um die von der Methode erzeugte Formatierung zu steuern, da die angegebene policy an den Generator weitergegeben wird.

Das Abflachen der Nachricht kann zu Änderungen an der Message führen, wenn Standardwerte aufgefüllt werden müssen, um die Transformation in eine Zeichenkette abzuschließen (z. B. können MIME-Grenzen generiert oder geändert werden).

Beachten Sie, dass diese Methode als Komfortfunktion bereitgestellt wird und die Nachricht möglicherweise nicht immer wie gewünscht formatiert. Sie erledigt beispielsweise standardmäßig nicht die Behandlung von Zeilen, die mit From beginnen und für das Unix-Mbox-Format erforderlich sind. Für mehr Flexibilität instanziieren Sie eine Generator-Instanz und verwenden Sie deren flatten()-Methode direkt. Zum Beispiel

from io import StringIO
from email.generator import Generator
fp = StringIO()
g = Generator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Wenn das Nachrichtenobjekt Binärdaten enthält, die nicht gemäß RFC-Standards codiert sind, werden die nicht konformen Daten durch Unicode-"Unbekannte Zeichen"-Codepunkte ersetzt. (Siehe auch as_bytes() und BytesGenerator.)

Geändert in Version 3.4: Das Schlüsselwortargument policy wurde hinzugefügt.

__str__()

Entspricht as_string(). Ermöglicht, dass str(msg) eine Zeichenkette mit der formatierten Nachricht erzeugt.

as_bytes(unixfrom=False, policy=None)

Gibt die gesamte Nachricht als Bytes-Objekt zurück. Wenn das optionale unixfrom True ist, wird der Umschlag-Header in die zurückgegebene Zeichenkette aufgenommen. unixfrom ist standardmäßig False. Das Argument policy kann verwendet werden, um die Standardrichtlinie der Nachrichteninstanz zu überschreiben. Dies kann verwendet werden, um die von der Methode erzeugte Formatierung zu steuern, da die angegebene policy an den BytesGenerator weitergegeben wird.

Das Abflachen der Nachricht kann zu Änderungen an der Message führen, wenn Standardwerte aufgefüllt werden müssen, um die Transformation in eine Zeichenkette abzuschließen (z. B. können MIME-Grenzen generiert oder geändert werden).

Beachten Sie, dass diese Methode als Komfortfunktion bereitgestellt wird und die Nachricht möglicherweise nicht immer wie gewünscht formatiert. Sie erledigt beispielsweise standardmäßig nicht die Behandlung von Zeilen, die mit From beginnen und für das Unix-Mbox-Format erforderlich sind. Für mehr Flexibilität instanziieren Sie eine BytesGenerator-Instanz und verwenden Sie deren flatten()-Methode direkt. Zum Beispiel

from io import BytesIO
from email.generator import BytesGenerator
fp = BytesIO()
g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60)
g.flatten(msg)
text = fp.getvalue()

Hinzugefügt in Version 3.4.

__bytes__()

Entspricht as_bytes(). Ermöglicht, dass bytes(msg) ein Bytes-Objekt mit der formatierten Nachricht erzeugt.

Hinzugefügt in Version 3.4.

is_multipart()

Gibt True zurück, wenn die Payload der Nachricht eine Liste von Sub-Message-Objekten ist, andernfalls False. Wenn is_multipart() False zurückgibt, sollte die Payload ein Zeichenkettenobjekt sein (was eine CTE-codierte binäre Payload sein könnte). (Beachten Sie, dass is_multipart() nicht unbedingt True zurückgibt, nur weil „msg.get_content_maintype() == ‘multipart'“ True ist. Zum Beispiel gibt is_multipart True zurück, wenn die Message vom Typ message/rfc822 ist.)

set_unixfrom(unixfrom)

Setzt den Umschlag-Header der Nachricht auf unixfrom, was eine Zeichenkette sein sollte.

get_unixfrom()

Gibt den Umschlag-Header der Nachricht zurück. Standardmäßig None, wenn der Umschlag-Header nie gesetzt wurde.

attach(payload)

Fügt die gegebene payload zur aktuellen Payload hinzu, die vor dem Aufruf None oder eine Liste von Message-Objekten sein muss. Nach dem Aufruf ist die Payload immer eine Liste von Message-Objekten. Wenn Sie die Payload auf ein Skalarobjekt (z. B. eine Zeichenkette) setzen möchten, verwenden Sie stattdessen set_payload().

Dies ist eine Legacy-Methode. Auf der Klasse EmailMessage wird ihre Funktionalität durch set_content() und die zugehörigen Methoden make und add ersetzt.

get_payload(i=None, decode=False)

Gibt die aktuelle Payload zurück, die eine Liste von Message-Objekten ist, wenn is_multipart() True ist, oder eine Zeichenkette, wenn is_multipart() False ist. Wenn die Payload eine Liste ist und Sie das Listenobjekt verändern, verändern Sie die Payload der Nachricht direkt.

Mit dem optionalen Argument i gibt get_payload() das i-te Element der Payload zurück, beginnend bei Null, wenn is_multipart() True ist. Ein IndexError wird ausgelöst, wenn i kleiner als 0 oder größer oder gleich der Anzahl der Elemente in der Payload ist. Wenn die Payload eine Zeichenkette ist (d. h. is_multipart() False ist) und i angegeben ist, wird ein TypeError ausgelöst.

Optionales decode ist ein Flag, das angibt, ob die Payload gemäß dem Content-Transfer-Encoding-Header dekodiert werden soll. Wenn True ist und die Nachricht keine Multipart ist, wird die Payload dekodiert, wenn der Wert dieses Headers quoted-printable oder base64 ist. Wenn eine andere Codierung verwendet wird oder der Content-Transfer-Encoding-Header fehlt, wird die Payload unverändert zurückgegeben (undekodiert). In allen Fällen handelt es sich bei dem zurückgegebenen Wert um Binärdaten. Wenn die Nachricht eine Multipart ist und das decode-Flag True ist, wird None zurückgegeben. Wenn die Payload base64 ist und nicht perfekt formatiert war (fehlende Auffüllung, Zeichen außerhalb des base64-Alphabets), wird ein entsprechender Fehler zur Fehlereigenschaft der Nachricht hinzugefügt (InvalidBase64PaddingDefect oder InvalidBase64CharactersDefect).

Wenn decode False (Standard) ist, wird der Body als Zeichenkette ohne Dekodierung des Content-Transfer-Encoding zurückgegeben. Bei einem Content-Transfer-Encoding von 8bit wird jedoch versucht, die ursprünglichen Bytes mit der im Content-Type-Header angegebenen charset unter Verwendung des Fehlerbehandlungsverfahrens replace zu dekodieren. Wenn kein charset angegeben ist oder wenn das angegebene charset vom E-Mail-Paket nicht erkannt wird, wird der Body mit dem Standard-ASCII-Zeichensatz dekodiert.

Dies ist eine Legacy-Methode. Auf der Klasse EmailMessage wird ihre Funktionalität durch get_content() und iter_parts() ersetzt.

set_payload(payload, charset=None)

Setzt die gesamte Payload des Nachrichtenobjekts auf payload. Es liegt in der Verantwortung des Clients, die Payload-Invarianten sicherzustellen. Optionales charset setzt den Standardzeichensatz der Nachricht; siehe set_charset() für Details.

Dies ist eine Legacy-Methode. Auf der Klasse EmailMessage wird ihre Funktionalität durch set_content() ersetzt.

set_charset(charset)

Setzt den Zeichensatz der Payload auf charset, was entweder eine Instanz von Charset (siehe email.charset), eine Zeichenkette, die einen Zeichensatz benennt, oder None sein kann. Wenn es eine Zeichenkette ist, wird sie in eine Instanz von Charset konvertiert. Wenn charset None ist, wird der Parameter charset aus dem Content-Type-Header entfernt (die Nachricht wird nicht anderweitig verändert). Alles andere löst einen TypeError aus.

Wenn kein vorhandener MIME-Version-Header vorhanden ist, wird einer hinzugefügt. Wenn kein vorhandener Content-Type-Header vorhanden ist, wird einer mit dem Wert text/plain hinzugefügt. Unabhängig davon, ob der Content-Type-Header bereits vorhanden ist oder nicht, wird sein Parameter charset auf charset.output_charset gesetzt. Wenn charset.input_charset und charset.output_charset sich unterscheiden, wird die Payload in den output_charset neu codiert. Wenn kein vorhandener Content-Transfer-Encoding-Header vorhanden ist, wird die Payload bei Bedarf mit dem angegebenen Charset transfercodiert und ein Header mit dem entsprechenden Wert hinzugefügt. Wenn ein Content-Transfer-Encoding-Header bereits vorhanden ist, wird angenommen, dass die Payload bereits mit diesem Content-Transfer-Encoding korrekt codiert ist und wird nicht verändert.

Dies ist eine Legacy-Methode. Auf der Klasse EmailMessage wird ihre Funktionalität durch den charset-Parameter der Methode email.message.EmailMessage.set_content() ersetzt.

get_charset()

Gibt die Charset-Instanz zurück, die mit der Payload der Nachricht verknüpft ist.

Dies ist eine Legacy-Methode. Auf der Klasse EmailMessage gibt sie immer None zurück.

Die folgenden Methoden implementieren eine Mapping-ähnliche Schnittstelle für den Zugriff auf die RFC 2822-Header der Nachricht. Beachten Sie, dass es semantische Unterschiede zwischen diesen Methoden und einer normalen Mapping-Schnittstelle (d. h. einem Wörterbuch) gibt. Zum Beispiel gibt es in einem Wörterbuch keine doppelten Schlüssel, aber hier kann es doppelte Nachrichten-Header geben. Außerdem gibt es in Wörterbüchern keine garantierte Reihenfolge der von keys() zurückgegebenen Schlüssel, aber in einem Message-Objekt werden Header immer in der Reihenfolge zurückgegeben, in der sie in der ursprünglichen Nachricht erschienen sind oder später zur Nachricht hinzugefügt wurden. Jeder gelöschte und dann neu hinzugefügte Header wird immer am Ende der Header-Liste angehängt.

Diese semantischen Unterschiede sind beabsichtigt und auf maximale Benutzerfreundlichkeit ausgerichtet.

Beachten Sie, dass in allen Fällen ein etwaiger Umschlag-Header in der Nachricht nicht in der Mapping-Schnittstelle enthalten ist.

In einem aus Bytes generierten Modell werden Header-Werte, die (entgegen den RFCs) Nicht-ASCII-Bytes enthalten, bei Abruf über diese Schnittstelle als Header-Objekte mit einem Zeichensatz von unknown-8bit dargestellt.

__len__()

Gibt die Gesamtzahl der Header zurück, einschließlich Duplikaten.

__contains__(name)

Gibt True zurück, wenn das Nachrichtenobjekt ein Feld mit dem Namen name hat. Die Übereinstimmung erfolgt unabhängig von der Groß- und Kleinschreibung, und name sollte den nachfolgenden Doppelpunkt nicht enthalten. Wird für den in-Operator verwendet, z. B.

if 'message-id' in myMessage:
   print('Message-ID:', myMessage['message-id'])

__getitem__(name)

Gibt den Wert des benannten Headerfelds zurück. name sollte den Doppelpunkt-Feldtrenner nicht enthalten. Wenn der Header fehlt, wird None zurückgegeben; ein KeyError wird nie ausgelöst.

Beachten Sie, dass, wenn das benannte Feld mehr als einmal in den Headern der Nachricht vorkommt, undefiniert ist, welcher dieser Feldwerte zurückgegeben wird. Verwenden Sie die Methode get_all(), um die Werte aller vorhandenen benannten Header zu erhalten.

__setitem__(name, val)

Fügt einen Header zur Nachricht mit dem Feldnamen name und dem Wert val hinzu. Das Feld wird am Ende der vorhandenen Felder der Nachricht angehängt.

Beachten Sie, dass dadurch vorhandene Header mit demselben Namen *nicht* überschrieben oder gelöscht werden. Wenn Sie sicherstellen möchten, dass der neue Header der einzige ist, der in der Nachricht mit dem Feldnamen name vorhanden ist, löschen Sie das Feld zuerst, z. B.

del msg['subject']
msg['subject'] = 'Python roolz!'

__delitem__(name)

Löscht alle Vorkommen des Felds mit dem Namen name aus den Headern der Nachricht. Es wird keine Ausnahme ausgelöst, wenn das benannte Feld nicht in den Headern vorhanden ist.

keys()

Gibt eine Liste aller Headerfeldnamen der Nachricht zurück.

values()

Gibt eine Liste aller Feldwerte der Nachricht zurück.

items()

Gibt eine Liste von 2-Tupeln zurück, die alle Feld-Header und Werte der Nachricht enthalten.

get(name, failobj=None)

Gibt den Wert des benannten Headerfelds zurück. Dies ist identisch mit __getitem__(), außer dass das optionale failobj zurückgegeben wird, wenn der benannte Header fehlt (standardmäßig None).

Hier sind einige zusätzliche nützliche Methoden

get_all(name, failobj=None)

Gibt eine Liste aller Werte für das Feld mit dem Namen name zurück. Wenn keine solchen benannten Header in der Nachricht vorhanden sind, wird failobj zurückgegeben (standardmäßig None).

add_header(_name, _value, **_params)

Erweiterte Header-Einstellung. Diese Methode ähnelt __setitem__(), außer dass zusätzliche Header-Parameter als Schlüsselwortargumente bereitgestellt werden können. _name ist das hinzuzufügende Header-Feld und _value ist der primäre Wert für den Header.

Für jedes Element im Schlüsselwortargumenten-Wörterbuch _params wird der Schlüssel als Parametername genommen, wobei Unterstriche durch Bindestriche ersetzt werden (da Bindestriche in Python-Bezeichnern illegal sind). Normalerweise wird der Parameter als key="value" hinzugefügt, es sei denn, der Wert ist None, in diesem Fall wird nur der Schlüssel hinzugefügt. Wenn der Wert Nicht-ASCII-Zeichen enthält, kann er als Dreier-Tupel im Format (CHARSET, LANGUAGE, VALUE) angegeben werden, wobei CHARSET ein String ist, der die zu verwendende Zeichenkodierung für den Wert angibt, LANGUAGE normalerweise auf None oder den leeren String gesetzt werden kann (siehe RFC 2231 für andere Möglichkeiten) und VALUE der String-Wert ist, der Nicht-ASCII-Codepunkte enthält. Wenn kein Dreier-Tupel übergeben wird und der Wert Nicht-ASCII-Zeichen enthält, wird er automatisch im RFC 2231-Format mit einer CHARSET von utf-8 und einer LANGUAGE von None kodiert.

Hier ist ein Beispiel

msg.add_header('Content-Disposition', 'attachment', filename='bud.gif')

Dies fügt einen Header hinzu, der so aussieht

Content-Disposition: attachment; filename="bud.gif"

Ein Beispiel mit Nicht-ASCII-Zeichen

msg.add_header('Content-Disposition', 'attachment',
               filename=('iso-8859-1', '', 'Fußballer.ppt'))

Was ergibt

Content-Disposition: attachment; filename*="iso-8859-1''Fu%DFballer.ppt"

replace_header(_name, _value)

Ersetzt einen Header. Ersetzt den ersten im Nachricht gefundenen Header, der mit _name übereinstimmt, wobei die Header-Reihenfolge und die Groß-/Kleinschreibung des Feldnamens beibehalten werden. Wenn kein übereinstimmender Header gefunden wurde, wird ein KeyError ausgelöst.

get_content_type()

Gibt den Inhaltstyp der Nachricht zurück. Der zurückgegebene String wird in Kleinbuchstaben im Format maintype/subtype umgewandelt. Wenn kein Content-Type-Header in der Nachricht vorhanden war, wird der Standardtyp gemäß get_default_type() zurückgegeben. Da Nachrichten gemäß RFC 2045 immer einen Standardtyp haben, gibt get_content_type() immer einen Wert zurück.

RFC 2045 definiert den Standardtyp einer Nachricht als text/plain, es sei denn, sie erscheint innerhalb eines multipart/digest-Containers, in diesem Fall wäre sie message/rfc822. Wenn der Content-Type-Header eine ungültige Typangabe enthält, schreibt RFC 2045 vor, dass der Standardtyp text/plain ist.

get_content_maintype()

Gibt den Hauptinhaltstyp der Nachricht zurück. Dies ist der maintype-Teil des von get_content_type() zurückgegebenen Strings.

get_content_subtype()

Gibt den Unterinhaltstyp der Nachricht zurück. Dies ist der subtype-Teil des von get_content_type() zurückgegebenen Strings.

get_default_type()

Gibt den Standardinhaltstyp zurück. Die meisten Nachrichten haben einen Standardinhaltstyp von text/plain, außer Nachrichten, die Unterteile von multipart/digest-Containern sind. Solche Unterteile haben einen Standardinhaltstyp von message/rfc822.

set_default_type(ctype)

Legt den Standardinhaltstyp fest. ctype sollte entweder text/plain oder message/rfc822 sein, obwohl dies nicht erzwungen wird. Der Standardinhaltstyp wird nicht im Content-Type-Header gespeichert.

get_params(failobj=None, header='content-type', unquote=True)

Gibt die Parameter des Content-Type-Headers der Nachricht als Liste zurück. Die Elemente der zurückgegebenen Liste sind 2-Tupel von Schlüssel/Wert-Paaren, wie sie am Zeichen '=' aufgeteilt sind. Die linke Seite des '=' ist der Schlüssel, während die rechte Seite der Wert ist. Wenn kein '='-Zeichen im Parameter vorhanden ist, ist der Wert die leere Zeichenkette, andernfalls ist der Wert wie in get_param() beschrieben und wird optional entquotet, wenn unquote True ist (Standard).

Das optionale failobj ist das Objekt, das zurückgegeben wird, wenn kein Content-Type-Header vorhanden ist. Das optionale header ist der Header, der anstelle von Content-Type durchsucht werden soll.

Dies ist eine Legacy-Methode. In der Klasse EmailMessage wird ihre Funktionalität durch die params-Eigenschaft der einzelnen Header-Objekte ersetzt, die von den Header-Zugriffsmethoden zurückgegeben werden.

get_param(param, failobj=None, header='content-type', unquote=True)

Gibt den Wert des Parameters param des Content-Type-Headers als String zurück. Wenn die Nachricht keinen Content-Type-Header hat oder wenn es einen solchen Parameter nicht gibt, wird failobj zurückgegeben (Standard ist None).

Das optionale header, falls angegeben, gibt den Nachrichtenkopf an, der anstelle von Content-Type verwendet werden soll.

Parameter-Schlüssel werden immer case-insensitiv verglichen. Der Rückgabewert kann entweder ein String sein oder ein 3-Tupel, wenn der Parameter RFC 2231-kodiert war. Wenn es sich um ein 3-Tupel handelt, haben die Elemente des Werts die Form (CHARSET, LANGUAGE, VALUE). Beachten Sie, dass sowohl CHARSET als auch LANGUAGE None sein können, in diesem Fall sollten Sie VALUE als in der us-ascii-Zeichenkodierung kodiert betrachten. Sie können LANGUAGE normalerweise ignorieren.

Wenn Ihre Anwendung nicht darauf achtet, ob der Parameter wie in RFC 2231 kodiert wurde, können Sie den Parameterwert durch Aufrufen von email.utils.collapse_rfc2231_value() zusammenführen, wobei der Rückgabewert von get_param() übergeben wird. Dies gibt einen entsprechend dekodierten Unicode-String zurück, wenn der Wert ein Tupel ist, oder den ursprünglichen String unquotet, wenn er es nicht ist. Zum Beispiel

rawparam = msg.get_param('foo')
param = email.utils.collapse_rfc2231_value(rawparam)

In jedem Fall ist der Parameterwert (entweder der zurückgegebene String oder das VALUE-Element im 3-Tupel) immer unquotet, es sei denn, unquote ist auf False gesetzt.

Dies ist eine Legacy-Methode. In der Klasse EmailMessage wird ihre Funktionalität durch die params-Eigenschaft der einzelnen Header-Objekte ersetzt, die von den Header-Zugriffsmethoden zurückgegeben werden.

set_param(param, value, header='Content-Type', requote=True, charset=None, language='', replace=False)

Setzt einen Parameter im Content-Type-Header. Wenn der Parameter bereits im Header vorhanden ist, wird sein Wert durch value ersetzt. Wenn der Content-Type-Header für diese Nachricht noch nicht definiert wurde, wird er auf text/plain gesetzt und der neue Parameterwert wird gemäß RFC 2045 angehängt.

Der optionale header gibt einen alternativen Header zu Content-Type an, und alle Parameter werden nach Bedarf gequotet, es sei denn, das optionale requote ist False (Standard ist True).

Wenn das optionale charset angegeben ist, wird der Parameter gemäß RFC 2231 kodiert. Das optionale language gibt die RFC 2231-Sprache an und hat standardmäßig den leeren String. Sowohl charset als auch language sollten Strings sein.

Wenn replace False (Standard) ist, wird der Header ans Ende der Liste der Header verschoben. Wenn replace True ist, wird der Header an Ort und Stelle aktualisiert.

Geändert in Version 3.4: Das Schlüsselwort replace wurde hinzugefügt.

del_param(param, header='content-type', requote=True)

Entfernt den angegebenen Parameter vollständig aus dem Content-Type-Header. Der Header wird an Ort und Stelle ohne den Parameter oder seinen Wert neu geschrieben. Alle Werte werden nach Bedarf gequotet, es sei denn, requote ist False (Standard ist True). Das optionale header gibt eine Alternative zu Content-Type an.

set_type(type, header='Content-Type', requote=True)

Legt den Haupttyp und Untertyp für den Content-Type-Header fest. type muss ein String im Format maintype/subtype sein, andernfalls wird ein ValueError ausgelöst.

Diese Methode ersetzt den Content-Type-Header und behält alle Parameter bei. Wenn requote False ist, bleiben die Quoten des vorhandenen Headers unverändert, andernfalls werden die Parameter gequotet (Standard).

Ein alternativer Header kann im Argument header angegeben werden. Wenn der Content-Type-Header gesetzt wird, wird auch ein MIME-Version-Header hinzugefügt.

Dies ist eine Legacy-Methode. In der Klasse EmailMessage wird ihre Funktionalität durch die Methoden make_ und add_ ersetzt.

get_filename(failobj=None)

Gibt den Wert des filename-Parameters des Content-Disposition-Headers der Nachricht zurück. Wenn der Header keinen filename-Parameter hat, greift diese Methode auf die Suche nach dem name-Parameter im Content-Type-Header zurück. Wenn keiner von beiden gefunden wird oder der Header fehlt, wird failobj zurückgegeben. Der zurückgegebene String wird immer gemäß email.utils.unquote() unquotet.

get_boundary(failobj=None)

Gibt den Wert des boundary-Parameters des Content-Type-Headers der Nachricht zurück, oder failobj, wenn entweder der Header fehlt oder keinen boundary-Parameter hat. Der zurückgegebene String wird immer gemäß email.utils.unquote() unquotet.

set_boundary(boundary)

Setzt den boundary-Parameter des Content-Type-Headers auf boundary. set_boundary() wird boundary immer bei Bedarf quoten. Ein HeaderParseError wird ausgelöst, wenn das Nachrichtenobjekt keinen Content-Type-Header hat.

Beachten Sie, dass die Verwendung dieser Methode subtil anders ist als das Löschen des alten Content-Type-Headers und das Hinzufügen eines neuen mit dem neuen Boundary über add_header(), da set_boundary() die Reihenfolge des Content-Type-Headers in der Liste der Header beibehält. Es behält jedoch keine fortlaufenden Zeilen bei, die möglicherweise im ursprünglichen Content-Type-Header vorhanden waren.

get_content_charset(failobj=None)

Gibt den charset-Parameter des Content-Type-Headers zurück, umgewandelt in Kleinbuchstaben. Wenn kein Content-Type-Header vorhanden ist oder dieser Header keinen charset-Parameter hat, wird failobj zurückgegeben.

Beachten Sie, dass diese Methode von get_charset() abweicht, das die Charset-Instanz für die Standardkodierung des Nachrichtentexts zurückgibt.

get_charsets(failobj=None)

Gibt eine Liste zurück, die die Zeichensetznahmen in der Nachricht enthält. Wenn die Nachricht ein multipart ist, enthält die Liste ein Element für jeden Unterteil in der Nutzlast, andernfalls ist sie eine Liste der Länge 1.

Jedes Element in der Liste ist ein String, der den Wert des charset-Parameters im Content-Type-Header für den dargestellten Unterteil darstellt. Wenn der Unterteil jedoch keinen Content-Type-Header, keinen charset-Parameter hat oder nicht vom MIME-Typ text ist, ist dieses Element in der zurückgegebenen Liste failobj.

get_content_disposition()

Gibt den kleingeschriebenen Wert (ohne Parameter) des Content-Disposition-Headers der Nachricht zurück, falls vorhanden, oder None. Die möglichen Werte für diese Methode sind inline, attachment oder None, wenn die Nachricht RFC 2183 folgt.

Hinzugefügt in Version 3.5.

walk()

Die Methode walk() ist ein Allzweck-Generator, der verwendet werden kann, um alle Teile und Unterteile eines Nachrichtenobjektbaums in Tiefensuche-Reihenfolge zu durchlaufen. Typischerweise verwenden Sie walk() als Iterator in einer for-Schleife; jede Iteration gibt den nächsten Unterteil zurück.

Hier ist ein Beispiel, das den MIME-Typ jedes Teils einer multipart-Nachrichtenstruktur ausgibt

>>> for part in msg.walk():
...     print(part.get_content_type())
multipart/report
text/plain
message/delivery-status
text/plain
text/plain
message/rfc822
text/plain

walk durchläuft die Unterteile jedes Teils, für den is_multipart() True zurückgibt, auch wenn msg.get_content_maintype() == 'multipart' False zurückgeben kann. Dies können wir in unserem Beispiel sehen, indem wir die Debug-Hilfsfunktion _structure verwenden

>>> for part in msg.walk():
...     print(part.get_content_maintype() == 'multipart',
...           part.is_multipart())
True True
False False
False True
False False
False False
False True
False False
>>> _structure(msg)
multipart/report
    text/plain
    message/delivery-status
        text/plain
        text/plain
    message/rfc822
        text/plain

Hier sind die message-Teile keine multiparts, aber sie enthalten Unterteile. is_multipart() gibt True zurück und walk steigt in die Unterteile ab.

Message-Objekte können auch optional zwei Instanzattribute enthalten, die bei der Generierung des Klartextes einer MIME-Nachricht verwendet werden können.

preamble

Das Format eines MIME-Dokuments erlaubt Text zwischen der Leerzeile nach den Headern und dem ersten Multipart-Boundary-String. Normalerweise ist dieser Text in einem MIME-fähigen Mailreader nie sichtbar, da er außerhalb der Standard-MIME-Hülle liegt. Beim Betrachten des reinen Textes der Nachricht oder beim Betrachten der Nachricht in einem nicht-MIME-fähigen Reader kann dieser Text jedoch sichtbar werden.

Das Attribut preamble enthält diesen führenden zusätzlichen Hüllen-Text für MIME-Dokumente. Wenn der Parser Text nach den Headern, aber vor dem ersten Boundary-String entdeckt, weist er diesen Text dem preamble-Attribut der Nachricht zu. Wenn der Generator die Klartextdarstellung einer MIME-Nachricht schreibt und feststellt, dass die Nachricht ein preamble-Attribut hat, schreibt er diesen Text in den Bereich zwischen den Headern und dem ersten Boundary. Einzelheiten finden Sie in email.parser und email.generator.

Beachten Sie, dass das Attribut preamble None ist, wenn das Nachrichtenobjekt keine Präambel hat.

epilogue

Das Attribut epilogue verhält sich genauso wie das Attribut preamble, nur dass es Text enthält, der zwischen dem letzten Boundary und dem Ende der Nachricht steht.

Sie müssen den Epilog nicht auf die leere Zeichenkette setzen, damit der Generator am Ende der Datei einen Zeilenumbruch schreibt.

defects

Das Attribut defects enthält eine Liste aller Probleme, die beim Parsen dieser Nachricht gefunden wurden. Eine detaillierte Beschreibung der möglichen Parsing-Fehler finden Sie in email.errors.