email.utils: Diverse Hilfsprogramme

Quellcode: Lib/email/utils.py

Das Modul email.utils bietet einige nützliche Hilfsprogramme.

email.utils.localtime(dt=None)

Gibt die lokale Zeit als zustandsbehaftetes `datetime`-Objekt zurück. Wenn ohne Argumente aufgerufen, wird die aktuelle Zeit zurückgegeben. Andernfalls sollte das Argument dt eine datetime-Instanz sein und wird gemäß der Systemzeitzonendatenbank in die lokale Zeitzone konvertiert. Wenn dt naiv ist (d. h. dt.tzinfo ist None), wird angenommen, dass es sich in lokaler Zeit befindet.

Hinzugefügt in Version 3.3.

Seit Version 3.12 veraltet, in Version 3.14 entfernt: Der Parameter isdst.

email.utils.make_msgid(idstring=None, domain=None)

Gibt eine Zeichenkette zurück, die für einen RFC 2822-konformen Message-ID-Header geeignet ist. Ein optionales idstring, falls vorhanden, ist eine Zeichenkette, die zur Stärkung der Einzigartigkeit der Nachrichten-ID verwendet wird. Ein optionaler domain, falls vorhanden, liefert den Teil der msgid nach dem „@“. Der Standardwert ist der lokale Hostname. Es ist normalerweise nicht notwendig, diesen Standardwert zu überschreiben, kann aber in bestimmten Fällen nützlich sein, z. B. beim Aufbau eines verteilten Systems, das einen konsistenten Domainnamen über mehrere Hosts hinweg verwendet.

Geändert in Version 3.2: Der Schlüsselwortparameter domain wurde hinzugefügt.

Die übrigen Funktionen sind Teil der Legacy-API (Compat32) für E-Mails. Es besteht keine Notwendigkeit, diese direkt mit der neuen API zu verwenden, da die von ihnen bereitgestellte Analyse und Formatierung automatisch durch die Header-Analyse der neuen API erfolgt.

email.utils.quote(str)

Gibt eine neue Zeichenkette zurück, in der Backslashes in str durch zwei Backslashes und doppelte Anführungszeichen durch Backslash-doppelte Anführungszeichen ersetzt werden.

email.utils.unquote(str)

Gibt eine neue Zeichenkette zurück, die eine *unquoted* Version von str ist. Wenn str mit doppelten Anführungszeichen endet und beginnt, werden diese entfernt. Ebenso werden, wenn str mit spitzen Klammern endet und beginnt, diese entfernt.

email.utils.parseaddr(address, *, strict=True)

Analysiert eine Adresse – die der Wert eines Adressen enthaltenden Feldes wie To oder Cc sein sollte – in ihre Bestandteile *realname* und *E-Mail-Adresse*. Gibt ein Tupel dieser Informationen zurück, es sei denn, die Analyse schlägt fehl, in welchem Fall ein 2-Tupel von ('', '') zurückgegeben wird.

Wenn strict wahr ist, wird ein strenger Parser verwendet, der fehlerhafte Eingaben ablehnt.

Geändert in Version 3.13: Optionaler Parameter strict hinzugefügt und fehlerhafte Eingaben standardmäßig abgelehnt.

email.utils.formataddr(pair, charset='utf-8')

Das Gegenteil von parseaddr(). Dies nimmt ein 2-Tupel der Form (realname, email_address) und gibt den Zeichenkettenwert zurück, der für einen To- oder Cc-Header geeignet ist. Wenn das erste Element von pair falsch ist, wird das zweite Element unverändert zurückgegeben.

Optionales charset ist die Zeichensatz, der bei der RFC 2047-Kodierung des realname verwendet wird, falls der realname Nicht-ASCII-Zeichen enthält. Kann eine Instanz von str oder ein Charset sein. Standard ist utf-8.

Geändert in Version 3.3: Die Option charset wurde hinzugefügt.

email.utils.getaddresses(fieldvalues, *, strict=True)

Diese Methode gibt eine Liste von 2-Tupeln im Format zurück, das von parseaddr() zurückgegeben wird. fieldvalues ist eine Sequenz von Header-Feldwerten, wie sie von Message.get_all zurückgegeben werden könnten.

Wenn strict wahr ist, wird ein strenger Parser verwendet, der fehlerhafte Eingaben ablehnt.

Hier ist ein einfaches Beispiel, das alle Empfänger einer Nachricht abruft.

from email.utils import getaddresses

tos = msg.get_all('to', [])
ccs = msg.get_all('cc', [])
resent_tos = msg.get_all('resent-to', [])
resent_ccs = msg.get_all('resent-cc', [])
all_recipients = getaddresses(tos + ccs + resent_tos + resent_ccs)

Geändert in Version 3.13: Optionaler Parameter strict hinzugefügt und fehlerhafte Eingaben standardmäßig abgelehnt.

email.utils.parsedate(date)

Versucht, ein Datum gemäß den Regeln in RFC 2822 zu analysieren. Da jedoch einige Mailer dieses Format nicht spezifikationsgerecht verwenden, versucht parsedate() in solchen Fällen, korrekt zu raten. date ist eine Zeichenkette, die ein RFC 2822-Datum enthält, z. B. "Mon, 20 Nov 1995 19:12:08 -0500". Wenn das Datum erfolgreich analysiert werden kann, gibt parsedate() ein 9-Tupel zurück, das direkt an time.mktime() übergeben werden kann; andernfalls wird None zurückgegeben. Beachten Sie, dass die Indizes 6, 7 und 8 des Ergebnis-Tupels nicht verwendbar sind.

email.utils.parsedate_tz(date)

