email.generator: MIME-Dokumente generieren

Quellcode: Lib/email/generator.py

Eine der häufigsten Aufgaben ist die Generierung der flachen (serialisierten) Version der E-Mail-Nachricht, die durch eine Nachrichtenobjektstruktur dargestellt wird. Dies ist erforderlich, wenn Sie Ihre Nachricht über smtplib.SMTP.sendmail() senden oder die Nachricht auf der Konsole ausgeben möchten. Die Umwandlung einer Nachrichtenobjektstruktur in eine serialisierte Darstellung ist die Aufgabe der Generator-Klassen.

Wie beim Modul email.parser sind Sie nicht auf die Funktionalität des mitgelieferten Generators beschränkt; Sie könnten auch selbst einen von Grund auf neu schreiben. Der mitgelieferte Generator weiß jedoch, wie die meisten E-Mails standardkonform generiert werden, sollte MIME- und Nicht-MIME-E-Mail-Nachrichten problemlos verarbeiten und ist so konzipiert, dass die Byte-orientierten Parsing- und Generierungsoperationen invers sind, vorausgesetzt, derselbe nicht-transformierende policy wird für beide verwendet. Das heißt, wenn der serialisierte Byte-Stream über die Klasse BytesParser geparst und dann mit BytesGenerator wieder serialisiert wird, sollte die Ausgabe identisch mit der Eingabe sein [1]. (Andererseits kann die Verwendung des Generators für ein programmgesteuert erstelltes EmailMessage-Objekt zu Änderungen am EmailMessage-Objekt führen, da Standardwerte ausgefüllt werden.)

Die Klasse Generator kann verwendet werden, um eine Nachricht in eine textuelle (im Gegensatz zu binärer) serialisierte Darstellung zu überführen. Da Unicode jedoch keine Binärdaten direkt darstellen kann, wird die Nachricht zwangsläufig in etwas umgewandelt, das nur ASCII-Zeichen enthält, unter Verwendung der standardmäßigen E-Mail-RFC Content-Transfer-Encoding-Techniken zur Kodierung von E-Mail-Nachrichten für den Transport über Kanäle, die nicht "8-Bit-sauber" sind.

Um die reproduzierbare Verarbeitung von SMIME-signierten Nachrichten zu ermöglichen, deaktiviert Generator das Umbrechen von Kopfzeilen für Nachrichtenteile vom Typ multipart/signed und alle Unterteile.

class email.generator.BytesGenerator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Gibt ein BytesGenerator-Objekt zurück, das jede an die Methode flatten() übergebene Nachricht oder jeden an die Methode write() übergebenen, als 'surrogateescape' kodierten Text an das dateiähnliche Objekt outfp schreibt. outfp muss eine write-Methode unterstützen, die Binärdaten akzeptiert.

Wenn das optionale Argument mangle_from_ auf True gesetzt ist, wird jeder Zeile im Body, die mit der exakten Zeichenkette "From " beginnt (d. h. From gefolgt von einem Leerzeichen am Zeilenanfang), ein >-Zeichen vorangestellt. mangle_from_ hat standardmäßig den Wert der Einstellung mangle_from_ des policy (der für den compat32-Policy True und für alle anderen False ist). mangle_from_ ist für die Verwendung gedacht, wenn Nachrichten im Unix-Mbox-Format gespeichert werden (siehe mailbox und WARUM DAS CONTENT-LENGTH-FORMAT SCHLECHT IST).

Wenn maxheaderlen nicht None ist, werden alle Kopfzeilen, die länger als maxheaderlen sind, neu umgebrochen, oder wenn 0, werden keine Kopfzeilen umgebrochen. Wenn manheaderlen None (Standard) ist, werden Kopfzeilen und andere Nachrichtenzeilen gemäß den policy-Einstellungen umgebrochen.

Wenn policy angegeben ist, wird diese Policy zur Steuerung der Nachrichtengenerierung verwendet. Wenn policy None (Standard) ist, wird die Policy verwendet, die mit dem Message- oder EmailMessage-Objekt verknüpft ist, das an flatten übergeben wird, um die Nachrichtengenerierung zu steuern. Einzelheiten dazu, was policy steuert, finden Sie unter email.policy.

Hinzugefügt in Version 3.2.

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

Geändert in Version 3.6: Das Standardverhalten der Parameter mangle_from_ und maxheaderlen ist nun, der Policy zu folgen.

flatten(msg, unixfrom=False, linesep=None)

Gibt die textuelle Darstellung der Nachrichtenobjektstruktur, die bei msg verwurzelt ist, an die Ausgabedatei aus, die beim Erstellen der BytesGenerator-Instanz angegeben wurde.

