email — Ett paket för hantering av e-post och MIME

Källkod: Lib/email/__init__.py

Paketet email är ett bibliotek för hantering av e-postmeddelanden. Det är specifikt inte utformat för att skicka e-postmeddelanden till SMTP (RFC 2821), NNTP eller andra servrar; sådana funktioner finns i moduler som smtplib. Paketet email försöker vara så RFC-kompatibelt som möjligt och stöder RFC 5322 och RFC 6532, samt sådana MIME-relaterade RFC:er som RFC 2045, RFC 2046, RFC 2047, RFC 2183 och RFC 2231.

Den övergripande strukturen i e-postpaketet kan delas in i tre huvudkomponenter, plus en fjärde komponent som styr beteendet hos de andra komponenterna.

Den centrala komponenten i paketet är en ”objektmodell” som representerar e-postmeddelanden. En applikation interagerar med paketet främst genom det gränssnitt för objektmodellen som definieras i undermodulen message. Programmet kan använda detta API för att ställa frågor om ett befintligt e-postmeddelande, för att konstruera ett nytt e-postmeddelande eller för att lägga till eller ta bort underkomponenter till e-postmeddelanden som själva använder samma objektmodellgränssnitt. Det vill säga, i enlighet med e-postmeddelandenas natur och deras MIME-underkomponenter, är e-postobjektmodellen en trädstruktur av objekt som alla tillhandahåller EmailMessage API.

De andra två huvudkomponenterna i paketet är parser och generator. Parsern tar den serialiserade versionen av ett e-postmeddelande (en ström av bytes) och omvandlar den till ett träd av EmailMessage-objekt. Generatorn tar ett EmailMessage och omvandlar det tillbaka till en serialiserad byte-ström. (Parsern och generatorn hanterar även strömmar av texttecken, men denna användning avrådes eftersom det är alltför lätt att få meddelanden som inte är giltiga på ett eller annat sätt)

Kontrollkomponenten är modulen policy. Varje EmailMessage, varje generator och varje parser har ett associerat policy-objekt som styr dess beteende. Vanligtvis behöver en applikation bara ange policyn när ett EmailMessage skapas, antingen genom att direkt instansiera ett EmailMessage för att skapa ett nytt e-postmeddelande, eller genom att analysera en inmatningsström med hjälp av en parser. Men policyn kan ändras när meddelandet serialiseras med hjälp av en generator. Detta gör att t.ex. ett generiskt e-postmeddelande kan analyseras från disk, men serialiseras med standard SMTP-inställningar när det skickas till en e-postserver.

E-postpaketet gör sitt bästa för att dölja detaljerna i de olika styrande RFC:erna för applikationen. Konceptuellt bör programmet kunna behandla e-postmeddelandet som ett strukturerat träd av Unicode-text och binära bilagor, utan att behöva oroa sig för hur dessa representeras när de serialiseras. I praktiken är det dock ofta nödvändigt att känna till åtminstone några av de regler som styr MIME-meddelanden och deras struktur, särskilt namnen på och karaktären hos MIME:s ”innehållstyper” och hur de identifierar flerdelade dokument. För det mesta bör denna kunskap endast krävas för mer komplexa tillämpningar, och även då bör det endast vara den övergripande strukturen som avses, och inte detaljerna i hur dessa strukturer representeras. Eftersom MIME-innehållstyper används i stor utsträckning i modern internetprogramvara (inte bara e-post) kommer detta att vara ett bekant koncept för många programmerare.

I följande avsnitt beskrivs funktionaliteten i paketet email. Vi börjar med objektmodellen message, som är det primära gränssnittet som en applikation kommer att använda, och fortsätter med komponenterna parser och generator. Sedan tar vi upp policy-kontrollerna, vilket avslutar behandlingen av bibliotekets huvudkomponenter.

I de tre följande avsnitten beskrivs de undantag som paketet kan ge upphov till och de defekter (bristande överensstämmelse med RFC) som parser kan upptäcka. Därefter beskrivs underkomponenterna headerregistry och contentmanager, som tillhandahåller verktyg för mer detaljerad hantering av rubriker respektive nyttolaster. Båda dessa komponenter innehåller funktioner som är relevanta för att konsumera och producera icke-triviala meddelanden, men dokumenterar också sina API:er för utvidgning, vilket kommer att vara av intresse för avancerade applikationer.

Därefter följer en uppsättning exempel på hur man använder de grundläggande delarna av de API:er som behandlas i de föregående avsnitten.

Ovanstående representerar det moderna (unicodevänliga) API:et för e-postpaketet. De återstående avsnitten, som börjar med klassen Message, täcker det äldre compat32-API:t som mycket mer direkt behandlar detaljerna i hur e-postmeddelanden representeras. API:et compat32 döljer inte detaljerna i RFC:erna från programmet, men för program som behöver arbeta på den nivån kan de vara användbara verktyg. Denna dokumentation är också relevant för program som fortfarande använder API:et compat32 av bakåtkompatibilitetsskäl.

Ändrad i version 3.6: Dokument omorganiserade och omskrivna för att främja det nya EmailMessage/EmailPolicy API:et.

Innehåll i dokumentationen för paketet email:

Äldre API:

Se även

Modul smtplib

SMTP-klient (Simple Mail Transport Protocol)

Modul poplib

POP-klient (Post Office Protocol)

Modul imaplib

IMAP-klient (Internet Message Access Protocol)

Modul mailbox

Verktyg för att skapa, läsa och hantera samlingar av meddelanden på disk med hjälp av olika standardformat.