email.mime: E-Mail- und MIME-Objekte von Grund auf erstellen

Quellcode: Lib/email/mime/

Dieses Modul ist Teil der Legacy-API (Compat32) für E-Mails. Seine Funktionalität wird teilweise durch contentmanager in der neuen API ersetzt, aber in bestimmten Anwendungen können diese Klassen auch in Nicht-Legacy-Code nützlich sein.

Normalerweise erhalten Sie eine Nachrichtenobjektstruktur, indem Sie eine Datei oder Text an einen Parser übergeben, der den Text analysiert und das Stamm-Nachrichtenobjekt zurückgibt. Sie können jedoch auch eine vollständige Nachrichtenstruktur von Grund auf erstellen oder sogar einzelne Message-Objekte manuell erstellen. Tatsächlich können Sie auch eine vorhandene Struktur nehmen und neue Message-Objekte hinzufügen, sie verschieben usw. Dies macht eine sehr praktische Schnittstelle zum Zerlegen und Zusammensetzen von MIME-Nachrichten.

Sie können eine neue Objektstruktur erstellen, indem Sie Message-Instanzen erstellen, Anhänge und alle geeigneten Header manuell hinzufügen. Für MIME-Nachrichten bietet das Paket email einige praktische Unterklassen, um die Dinge zu vereinfachen.

Hier sind die Klassen

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_params)

Modul: email.mime.base

Dies ist die Basisklasse für alle MIME-spezifischen Unterklassen von Message. Normalerweise werden Sie keine Instanzen speziell von MIMEBase erstellen, obwohl Sie es könnten. MIMEBase wird hauptsächlich als praktische Basisklasse für spezifischere MIME-fähige Unterklassen bereitgestellt.

_maintype ist der Haupttyp von Content-Type (z. B. text oder image), und _subtype ist der Nebentyp von Content-Type (z. B. plain oder gif). _params ist ein Parameter-Schlüssel/Wert-Dictionary und wird direkt an Message.add_header übergeben.

Wenn policy angegeben ist (standardmäßig die compat32-Richtlinie), wird sie an Message übergeben.

Die Klasse MIMEBase fügt immer einen Header Content-Type (basierend auf _maintype, _subtype und _params) und einen Header MIME-Version (immer auf 1.0 gesetzt) hinzu.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.

class email.mime.nonmultipart.MIMENonMultipart

Modul: email.mime.nonmultipart

Diese Unterklasse von MIMEBase ist eine Zwischenbasisklasse für MIME-Nachrichten, die nicht multipart sind. Der Hauptzweck dieser Klasse ist die Verhinderung der Verwendung der Methode attach(), die nur für multipart-Nachrichten sinnvoll ist. Wenn attach() aufgerufen wird, wird eine Ausnahme vom Typ MultipartConversionError ausgelöst.

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

Modul: email.mime.multipart

Diese Unterklasse von MIMEBase ist eine Zwischenbasisklasse für MIME-Nachrichten, die multipart sind. Das optionale _subtype hat standardmäßig den Wert mixed, kann aber verwendet werden, um den Subtyp der Nachricht anzugeben. Ein Header Content-Type von multipart/_subtype wird dem Nachrichtenobjekt hinzugefügt. Ein Header MIME-Version wird ebenfalls hinzugefügt.

Das optionale boundary ist der Multipart-Boundary-String. Wenn es None (Standard) ist, wird der Boundary bei Bedarf berechnet (z. B. wenn die Nachricht serialisiert wird).

_subparts ist eine Sequenz anfänglicher Unterteile für die Nutzlast. Diese Sequenz muss in eine Liste konvertierbar sein. Sie können der Nachricht jederzeit neue Unterteile hinzufügen, indem Sie die Methode Message.attach verwenden.

Das optionale Argument policy ist standardmäßig compat32.

Zusätzliche Parameter für den Header Content-Type werden aus den Schlüsselwortargumenten übernommen oder über das Argument _params übergeben, das ein Dictionary ist.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Modul: email.mime.application

Diese Unterklasse von MIMENonMultipart, die Klasse MIMEApplication, wird zur Darstellung von MIME-Nachrichtenobjekten des Haupttyps application verwendet. _data enthält die Bytes für die Rohdaten der Anwendung. Optional _subtype gibt den MIME-Subtyp an und hat standardmäßig den Wert octet-stream.

Optional _encoder ist ein aufrufbares Objekt (d. h. eine Funktion), das die eigentliche Kodierung der Daten für den Transport durchführt. Dieses aufrufbare Objekt nimmt ein Argument entgegen, nämlich die Instanz von MIMEApplication. Es sollte get_payload() und set_payload() verwenden, um die Nutzlast in die kodierte Form zu ändern. Es sollte außerdem alle Header wie Content-Transfer-Encoding oder andere Header nach Bedarf zum Nachrichtenobjekt hinzufügen. Die Standardkodierung ist Base64. Eine Liste der integrierten Encoder finden Sie im Modul email.encoders.

Das optionale Argument policy ist standardmäßig compat32.

_params werden direkt an den Konstruktor der Basisklasse weitergegeben.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Modul: email.mime.audio