Wenn die Policy-Option cte_type des policy auf 8bit (Standard) gesetzt ist, werden alle Kopfzeilen der ursprünglichen geparsten Nachricht, die nicht geändert wurden, mit den ursprünglichen Bits, deren höchstes Bit gesetzt ist, in die Ausgabe kopiert, und die nicht-ASCII Content-Transfer-Encoding von Nachrichtenteilen, die diese haben, wird beibehalten. Wenn cte_type auf 7bit gesetzt ist, werden die Bits mit dem gesetzten höchsten Bit mithilfe einer ASCII-kompatiblen Content-Transfer-Encoding konvertiert. Das heißt, Teile mit nicht-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) werden in eine ASCII-kompatible Content-Transfer-Encoding umgewandelt, und RFC-ungültige Nicht-ASCII-Bytes in Kopfzeilen werden unter Verwendung des MIME-Zeichensatzes unknown-8bit kodiert, wodurch sie RFC-konform werden.

Wenn unixfrom auf True gesetzt ist, wird der von der Unix-Mbox-Formatierung verwendete Umschlagskopf-Begrenzer (siehe mailbox) vor dem ersten der RFC 5322-Kopfzeilen des Stammobjekts ausgegeben. Wenn das Stammobjekt keinen Umschlagskopf hat, wird ein Standardkopf erstellt. Der Standardwert ist False. Beachten Sie, dass für Unterteile niemals ein Umschlagskopf ausgegeben wird.

Wenn linesep nicht None ist, wird es als Trennzeichen zwischen allen Zeilen der flachen Nachricht verwendet. Wenn linesep None (Standard) ist, wird der Wert verwendet, der in der policy angegeben ist.

clone(fp)

Gibt eine unabhängige Kopie dieser BytesGenerator-Instanz mit exakt denselben Einstellungen und fp als neuer outfp zurück.

write(s)

Kodiert s mit dem ASCII-Codec und dem surrogateescape-Fehlerbehandlungsverfahren und übergibt es an die write-Methode des outfp, das dem Konstruktor des BytesGenerator übergeben wurde.

Als Komfortfunktion bietet EmailMessage die Methoden as_bytes() und bytes(aMessage) (auch bekannt als __bytes__()), die die Generierung einer serialisierten binären Darstellung eines Nachrichtenobjekts vereinfachen. Weitere Details finden Sie unter email.message.

Da Zeichenketten keine Binärdaten darstellen können, muss die Klasse Generator alle Binärdaten in einer von ihr verarbeiteten Nachricht in ein ASCII-kompatibles Format konvertieren, indem sie diese in eine ASCII-kompatible Content-Transfer_Encoding umwandelt. In Anlehnung an die Terminologie der E-Mail-RFCs kann man sich dies so vorstellen, dass Generator in einen I/O-Stream serialisiert, der nicht "8-Bit-sauber" ist. Mit anderen Worten: Die meisten Anwendungen werden BytesGenerator und nicht Generator verwenden wollen.

class email.generator.Generator(outfp, mangle_from_=None, maxheaderlen=None, *, policy=None)

Gibt ein Generator-Objekt zurück, das jede an die Methode flatten() übergebene Nachricht oder jeden an die Methode write() übergebenen Text an das dateiähnliche Objekt outfp schreibt. outfp muss eine write-Methode unterstützen, die Zeichenketten-Daten akzeptiert.

Wenn das optionale Argument mangle_from_ auf True gesetzt ist, wird jeder Zeile im Body, die mit der exakten Zeichenkette "From " beginnt (d. h. From gefolgt von einem Leerzeichen am Zeilenanfang), ein >-Zeichen vorangestellt. mangle_from_ hat standardmäßig den Wert der Einstellung mangle_from_ des policy (der für den compat32-Policy True und für alle anderen False ist). mangle_from_ ist für die Verwendung gedacht, wenn Nachrichten im Unix-Mbox-Format gespeichert werden (siehe mailbox und WARUM DAS CONTENT-LENGTH-FORMAT SCHLECHT IST).

Wenn maxheaderlen nicht None ist, werden alle Kopfzeilen, die länger als maxheaderlen sind, neu umgebrochen, oder wenn 0, werden keine Kopfzeilen umgebrochen. Wenn manheaderlen None (Standard) ist, werden Kopfzeilen und andere Nachrichtenzeilen gemäß den policy-Einstellungen umgebrochen.

Wenn policy angegeben ist, wird diese Policy zur Steuerung der Nachrichtengenerierung verwendet. Wenn policy None (Standard) ist, wird die Policy verwendet, die mit dem Message- oder EmailMessage-Objekt verknüpft ist, das an flatten übergeben wird, um die Nachrichtengenerierung zu steuern. Einzelheiten dazu, was policy steuert, finden Sie unter email.policy.

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

