email.generator: Generering av MIME-dokument

Källkod: Lib/email/generator.py

En av de vanligaste uppgifterna är att generera den platta (serialiserade) versionen av e-postmeddelandet som representeras av en meddelandeobjektstruktur. Du behöver göra detta om du vill skicka ditt meddelande via smtplib.SMTP.sendmail(), eller skriva ut meddelandet på konsolen. Att ta en meddelandeobjektstruktur och producera en serialiserad representation är jobbet för generatorklasserna.

Precis som med modulen email.parser är du inte begränsad till funktionaliteten i den medföljande generatorn; du kan skriva en från grunden själv. Den medföljande generatorn vet dock hur man genererar de flesta e-postmeddelanden på ett standardkompatibelt sätt, bör hantera MIME- och icke-MIME-e-postmeddelanden helt okej och är utformad så att de bytesorienterade pars- och genereringsoperationerna är inversa, förutsatt att samma icke-transformerande policy används för båda. Det vill säga, att analysera den serialiserade byteströmmen via BytesParser-klassen och sedan regenerera den serialiserade byteströmmen med BytesGenerator bör ge utdata som är identiska med indata [1]. (Å andra sidan kan användning av generatorn på ett EmailMessage konstruerat av ett program resultera i ändringar av EmailMessage-objektet när standardvärden fylls i)

Klassen Generator kan användas för att platta till ett meddelande till en text (i motsats till binär) serialiserad representation, men eftersom Unicode inte kan representera binära data direkt måste meddelandet omvandlas till något som bara innehåller ASCII-tecken, med hjälp av standard RFC Content Transfer Encoding-teknik för e-postmeddelanden för kodning av e-postmeddelanden för transport över kanaler som inte är ”8 bit clean”.

För att möjliggöra reproducerbar behandling av SMIME-signerade meddelanden inaktiverar Generator header folding för meddelandedelar av typen multipart/signed och alla underdelar.

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

Returnerar ett BytesGenerator-objekt som skriver ett meddelande som tillhandahålls till flatten()-metoden, eller en surrogateescape-kodad text som tillhandahålls till write()-metoden, till file-like object outfp. outfp måste ha stöd för en write-metod som accepterar binära data.

Om det valfria mangle_from_ är True, placeras ett >-tecken framför varje rad i brödtexten som börjar med den exakta strängen "From", det vill säga From följt av ett mellanslag i början av en rad. mangle_from_ är standardvärdet för inställningen mangle_from_ i policy (som är True för policyn compat32 och False för alla andra). mangle_from_ är avsedd att användas när meddelanden lagras i Unix mbox-format (se mailbox och Varför är innehållslängdsformatet dåligt).

Om maxheaderlen inte är None, vik om alla rubrikrader som är längre än maxheaderlen, eller om 0, vik inte om några rubriker. Om manheaderlen är None (standard), bryts rubriker och andra meddelanderader enligt inställningarna för policy.

Om policy anges används den policyn för att styra genereringen av meddelanden. Om policy är None (standard), används den policy som är associerad med Message eller EmailMessage-objektet som skickas till flatten för att styra genereringen av meddelanden. Se email.policy för detaljer om vad policy kontrollerar.

Tillagd i version 3.2.

Ändrad i version 3.3: Nyckelordet policy har lagts till.

Ändrad i version 3.6: Standardbeteendet för parametrarna mangle_from_ och maxheaderlen är att följa policyn.

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

Skriv ut en textrepresentation av meddelandeobjektstrukturen med msg som bas till den utdatafil som angavs när instansen BytesGenerator skapades.

Om alternativet policy option cte_type är 8bit (standard), kopiera alla rubriker i det ursprungliga analyserade meddelandet som inte har modifierats till utdata med alla byte med den höga bituppsättningen reproducerade som i originalet, och bevara den icke-ASCII Content-Transfer-Encoding för alla kroppsdelar som har dem. Om cte_type är 7bit, konvertera byte med hög bituppsättning efter behov med hjälp av en ASCII-kompatibel Content-Transfer-Encoding. Det vill säga, omvandla delar med icke-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) till en ASCII-kompatibel Content-Transfer-Encoding, och koda RFC-giltiga icke-ASCII-bytes i rubriker med MIME-teckensatsen unknown-8bit, vilket gör dem RFC-kompatibla.

Om unixfrom är True, skriv ut den avgränsare för kuvertrubriker som används av Unix brevlådeformat (se mailbox) före den första av RFC 5322-rubrikerna i rotmeddelandeobjektet. Om rotobjektet inte har något kuverthuvud skapas ett standardhuvud. Standardvärdet är False. Observera att för subparts skrivs aldrig något kuverthuvud ut.

Om linesep inte är None används det som skiljetecken mellan alla rader i det tillplattade meddelandet. Om linesep är None (standard), används det värde som anges i policy.

clone(fp)

Returnerar en oberoende klon av denna BytesGenerator-instans med exakt samma alternativinställningar, och fp som den nya outfp.

write(s)

Koda s med hjälp av codec ASCII och felhanteraren surrogateescape och skicka den till metoden write i outfp som skickas till BytesGenerators konstruktör.

Som en bekvämlighet tillhandahåller EmailMessage metoderna as_bytes() och bytes(aMessage) (a.k.a. __bytes__()), som förenklar genereringen av en serialiserad binär representation av ett meddelandeobjekt. För mer information, se email.message.