Diese Unterklasse von MIMENonMultipart, die Klasse MIMEAudio, wird zur Erstellung von MIME-Nachrichtenobjekten des Haupttyps audio verwendet. _audiodata enthält die Bytes für die Rohaudiodaten. Wenn diese Daten als au, wav, aiff oder aifc dekodiert werden können, wird der Subtyp automatisch in den Header Content-Type aufgenommen. Andernfalls können Sie den Audiosubtyp explizit über das Argument _subtype angeben. Wenn der Nebentyp nicht erraten werden konnte und _subtype nicht angegeben wurde, wird eine Ausnahme vom Typ TypeError ausgelöst.

Optional _encoder ist ein aufrufbares Objekt (d. h. eine Funktion), das die eigentliche Kodierung der Audiodaten für den Transport durchführt. Dieses aufrufbare Objekt nimmt ein Argument entgegen, nämlich die Instanz von MIMEAudio. Es sollte get_payload() und set_payload() verwenden, um die Nutzlast in die kodierte Form zu ändern. Es sollte außerdem alle Header wie Content-Transfer-Encoding oder andere Header nach Bedarf zum Nachrichtenobjekt hinzufügen. Die Standardkodierung ist Base64. Eine Liste der integrierten Encoder finden Sie im Modul email.encoders.

Das optionale Argument policy ist standardmäßig compat32.

_params werden direkt an den Konstruktor der Basisklasse weitergegeben.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

Modul: email.mime.image

Diese Unterklasse von MIMENonMultipart, die Klasse MIMEImage, wird zur Erstellung von MIME-Nachrichtenobjekten des Haupttyps image verwendet. _imagedata enthält die Bytes für die Rohbilddaten. Wenn dieser Datentyp erkannt werden kann (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp und exr werden versucht), wird der Subtyp automatisch in den Header Content-Type aufgenommen. Andernfalls können Sie den Bildsubtyp explizit über das Argument _subtype angeben. Wenn der Nebentyp nicht erraten werden konnte und _subtype nicht angegeben wurde, wird eine Ausnahme vom Typ TypeError ausgelöst.

Optional _encoder ist ein aufrufbares Objekt (d. h. eine Funktion), das die eigentliche Kodierung der Bilddaten für den Transport durchführt. Dieses aufrufbare Objekt nimmt ein Argument entgegen, nämlich die Instanz von MIMEImage. Es sollte get_payload() und set_payload() verwenden, um die Nutzlast in die kodierte Form zu ändern. Es sollte außerdem alle Header wie Content-Transfer-Encoding oder andere Header nach Bedarf zum Nachrichtenobjekt hinzufügen. Die Standardkodierung ist Base64. Eine Liste der integrierten Encoder finden Sie im Modul email.encoders.

Das optionale Argument policy ist standardmäßig compat32.

_params werden direkt an den Konstruktor der MIMEBase-Klasse weitergegeben.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

Modul: email.mime.message

Diese Unterklasse von MIMENonMultipart, die Klasse MIMEMessage, wird zur Erstellung von MIME-Objekten des Haupttyps message verwendet. _msg wird als Nutzlast verwendet und muss eine Instanz der Klasse Message (oder einer Unterklasse davon) sein, andernfalls wird eine Ausnahme vom Typ TypeError ausgelöst.

Der optionale _subtype legt den Subtyp der Nachricht fest; er hat standardmäßig den Wert rfc822.

Das optionale Argument policy ist standardmäßig compat32.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

Modul: email.mime.text

Diese Unterklasse von MIMENonMultipart, die Klasse MIMEText, wird zur Erstellung von MIME-Objekten des Haupttyps text verwendet. _text ist der String für die Nutzlast. _subtype ist der Nebentyp und hat standardmäßig den Wert plain. _charset ist die Zeichensatz der Textdaten und wird als Argument an den Konstruktor von MIMENonMultipart übergeben; er hat standardmäßig den Wert us-ascii, wenn der String nur ascii-Codepunkte enthält, und andernfalls utf-8. Das Argument _charset akzeptiert entweder einen String oder eine Instanz von Charset.

Sofern das Argument _charset nicht explizit auf None gesetzt ist, hat das erstellte MIMEText-Objekt sowohl einen Header Content-Type mit einem Parameter charset als auch einen Header Content-Transfer-Encoding. Das bedeutet, dass ein nachfolgender Aufruf von set_payload nicht zu einer kodierten Nutzlast führt, selbst wenn ein Zeichensatz im Befehl set_payload übergeben wird. Sie können dieses Verhalten "zurücksetzen", indem Sie den Header Content-Transfer-Encoding löschen. Danach führt ein Aufruf von set_payload automatisch zur Kodierung der neuen Nutzlast (und fügt einen neuen Header Content-Transfer-Encoding hinzu).

Das optionale Argument policy ist standardmäßig compat32.

Geändert in Version 3.5: _charset akzeptiert nun auch Instanzen von Charset.

Geändert in Version 3.6: Optionaler schlüsselwortbasierter Parameter policy hinzugefügt.