Geändert in Version 3.6: Das Standardverhalten der Parameter mangle_from_ und maxheaderlen ist nun, der Policy zu folgen.

flatten(msg, unixfrom=False, linesep=None)

Gibt die textuelle Darstellung der Nachrichtenobjektstruktur, die bei msg verwurzelt ist, an die Ausgabedatei aus, die beim Erstellen der Generator-Instanz angegeben wurde.

Wenn die Policy-Option cte_type des policy auf 8bit gesetzt ist, wird die Nachricht generiert, als ob die Option auf 7bit gesetzt wäre. (Dies ist erforderlich, da Zeichenketten keine Nicht-ASCII-Bytes darstellen können.) Bits mit dem gesetzten höchsten Bit werden mithilfe einer ASCII-kompatiblen Content-Transfer-Encoding nach Bedarf konvertiert. Das heißt, Teile mit nicht-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) werden in eine ASCII-kompatible Content-Transfer-Encoding umgewandelt, und RFC-ungültige Nicht-ASCII-Bytes in Kopfzeilen werden unter Verwendung des MIME-Zeichensatzes unknown-8bit kodiert, wodurch sie RFC-konform werden.

Wenn unixfrom auf True gesetzt ist, wird der von der Unix-Mbox-Formatierung verwendete Umschlagskopf-Begrenzer (siehe mailbox) vor dem ersten der RFC 5322-Kopfzeilen des Stammobjekts ausgegeben. Wenn das Stammobjekt keinen Umschlagskopf hat, wird ein Standardkopf erstellt. Der Standardwert ist False. Beachten Sie, dass für Unterteile niemals ein Umschlagskopf ausgegeben wird.

Wenn linesep nicht None ist, wird es als Trennzeichen zwischen allen Zeilen der flachen Nachricht verwendet. Wenn linesep None (Standard) ist, wird der Wert verwendet, der in der policy angegeben ist.

Geändert in Version 3.2: Unterstützung für die erneute Kodierung von 8bit-Nachrichten-Bodies und das Argument linesep hinzugefügt.

clone(fp)

Gibt eine unabhängige Kopie dieser Generator-Instanz mit exakt denselben Optionen und fp als neuer outfp zurück.

write(s)

Schreibt s in die write-Methode des outfp, das dem Konstruktor des Generator übergeben wurde. Dies bietet eine ausreichende API für dateiähnliche Objekte, damit Generator-Instanzen in der Funktion print() verwendet werden können.

Als Komfortfunktion bietet EmailMessage die Methoden as_string() und str(aMessage) (auch bekannt als __str__()), die die Generierung einer formatierten Zeichenkettenrepräsentation eines Nachrichtenobjekts vereinfachen. Weitere Details finden Sie unter email.message.

Das Modul email.generator bietet außerdem eine abgeleitete Klasse, DecodedGenerator, die der Basisklasse Generator ähnelt, mit der Ausnahme, dass Nicht-text-Teile nicht serialisiert werden, sondern im Ausgabestrom durch eine Zeichenkette repräsentiert werden, die aus einer Vorlage abgeleitet ist, die mit Informationen über den Teil gefüllt wird.

class email.generator.DecodedGenerator(outfp, mangle_from_=None, maxheaderlen=None, fmt=None, *, policy=None)

Verhält sich wie Generator, außer dass für jeden Unterteil der an Generator.flatten() übergebenen Nachricht, wenn der Unterteil vom Haupttyp text ist, der dekodierte Payload des Unterteils ausgegeben wird, und wenn der Haupttyp nicht text ist, wird anstelle der Ausgabe die Zeichenkette fmt mit Informationen aus dem Teil gefüllt und die resultierende gefüllte Zeichenkette ausgegeben.

Um fmt zu füllen, wird fmt % part_info ausgeführt, wobei part_info ein Wörterbuch ist, das aus den folgenden Schlüsseln und Werten besteht:

  • type – Vollständiger MIME-Typ des Nicht-text-Teils

  • maintype – Haupt-MIME-Typ des Nicht-text-Teils

  • subtype – Unter-MIME-Typ des Nicht-text-Teils

  • filename – Dateiname des Nicht-text-Teils

  • description – Beschreibung des Nicht-text-Teils

  • encoding – Content-Transfer-Encoding des Nicht-text-Teils

Wenn fmt None ist, wird die folgende Standard-fmt verwendet:

“[Nicht-Text (%(type)s) Teil der Nachricht weggelassen, Dateiname %(filename)s]”

Optionale Argumente _mangle_from_ und maxheaderlen sind wie bei der Basisklasse Generator.

Fußnoten