Eftersom strängar inte kan representera binära data måste klassen Generator konvertera alla binära data i alla meddelanden som den plattar till ett ASCII-kompatibelt format genom att konvertera dem till en ASCII-kompatibel Content-Transfer_Encoding. Med hjälp av terminologin i RFC för e-post kan du tänka på detta som att Generator serialiserar till en I/O-ström som inte är ”8 bit clean”. Med andra ord kommer de flesta applikationer att vilja använda BytesGenerator, och inte Generator.

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

Returnerar ett Generator-objekt som skriver alla meddelanden som anges i flatten()-metoden, eller all text som anges i write()-metoden, till filliknande objekt outfp. outfp måste ha stöd för en write-metod som accepterar strängdata.

Om det valfria mangle_from_ är True, placeras ett >-tecken framför varje rad i brödtexten som börjar med den exakta strängen "From", det vill säga From följt av ett mellanslag i början av en rad. mangle_from_ är standardvärdet för inställningen mangle_from_ i policy (som är True för policyn compat32 och False för alla andra). mangle_from_ är avsedd att användas när meddelanden lagras i Unix mbox-format (se mailbox och Varför är innehållslängdsformatet dåligt).

Om maxheaderlen inte är None, vik om alla rubrikrader som är längre än maxheaderlen, eller om 0, vik inte om några rubriker. Om manheaderlen är None (standard), bryts rubriker och andra meddelanderader enligt inställningarna för policy.

Om policy anges används den policyn för att styra genereringen av meddelanden. Om policy är None (standard), används den policy som är associerad med Message eller EmailMessage-objektet som skickas till flatten för att styra genereringen av meddelanden. Se email.policy för detaljer om vad policy kontrollerar.

Ändrad i version 3.3: Nyckelordet policy har lagts till.

Ändrad i version 3.6: Standardbeteendet för parametrarna mangle_from_ och maxheaderlen är att följa policyn.

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

Skriv ut en textrepresentation av meddelandeobjektstrukturen med msg som rot till den utdatafil som angavs när Generator-instansen skapades.

Om alternativet policy cte_type är 8bit, genereras meddelandet som om alternativet vore inställt på 7bit. (Detta krävs eftersom strängar inte kan representera icke-ASCII-bytes.) Konvertera alla bytes med den höga biten inställd efter behov med en ASCII-kompatibel Content-Transfer-Encoding. Det vill säga, omvandla delar med icke-ASCII Content-Transfer-Encoding (Content-Transfer-Encoding: 8bit) till en ASCII-kompatibel Content-Transfer-Encoding, och koda RFC-giltiga icke-ASCII-bytes i rubriker med MIME-teckensatsen unknown-8bit, vilket gör dem RFC-kompatibla.

Om unixfrom är True, skriv ut den avgränsare för kuvertrubriker som används av Unix brevlådeformat (se mailbox) före den första av RFC 5322-rubrikerna i rotmeddelandeobjektet. Om rotobjektet inte har något kuverthuvud skapas ett standardhuvud. Standardvärdet är False. Observera att för subparts skrivs aldrig något kuverthuvud ut.

Om linesep inte är None används det som skiljetecken mellan alla rader i det tillplattade meddelandet. Om linesep är None (standard), används det värde som anges i policy.

Ändrad i version 3.2: Stöd för omkodning av 8bit-meddelandekroppar och argumentet linesep har lagts till.

clone(fp)

Returnerar en oberoende klon av denna Generator-instans med exakt samma alternativ, och fp som den nya outfp.

write(s)

Skriv s till write-metoden i den outfp som skickas till Generators konstruktör. Detta ger precis tillräckligt med filliknande API för att Generator-instanser ska kunna användas i funktionen print().

Som en bekvämlighet tillhandahåller EmailMessage metoderna as_string() och str(aMessage) (a.k.a. __str__()), som förenklar genereringen av en formaterad strängrepresentation av ett meddelandeobjekt. För mer information, se email.message.

Modulen email.generator tillhandahåller också en härledd klass, DecodedGenerator, som är som basklassen Generator, förutom att delar som inte är av typen text inte serialiseras, utan i stället representeras i utdataströmmen av en sträng som härleds från en mall som fylls i med information om delen.

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

Fungerar som Generator, förutom att för alla underdelar av meddelandet som skickas till Generator.flatten(), om underdelen är av huvudtypen text, skriv ut den avkodade nyttolasten för underdelen, och om huvudtypen inte är text, istället för att skriva ut den, fyll i strängen fmt med information från delen och skriv ut den resulterande ifyllda strängen.

För att fylla i fmt, kör fmt % part_info, där part_info är en ordbok som består av följande nycklar och värden:

  • type – Fullständig MIME-typ för den del som är non-text

  • maintype – Huvud-MIME-typ för delen non-text

  • subtype – Under-MIME-typ för delen non-text

  • filename – Filnamn för delen non-text

  • description – Beskrivning som är associerad med delen non-text

  • encoding – Innehållsöverföringskodning av delen non-text

Om fmt är None används följande standard fmt:

”[Icke-text (%(type)s) del av meddelandet utelämnad, filnamn %(filename)s]”

De valfria _mangle_from_ och maxheaderlen är samma som för basklassen Generator.

Fotnoter