email.contentmanager: Verwaltung von MIME-Inhalten

Quellcode: Lib/email/contentmanager.py

Hinzugefügt in Version 3.6: [1]

class email.contentmanager.ContentManager

Basisklasse für Content-Manager. Bietet die Standard-Registrierungsmechanismen, um Konverter zwischen MIME-Inhalten und anderen Darstellungen zu registrieren, sowie die Dispatch-Methoden get_content und set_content.

get_content(msg, *args, **kw)

Sucht anhand des mimetype von msg (siehe nächster Absatz) nach einer Handler-Funktion, ruft diese auf, übergibt alle Argumente und gibt das Ergebnis des Aufrufs zurück. Die Erwartung ist, dass der Handler die Nutzlast aus msg extrahiert und ein Objekt zurückgibt, das Informationen über die extrahierten Daten kodiert.

Um den Handler zu finden, wird die Registry nach den folgenden Schlüsseln durchsucht, wobei beim ersten gefundenen gestoppt wird:

  • der String, der den vollständigen MIME-Typ (maintype/subtype) repräsentiert

  • der String, der den maintype repräsentiert

  • der leere String

Wenn keiner dieser Schlüssel einen Handler ergibt, wird für den vollständigen MIME-Typ eine KeyError ausgelöst.

set_content(msg, obj, *args, **kw)

Wenn der maintype multipart ist, wird eine TypeError ausgelöst; andernfalls wird anhand des Typs von obj (siehe nächster Absatz) eine Handler-Funktion gesucht, clear_content() auf msg aufgerufen und die Handler-Funktion aufgerufen, wobei alle Argumente weitergegeben werden. Die Erwartung ist, dass der Handler obj in msg transformiert und speichert und möglicherweise weitere Änderungen an msg vornimmt, wie z. B. das Hinzufügen verschiedener MIME-Header zur Kodierung von Informationen, die zur Interpretation der gespeicherten Daten benötigt werden.

Um den Handler zu finden, wird der Typ von obj (typ = type(obj)) ermittelt und die Registry nach den folgenden Schlüsseln durchsucht, wobei beim ersten gefundenen gestoppt wird:

  • der Typ selbst (typ)

  • der vollständig qualifizierte Name des Typs (typ.__module__ + '.' + typ.__qualname__).

  • der qualname des Typs (typ.__qualname__)

  • der name des Typs (typ.__name__).

Wenn keine der obigen Übereinstimmungen gefunden wird, werden alle oben genannten Prüfungen für jeden der Typen im MRO (typ.__mro__) wiederholt. Schließlich wird, wenn kein anderer Schlüssel einen Handler ergibt, nach einem Handler für den Schlüssel None gesucht. Wenn kein Handler für None vorhanden ist, wird für den vollständig qualifizierten Namen des Typs eine KeyError ausgelöst.

Fügt auch einen MIME-Version-Header hinzu, falls keiner vorhanden ist (siehe auch MIMEPart).

add_get_handler(key, handler)

Zeichnet die Funktion handler als Handler für key auf. Die möglichen Werte für key finden Sie in get_content().

add_set_handler(typekey, handler)

Zeichnet handler als die Funktion auf, die aufgerufen werden soll, wenn ein Objekt eines Typs, der mit typekey übereinstimmt, an set_content() übergeben wird. Die möglichen Werte für typekey finden Sie in set_content().

Instanzen des Content-Managers

Derzeit bietet das E-Mail-Paket nur einen konkreten Content-Manager, raw_data_manager, obwohl in Zukunft weitere hinzugefügt werden könnten. raw_data_manager ist der content_manager, der von content_manager und seinen Derivaten bereitgestellt wird.

email.contentmanager.raw_data_manager

Dieser Content-Manager bietet nur eine minimale Schnittstelle über die von Message selbst bereitgestellte hinaus: er befasst sich nur mit Text, rohen Byte-Strings und Message-Objekten. Dennoch bietet er erhebliche Vorteile gegenüber der Basis-API: get_content für einen Textteil gibt einen Unicode-String zurück, ohne dass die Anwendung ihn manuell dekodieren muss, set_content bietet eine reichhaltige Auswahl an Optionen zur Steuerung der zu einem Teil hinzugefügten Header und zur Steuerung der Content-Transfer-Kodierung, und er ermöglicht die Verwendung der verschiedenen add_-Methoden, wodurch die Erstellung von Multipart-Nachrichten vereinfacht wird.

email.contentmanager.get_content(msg, errors='replace')