Führt dieselbe Funktion wie parsedate() aus, gibt jedoch entweder None oder ein 10-Tupel zurück. Die ersten 9 Elemente bilden ein Tupel, das direkt an time.mktime() übergeben werden kann, und das zehnte ist der Offset der Zeitzone des Datums von UTC (was der offizielle Begriff für Greenwich Mean Time ist) [1]. Wenn die Eingabezeichenkette keine Zeitzone hat, ist das letzte Element des zurückgegebenen Tupels 0, was UTC darstellt. Beachten Sie, dass die Indizes 6, 7 und 8 des Ergebnis-Tupels nicht verwendbar sind.

email.utils.parsedate_to_datetime(date)

Das Gegenteil von format_datetime(). Führt dieselbe Funktion wie parsedate() aus, gibt aber bei Erfolg ein datetime zurück; andernfalls wird ValueError ausgelöst, wenn date einen ungültigen Wert enthält, wie z. B. eine Stunde größer als 23 oder einen Zeitzonen-Offset, der nicht zwischen -24 und 24 Stunden liegt. Wenn das Eingabedatum eine Zeitzone von -0000 hat, ist das datetime ein naives datetime und repräsentiert bei RFC-konformen Daten eine Zeit in UTC, aber ohne Angabe der tatsächlichen Quellzeitzone der Nachricht, aus der das Datum stammt. Wenn das Eingabedatum einen anderen gültigen Zeitzonen-Offset hat, ist das datetime ein zustandsbehaftetes datetime mit dem entsprechenden timezone tzinfo.

Hinzugefügt in Version 3.3.

email.utils.mktime_tz(tuple)

Wandelt ein 10-Tupel, wie es von parsedate_tz() zurückgegeben wird, in einen UTC-Zeitstempel (Sekunden seit der Epoche) um. Wenn das Zeitzonen-Element im Tupel None ist, wird die lokale Zeit angenommen.

email.utils.formatdate(timeval=None, localtime=False, usegmt=False)

Gibt eine Datumszeichenkette gemäß RFC 2822 zurück, z. B.

Fri, 09 Nov 2001 01:08:47 -0000

Ein optionaler timeval, falls vorhanden, ist ein Gleitkommawert, der von time.gmtime() und time.localtime() akzeptiert wird; andernfalls wird die aktuelle Zeit verwendet.

Ein optionales localtime ist ein Flag, das, wenn es True ist, timeval interpretiert und ein Datum relativ zur lokalen Zeitzone anstelle von UTC zurückgibt, wobei die Sommerzeit ordnungsgemäß berücksichtigt wird. Der Standardwert ist False, was bedeutet, dass UTC verwendet wird.

Ein optionales usegmt ist ein Flag, das, wenn es True ist, eine Datumszeichenkette mit der Zeitzone als ASCII-Zeichenkette GMT ausgibt, anstatt eines numerischen -0000. Dies ist für einige Protokolle (wie HTTP) erforderlich. Dies gilt nur, wenn localtime False ist. Der Standardwert ist False.

email.utils.format_datetime(dt, usegmt=False)

Ähnlich wie formatdate, aber die Eingabe ist eine datetime-Instanz. Wenn es sich um ein naives `datetime` handelt, wird angenommen, dass es sich um „UTC ohne Informationen über die Quellzeitzone“ handelt, und die konventionelle -0000 wird für die Zeitzone verwendet. Wenn es sich um ein zustandsbehaftetes `datetime` handelt, wird der numerische Zeitzonen-Offset verwendet. Wenn es sich um eine zustandsbehaftete Zeitzone mit dem Offset null handelt, kann usegmt auf True gesetzt werden, in welchem Fall die Zeichenkette GMT anstelle des numerischen Zeitzonen-Offsets verwendet wird. Dies bietet eine Möglichkeit, standardkonforme HTTP-Datumskopfzeilen zu generieren.

Hinzugefügt in Version 3.3.

email.utils.decode_rfc2231(s)

Dekodiert die Zeichenkette s gemäß RFC 2231.

email.utils.encode_rfc2231(s, charset=None, language=None)

Kodiert die Zeichenkette s gemäß RFC 2231. Optionale charset und language, falls vorhanden, sind der zu verwendende Zeichensatzname und Sprachname. Wenn keiner von beiden angegeben wird, wird s unverändert zurückgegeben. Wenn charset angegeben, aber language nicht angegeben ist, wird die Zeichenkette mit einer leeren Zeichenkette für language kodiert.

email.utils.collapse_rfc2231_value(value, errors='replace', fallback_charset='us-ascii')

Wenn ein Header-Parameter im RFC 2231-Format kodiert ist, kann Message.get_param ein 3-Tupel zurückgeben, das den Zeichensatz, die Sprache und den Wert enthält. collapse_rfc2231_value() wandelt dies in eine Unicode-Zeichenkette um. Optionales errors wird an das errors-Argument der str-Methode encode() übergeben; es ist standardmäßig 'replace'. Optionales fallback_charset gibt den Zeichensatz an, der verwendet werden soll, wenn der im RFC 2231-Header angegebene Zeichensatz von Python nicht bekannt ist; er ist standardmäßig 'us-ascii'.

Zur Vereinfachung: Wenn der an collapse_rfc2231_value() übergebene value kein Tupel ist, sollte es sich um eine Zeichenkette handeln, und diese wird ungequotet zurückgegeben.

email.utils.decode_params(params)

Dekodiert die Parameterliste gemäß RFC 2231. params ist eine Sequenz von 2-Tupeln, die Elemente der Form (content-type, string-value) enthalten.

Fußnoten