email — Ein Paket zur Handhabung von E-Mails und MIME

Quellcode: Lib/email/__init__.py

Das Paket email ist eine Bibliothek zur Verwaltung von E-Mail-Nachrichten. Es ist ausdrücklich *nicht* dazu gedacht, E-Mail-Nachrichten an SMTP (RFC 2821), NNTP oder andere Server zu senden; dies sind Funktionen von Modulen wie smtplib. Das Paket email versucht, so RFC-konform wie möglich zu sein und unterstützt RFC 5322 und RFC 6532 sowie MIME-bezogene RFCs wie RFC 2045, RFC 2046, RFC 2047, RFC 2183 und RFC 2231.

Die Gesamtstruktur des E-Mail-Pakets lässt sich in drei Hauptkomponenten unterteilen, plus einer vierten Komponente, die das Verhalten der anderen Komponenten steuert.

Die zentrale Komponente des Pakets ist ein „Objektmodell“, das E-Mail-Nachrichten repräsentiert. Eine Anwendung interagiert mit dem Paket hauptsächlich über die Schnittstelle des Objektmodells, die im Untermodul message definiert ist. Die Anwendung kann diese API verwenden, um Fragen zu einer vorhandenen E-Mail zu stellen, eine neue E-Mail zu erstellen oder E-Mail-Unterkomponenten hinzuzufügen oder zu entfernen, die selbst die gleiche Objektmodell-Schnittstelle verwenden. Das heißt, entsprechend der Natur von E-Mail-Nachrichten und ihren MIME-Unterkomponenten, ist das E-Mail-Objektmodell eine Baumstruktur von Objekten, die alle die EmailMessage API bereitstellen.

Die beiden anderen Hauptkomponenten des Pakets sind der parser und der generator. Der Parser nimmt die serialisierte Version einer E-Mail-Nachricht (einen Byte-Stream) und wandelt sie in einen Baum von EmailMessage-Objekten um. Der Generator nimmt ein EmailMessage und wandelt es zurück in einen serialisierten Byte-Stream. (Der Parser und der Generator verarbeiten auch Textzeichen-Streams, aber diese Verwendung wird nicht empfohlen, da es zu leicht zu Nachrichten kommen kann, die auf die eine oder andere Weise ungültig sind.)

Die Steuerkomponente ist das Modul policy. Jede EmailMessage, jeder generator und jeder parser hat ein zugeordnetes policy-Objekt, das sein Verhalten steuert. Normalerweise muss eine Anwendung die Richtlinie nur dann angeben, wenn eine EmailMessage erstellt wird, entweder durch direkte Instanziierung einer EmailMessage, um eine neue E-Mail zu erstellen, oder durch Parsen eines Eingabestroms mit einem parser. Die Richtlinie kann jedoch geändert werden, wenn die Nachricht mit einem generator serialisiert wird. Dies ermöglicht es beispielsweise, eine generische E-Mail-Nachricht von der Festplatte zu parsen, sie aber beim Senden an einen E-Mail-Server mit Standard-SMTP-Einstellungen zu serialisieren.

Das E-Mail-Paket tut sein Bestes, um die Details der verschiedenen maßgeblichen RFCs vor der Anwendung zu verbergen. Konzeptionell sollte die Anwendung die E-Mail-Nachricht als eine strukturierte Baumstruktur aus Unicode-Text und binären Anhängen behandeln können, ohne sich darum kümmern zu müssen, wie diese beim Serialisieren dargestellt werden. In der Praxis ist es jedoch oft notwendig, zumindest einige der Regeln zu kennen, die für MIME-Nachrichten und ihre Struktur gelten, insbesondere die Namen und die Natur der MIME-„Content-Typen“ und wie sie Multipart-Dokumente identifizieren. Größtenteils sollte dieses Wissen nur für komplexere Anwendungen erforderlich sein, und selbst dann sollte nur die übergeordnete Struktur von Bedeutung sein und nicht die Details, wie diese Strukturen dargestellt werden. Da MIME-Content-Typen in moderner Internetsoftware (nicht nur in E-Mails) weit verbreitet sind, wird dies für viele Programmierer ein vertrautes Konzept sein.

Die folgenden Abschnitte beschreiben die Funktionalität des Pakets email. Wir beginnen mit dem Objektmodell message, das die primäre Schnittstelle ist, die eine Anwendung verwenden wird, und folgen dann den Komponenten parser und generator. Anschließend behandeln wir die policy-Steuerungen, die die Behandlung der Hauptkomponenten der Bibliothek abschließen.

Die nächsten drei Abschnitte behandeln die Ausnahmen, die das Paket auslösen kann, und die Fehler (Nichtkonformität mit den RFCs), die der parser erkennen kann. Dann behandeln wir die Unterkomponenten headerregistry und contentmanager, die Werkzeuge zur detaillierteren Manipulation von Headern und Payloads bereitstellen. Beide Komponenten enthalten Funktionen, die für den Verzehr und die Erzeugung nicht-trivialer Nachrichten relevant sind, dokumentieren aber auch ihre erweiterbaren APIs, die für fortgeschrittene Anwendungen von Interesse sein werden.

Danach folgt eine Reihe von Beispielen für die Verwendung der grundlegenden Teile der APIs, die in den vorherigen Abschnitten behandelt wurden.

Das Vorherige stellt die moderne (Unicode-freundliche) API des E-Mail-Pakets dar. Die verbleibenden Abschnitte, beginnend mit der Klasse Message, behandeln die Legacy-API compat32, die viel direkter mit den Details der Darstellung von E-Mail-Nachrichten umgeht. Die API compat32 verbirgt die Details der RFCs *nicht* vor der Anwendung, aber für Anwendungen, die auf dieser Ebene arbeiten müssen, können sie nützliche Werkzeuge sein. Diese Dokumentation ist auch für Anwendungen relevant, die aus Gründen der Abwärtskompatibilität immer noch die API compat32 verwenden.

Geändert in Version 3.6: Dokumentation neu organisiert und überarbeitet, um die neue API EmailMessage/EmailPolicy zu fördern.

Inhalt der Dokumentation für das Paket email

Legacy-API

Siehe auch

Modul smtplib

SMTP (Simple Mail Transport Protocol) Client

Modul poplib

POP (Post Office Protocol) Client

Modul imaplib

IMAP (Internet Message Access Protocol) Client

Modul mailbox

Werkzeuge zum Erstellen, Lesen und Verwalten von Nachrichtensammlungen auf der Festplatte unter Verwendung einer Reihe von Standardformaten.