Gibt die Nutzlast des Teils als String (für text-Teile), als EmailMessage-Objekt (für message/rfc822-Teile) oder als bytes-Objekt (für alle anderen Nicht-Multipart-Typen) zurück. Löst eine KeyError aus, wenn sie auf einem multipart-Teil aufgerufen wird. Wenn der Teil ein text-Teil ist und errors angegeben ist, wird es als Fehlerbehandler beim Dekodieren der Nutzlast nach Unicode verwendet. Der Standardfehlerbehandler ist replace.

email.contentmanager.set_content(msg, <'str'>, subtype="plain", charset='utf-8', cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'bytes'>, maintype, subtype, cte="base64", disposition=None, filename=None, cid=None, params=None, headers=None)
email.contentmanager.set_content(msg, <'EmailMessage'>, cte=None, disposition=None, filename=None, cid=None, params=None, headers=None)

Fügt Header und Nutzlast zu msg hinzu

Fügt einen Content-Type-Header mit dem Wert maintype/subtype hinzu.

  • Für str wird der MIME-maintype auf text und der Subtyp auf subtype gesetzt, falls angegeben, oder auf plain, falls nicht.

  • Für bytes werden der angegebene maintype und subtype verwendet, oder es wird eine TypeError ausgelöst, wenn sie nicht angegeben sind.

  • Für EmailMessage-Objekte wird der Haupttyp auf message und der Untertyp auf subtype gesetzt, falls angegeben, oder auf rfc822, falls nicht. Wenn subtype partial ist, wird ein Fehler ausgelöst (bytes-Objekte müssen zum Erstellen von message/partial-Teilen verwendet werden).

Wenn charset angegeben ist (was nur für str gültig ist), wird der String mit der angegebenen Zeichenkodierung in Bytes kodiert. Der Standardwert ist utf-8. Wenn der angegebene charset ein bekannter Alias für einen Standard-MIME-Charset-Namen ist, wird stattdessen der Standard-Charset verwendet.

Wenn cte gesetzt ist, wird die Nutzlast mit der angegebenen Content-Transfer-Kodierung kodiert und der Content-Transfer-Encoding-Header auf diesen Wert gesetzt. Mögliche Werte für cte sind quoted-printable, base64, 7bit, 8bit und binary. Wenn die Eingabe nicht in der angegebenen Kodierung kodiert werden kann (z. B. bei Angabe eines cte von 7bit für eine Eingabe, die Nicht-ASCII-Werte enthält), wird eine ValueError ausgelöst.

  • Für str-Objekte, wenn cte nicht gesetzt ist, werden Heuristiken verwendet, um die kompakteste Kodierung zu bestimmen. Vor der Kodierung wird str.splitlines() verwendet, um alle Zeilenumbrüche zu normalisieren, sodass jede Zeile der Nutzlast durch die linesep-Eigenschaft der aktuellen Richtlinie terminiert wird (auch wenn die ursprüngliche Zeichenkette nicht mit einem solchen endete).

  • Für bytes-Objekte wird cte als base64 angenommen, wenn es nicht gesetzt ist, und die oben erwähnte Zeilenübersetzung wird nicht durchgeführt.

  • Für EmailMessage, gemäß RFC 2046, wird ein Fehler ausgelöst, wenn ein cte von quoted-printable oder base64 für subtype rfc822 angefordert wird, und für jeden cte außer 7bit für subtype external-body. Für message/rfc822 wird 8bit verwendet, wenn cte nicht angegeben ist. Für alle anderen Werte von subtype wird 7bit verwendet.

Hinweis

Ein cte von binary funktioniert noch nicht richtig. Das von set_content modifizierte EmailMessage-Objekt ist korrekt, aber BytesGenerator serialisiert es nicht korrekt.

Wenn disposition gesetzt ist, wird es als Wert für den Content-Disposition-Header verwendet. Wenn nicht angegeben und filename angegeben ist, wird der Header mit dem Wert attachment hinzugefügt. Wenn disposition nicht angegeben ist und filename ebenfalls nicht angegeben ist, wird der Header nicht hinzugefügt. Die einzigen gültigen Werte für disposition sind attachment und inline.

Wenn filename angegeben ist, wird es als Wert für den filename-Parameter des Content-Disposition-Headers verwendet.

Wenn cid angegeben ist, wird ein Content-ID-Header mit cid als Wert hinzugefügt.

Wenn params angegeben ist, wird die items-Methode durchlaufen und die resultierenden (key, value)-Paare verwendet, um zusätzliche Parameter auf dem Content-Type-Header zu setzen.

Wenn headers angegeben ist und eine Liste von Strings im Format headername: headervalue oder eine Liste von header-Objekten (unterschieden von Strings durch ein name-Attribut) ist, werden die Header zu msg hinzugefügt.

Fußnoten