email.policy: Policy-objekt

Tillagd i version 3.3.

Källkod: Lib/email/policy.py


Paketet email fokuserar i första hand på hanteringen av e-postmeddelanden enligt beskrivningen i de olika RFC:erna för e-post och MIME. Det allmänna formatet för e-postmeddelanden (ett block med rubrikfält som vart och ett består av ett namn följt av ett kolon följt av ett värde, hela blocket följt av en blankrad och en godtycklig ”body”) är dock ett format som har hittat användningsområden utanför e-postområdet. Vissa av dessa användningsområden överensstämmer ganska nära med de viktigaste RFC:erna för e-post, andra inte. Även när man arbetar med e-post finns det tillfällen då det är önskvärt att inte strikt följa RFC:erna, till exempel för att generera e-postmeddelanden som fungerar tillsammans med e-postservrar som inte själva följer standarderna, eller som implementerar tillägg som du vill använda på sätt som bryter mot standarderna.

Policyobjekt ger e-postpaketet den flexibilitet som krävs för att hantera alla dessa olika användningsområden.

Ett Policy-objekt kapslar in en uppsättning attribut och metoder som styr beteendet hos olika komponenter i e-postpaketet under användning. Policy-instanser kan skickas till olika klasser och metoder i e-postpaketet för att ändra standardbeteendet. De inställbara värdena och deras standardvärden beskrivs nedan.

Det finns en standardpolicy som används av alla klasser i e-postpaketet. För alla parser-klasserna och de relaterade bekvämlighetsfunktionerna, och för Message-klassen, är detta Compat32-policyn, via dess motsvarande fördefinierade instans compat32. Denna policy ger fullständig bakåtkompatibilitet (i vissa fall, inklusive buggkompatibilitet) med versionen av e-postpaketet före Python3.3.

Detta standardvärde för nyckelordet policy till EmailMessage är policyn EmailPolicy, via dess fördefinierade instans default.

När ett Message eller EmailMessage-objekt skapas får det en policy. Om meddelandet skapas av en parser, kommer en policy som skickas till parsern att vara den policy som används av det meddelande som den skapar. Om meddelandet skapas av programmet kan policyn anges när det skapas. När ett meddelande skickas till en generator använder generatorn som standard policyn från meddelandet, men du kan också skicka en specifik policy till generatorn som åsidosätter den som finns lagrad på meddelandeobjektet.

Standardvärdet för nyckelordet policy för email.parser-klasserna och parserns bekvämlighetsfunktioner kommer att ändras i en framtida version av Python. Därför bör du alltid uttryckligen ange vilken policy du vill använda när du anropar någon av de klasser och funktioner som beskrivs i modulen parser.

Den första delen av denna dokumentation täcker funktionerna i Policy, en abstrakt basklass som definierar de funktioner som är gemensamma för alla policyobjekt, inklusive compat32. Detta inkluderar vissa hook-metoder som anropas internt av e-postpaketet, som en anpassad policy kan åsidosätta för att få ett annat beteende. I den andra delen beskrivs de konkreta klasserna EmailPolicy och Compat32, som implementerar de hooks som ger standardbeteendet respektive det bakåtkompatibla beteendet och funktionerna.

Policy-instanser är oföränderliga, men de kan klonas genom att acceptera samma nyckelordsargument som klasskonstruktören och returnera en ny Policy-instans som är en kopia av originalet men med de angivna attributvärdena ändrade.

Exempelvis kan följande kod användas för att läsa ett e-postmeddelande från en fil på disken och skicka det till systemets endmail-program på ett Unix-system:

>>> from email import message_from_binary_file
>>> from email.generator import BytesGenerator
>>> from email import policy
>>> from subprocess import Popen, PIPE
>>> with open('mymsg.txt', 'rb') as f:
...     msg = message_from_binary_file(f, policy=policy.default)
...
>>> p = Popen(['sendmail', msg['To'].addresses[0]], stdin=PIPE)
>>> g = BytesGenerator(p.stdin, policy=msg.policy.clone(linesep='\r\n'))
>>> g.flatten(msg)
>>> p.stdin.close()
>>> rc = p.wait()

Här säger vi till BytesGenerator att använda de RFC-korrekta radavskiljartecknen när vi skapar den binära strängen som ska matas in i sendmails stdin, där standardpolicyn skulle använda n radavskiljare.

Vissa metoder i e-postpaketet accepterar ett policy-nyckelordsargument, vilket gör att policyn kan åsidosättas för den metoden. Följande kod använder t.ex. metoden as_bytes() för objektet msg från föregående exempel och skriver meddelandet till en fil med de inbyggda radavgränsarna för den plattform som koden körs på:

>>> import os
>>> with open('converted.txt', 'wb') as f:
...     f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep)))
17

Policyobjekt kan också kombineras med hjälp av additionsoperatorn, vilket ger ett policyobjekt vars inställningar är en kombination av icke-standardvärdena för de summerade objekten:

>>> compat_SMTP = policy.compat32.clone(linesep='\r\n')
>>> compat_strict = policy.compat32.clone(raise_on_defect=True)
>>> compat_strict_SMTP = compat_SMTP + compat_strict

Denna operation är inte kommutativ, det vill säga att ordningen i vilken objekten läggs till spelar roll. För att illustrera:

>>> policy100 = policy.compat32.clone(max_line_length=100)
>>> policy80 = policy.compat32.clone(max_line_length=80)
>>> apolicy = policy100 + policy80
>>> apolicy.max_line_length
80
>>> apolicy = policy80 + policy100
>>> apolicy.max_line_length
100
class email.policy.Policy(**kw)

Detta är abstrakt basklass för alla policyklasser. Den tillhandahåller standardimplementeringar för ett par triviala metoder, samt implementeringen av egenskapen oföränderlighet, metoden clone() och konstruktörsemantik.

Konstruktören för en policyklass kan ges olika nyckelordsargument. De argument som kan anges är alla icke-metodegenskaper för denna klass, plus eventuella ytterligare icke-metodegenskaper för den konkreta klassen. Ett värde som anges i konstruktören åsidosätter standardvärdet för motsvarande attribut.

Denna klass definierar följande egenskaper, och värden för följande kan därför anges i konstruktorn för vilken policyklass som helst:

max_line_length

Den maximala längden på en rad i den serialiserade utdata, utan att räkna med radslutstecken. Standardvärdet är 78, enligt RFC 5322. Ett värde på 0 eller None anger att ingen radbrytning skall göras alls.

linesep

Den sträng som ska användas för att avsluta rader i serialiserad utdata. Standardvärdet är \n eftersom det är den interna radavslutningsdisciplinen som används av Python, men \r\n krävs enligt RFC.

cte_type

Styr vilken typ av innehållsöverföringskodningar som kan användas eller måste användas. De möjliga värdena är:

7bit

all data måste vara ”7 bit clean” (endast ASCII). Detta innebär att data vid behov kommer att kodas med antingen quoted-printable eller base64-kodning.

8bit

data är inte begränsad till att vara 7 bitars ren. Data i rubriker måste fortfarande vara ASCII-only och kommer därför att kodas (se fold_binary() och utf8 nedan för undantag), men kroppsdelar kan använda 8bit CTE.

Ett cte_type-värde på 8bit fungerar bara med BytesGenerator, inte med Generator, eftersom strängar inte kan innehålla binära data. Om en Generator arbetar under en policy som anger cte_type=8bit, kommer den att fungera som om cte_type är 7bit.

raise_on_defect

Om True, kommer alla defekter som påträffas att tas upp som fel. Om False (standard), kommer defekter att skickas till metoden register_defect().

mangle_from_

Om True, undviks rader som börjar med ”From” i brödtexten genom att sätta en > framför dem. Denna parameter används när meddelandet serialiseras av en generator. Standard: False.

Tillagd i version 3.5.

message_factory

En fabriksfunktion för att konstruera ett nytt tomt meddelandeobjekt. Används av parsern när meddelanden byggs. Standardvärdet är None, i vilket fall Message används.

Tillagd i version 3.6.

verify_generated_headers

Om True (standard), genererar generatorn HeaderWriteError istället för att skriva en header som är felaktigt vikt eller avgränsad, så att den skulle analyseras som flera headers eller sammanfogas med angränsande data. Sådana rubriker kan genereras av anpassade rubrikklasser eller buggar i modulen email.

Eftersom det är en säkerhetsfunktion är standardvärdet True även i policyn Compat32. För bakåtkompatibelt, men osäkert, beteende måste det uttryckligen sättas till False.

Tillagd i version 3.13.

Följande Policy-metod är avsedd att anropas av kod som använder e-postbiblioteket för att skapa policyinstanser med anpassade inställningar:

clone(**kw)

Returnerar en ny Policy-instans vars attribut har samma värden som den aktuella instansen, utom när dessa attribut ges nya värden av nyckelordsargumenten.

De återstående Policy-metoderna anropas av koden för e-postpaketet och är inte avsedda att anropas av ett program som använder e-postpaketet. En anpassad policy måste implementera alla dessa metoder.

handle_defect(obj, defect)

Hantera en defekt som hittats på obj. När e-postpaketet anropar den här metoden kommer defect alltid att vara en underklass till MessageDefect.

Standardimplementeringen kontrollerar flaggan raise_on_defect. Om den är True, tas defect upp som ett undantag. Om den är False (standard), skickas obj och defect till register_defect().

register_defect(obj, defect)

Registrera en defektobj. I e-postpaketet kommer defect alltid att vara en underklass till MessageDefect.

Standardimplementeringen anropar metoden append i attributet defects i obj. När e-postpaketet anropar handle_defect kommer obj normalt att ha ett defects-attribut som har en append-metod. Anpassade objekttyper som används med e-postpaketet (t.ex. anpassade Message-objekt) bör också ha ett sådant attribut, annars kommer defekter i analyserade meddelanden att ge upphov till oväntade fel.

header_max_count(name)

Returnera det högsta tillåtna antalet rubriker med namnet namn.

Anropas när en header läggs till i ett EmailMessage- eller Message-objekt. Om det returnerade värdet inte är 0 eller None, och det redan finns ett antal headers med namnet name som är större än eller lika med det returnerade värdet, skapas ett ValueError.

Eftersom standardbeteendet för Message.__setitem__ är att lägga till värdet i listan över headers är det lätt att skapa duplicerade headers utan att inse det. Med den här metoden kan vissa rubriker begränsas i antalet instanser av rubriken som kan läggas till i ett Message programmatiskt. (Begränsningen observeras inte av parsern, som troget kommer att producera så många rubriker som finns i meddelandet som parsas)

Standardimplementeringen returnerar None för alla header-namn.

header_source_parse(sourcelines)

E-postpaketet anropar den här metoden med en lista över strängar, där varje sträng slutar med de radavgränsningstecken som finns i källan som analyseras. Den första raden innehåller namnet på fälthuvudet och separatorn. Alla blanksteg i källan bevaras. Metoden ska returnera tupeln (namn, värde) som ska lagras i Message för att representera det analyserade sidhuvudet.

Om en implementering vill behålla kompatibiliteten med de befintliga policyerna för e-postpaket, ska name vara namnet med bevarad skiftlägesanalys (alla tecken fram till separatorn ”:”), medan value ska vara det utvikta värdet (alla radavgränsningstecken borttagna, men blanksteg intakta), utan inledande blanksteg.

sourcelines kan innehålla surrogatkapslade binära data.

Det finns ingen standardimplementering

header_store_parse(name, value)

E-postpaketet anropar den här metoden med det namn och värde som tillhandahålls av tillämpningsprogrammet när tillämpningsprogrammet ändrar ett Message programmatiskt (i motsats till ett Message som skapats av en parser). Metoden bör returnera den tupel (namn, värde) som skall lagras i Message för att representera rubriken.

Om en implementering vill behålla kompatibiliteten med de befintliga policyerna för e-postpaket bör name och value vara strängar eller subklasser av strängar som inte ändrar innehållet i de argument som skickas in.

Det finns ingen standardimplementering

header_fetch_parse(name, value)

E-postpaketet anropar den här metoden med namn och värde som för närvarande lagras i Message när den rubriken begärs av tillämpningsprogrammet, och det som metoden returnerar är det som skickas tillbaka till tillämpningsprogrammet som värdet på den rubrik som hämtas. Observera att det kan finnas mer än en header med samma namn lagrad i Message; metoden får det specifika namnet och värdet på den header som ska returneras till applikationen.

value kan innehålla surrogatinställda binära data. Det får inte finnas några surrogatkapslade binära data i det värde som returneras av metoden.

Det finns ingen standardimplementering

fold(name, value)

E-postpaketet anropar den här metoden med namn och värde som för närvarande finns lagrade i Message för en viss rubrik. Metoden bör returnera en sträng som representerar den rubriken ”vikt” korrekt (enligt policyinställningarna) genom att komponera namn med värde och infoga linesep-tecken på lämpliga ställen. Se RFC 5322 för en diskussion om reglerna för vikning av e-postrubriker.

value kan innehålla surrogatinställda binära data. Det får inte finnas några surrogatkapslade binära data i den sträng som returneras av metoden.

fold_binary(name, value)

Samma sak som fold(), förutom att det returnerade värdet ska vara ett bytesobjekt i stället för en sträng.

value kan innehålla binära data med surrogatförkortning. Dessa kan konverteras tillbaka till binära data i det returnerade bytes-objektet.

class email.policy.EmailPolicy(**kw)

Denna konkreta Policy ger ett beteende som är avsett att vara helt förenligt med de aktuella RFC:erna för e-post. Dessa inkluderar (men är inte begränsade till) RFC 5322, RFC 2047 och de aktuella MIME RFC:erna.

Denna policy lägger till nya algoritmer för parsning och vikning av headers. Istället för enkla strängar är headers subklasser av str med attribut som beror på fältets typ. Algoritmerna för parsning och vikning implementerar fullt ut RFC 2047 och RFC 5322.

Standardvärdet för attributet message_factory är EmailMessage.

Utöver de inställbara attribut som anges ovan och som gäller för alla policyer, lägger den här policyn till följande ytterligare attribut:

Tillagd i version 3.6: [1]

utf8

Om False, följ RFC 5322, stöd för icke-ASCII-tecken i rubriker genom att koda dem som ”kodade ord”. If True, follow RFC 6532 and use utf-8 encoding for headers. Meddelanden som formaterats på detta sätt kan skickas till SMTP-servrar som har stöd för tillägget SMTPUTF8 (RFC 6531).

refold_source

Om värdet för en rubrik i objektet Message härrör från en parser` (i motsats till att ha ställts in av ett program), anger detta attribut om en generator skall återanvända värdet när meddelandet transformeras tillbaka till serialiserad form. De möjliga värdena är:

none

alla källvärden använder originalvikning

long

källvärden som har någon rad som är längre än max_line_length kommer att vikas om

all

alla värden omformuleras.

Standardvärdet är long.

header_factory

En anropsbar funktion som tar två argument, name och value, där name är ett namn på ett rubrikfält och value är ett värde på ett ovikt rubrikfält, och returnerar en strängunderklass som representerar rubriken. En standard header_factory (se headerregistry) tillhandahålls som stöder anpassad analys av de olika adress- och datumfälttyperna RFC 5322 och de viktigaste MIME-fälttyperna. Stöd för ytterligare anpassad parsning kommer att läggas till i framtiden.

content_manager

Ett objekt med minst två metoder: get_content och set_content. När metoden get_content() eller set_content() i ett EmailMessage-objekt anropas, anropas motsvarande metod i detta objekt, varvid meddelandeobjektet skickas som första argument och eventuella argument eller nyckelord som skickats till det som ytterligare argument. Som standard är content_manager inställd på raw_data_manager.

Tillagd i version 3.4.

Klassen tillhandahåller följande konkreta implementationer av de abstrakta metoderna i Policy:

header_max_count(name)

Returnerar värdet på attributet max_count i den specialiserade klass som används för att representera sidhuvudet med det angivna namnet.

header_source_parse(sourcelines)

Namnet parsas som allt upp till ’:’ och returneras oförändrat. Värdet bestäms genom att ta bort ledande blanksteg från återstoden av den första raden, sammanfoga alla efterföljande rader och ta bort eventuella efterföljande tecken för vagnsretur eller radmatning.

header_store_parse(name, value)

Namnet returneras oförändrat. Om indatavärdet har ett name-attribut och det matchar name ignorerande fall, returneras värdet oförändrat. Annars skickas name och value till header_factory och det resulterande header-objektet returneras som värde. I detta fall uppstår ett ValueError om indatavärdet innehåller CR- eller LF-tecken.

header_fetch_parse(name, value)

Om värdet har ett name-attribut returneras det oförändrat. Annars skickas name och value med alla CR- eller LF-tecken borttagna till header_factory och det resulterande header-objektet returneras. Alla byte med surrogatförkortning omvandlas till glyfen för okända tecken i Unicode.

fold(name, value)

Header-folding styrs av policyinställningen refold_source. Ett värde anses vara ett ”källvärde” om och endast om det inte har attributet name (om det har attributet name betyder det att det är ett rubrikobjekt av något slag). Om ett källvärde behöver vikas om enligt policyn konverteras det till ett rubrikobjekt genom att name och value med eventuella CR- och LF-tecken borttagna skickas till header_factory. Fällning av ett header-objekt görs genom att anropa dess fold-metod med den aktuella policyn.

Källvärden delas upp i rader med hjälp av splitlines(). Om värdet inte ska vikas om, sätts raderna ihop igen med hjälp av linesep från policyn och returneras. Undantaget är rader som innehåller binärdata som inte är ascii. I så fall viks värdet om oavsett inställningen för refold_source, vilket gör att binärdata CTE-kodas med teckenuppsättningen unknown-8bit.

fold_binary(name, value)

Samma sak som fold() om cte_type är 7bit, förutom att det returnerade värdet är bytes.

Om cte_type är 8bit konverteras binärdata som inte är ASCII tillbaka till bytes. Rubriker med binära data viks inte om, oavsett inställningen refold_header, eftersom det inte finns något sätt att veta om de binära data består av tecken med en byte eller tecken med flera bytes.

Följande instanser av EmailPolicy ger standardvärden som är lämpliga för specifika applikationsdomäner. Observera att i framtiden kan beteendet hos dessa instanser (i synnerhet HTTP-instansen) komma att justeras så att de i ännu högre grad överensstämmer med de RFC som är relevanta för deras domäner.

email.policy.default

En instans av EmailPolicy med alla standardvärden oförändrade. Denna policy använder Pythons standardradavslut \n istället för det RFC-korrekta \r\n.

email.policy.SMTP

Lämplig för serialisering av meddelanden i enlighet med RFC:erna för e-post. Som default, men med linesep satt till r\n, vilket är RFC-kompatibelt.

email.policy.SMTPUTF8

Samma som SMTP förutom att utf8 är True. Användbar för serialisering av meddelanden till en meddelandelagring utan att använda kodade ord i rubrikerna. Bör endast användas för SMTP-överföring om avsändar- eller mottagaradresserna har icke-ASCII-tecken (metoden smtplib.SMTP.send_message() hanterar detta automatiskt).

email.policy.HTTP

Lämplig för serialisering av headers för användning i HTTP-trafik. Som SMTP förutom att max_line_length är satt till None (obegränsad).

email.policy.strict

Bekvämlighetsinstans. Samma som default förutom att raise_on_defect är satt till True. Detta gör att alla policyer kan göras strikta genom att skriva:

somepolicy + policy.strict

Med alla dessa EmailPolicies ändras det effektiva API:et för e-postpaketet från Python 3.2 API på följande sätt:

  • Om du anger en header för en Message analyseras headern och ett header-objekt skapas.

  • Att hämta ett rubrikvärde från en Message resulterar i att rubriken analyseras och att ett rubrikobjekt skapas och returneras.

  • Varje rubrikobjekt, eller varje rubrik som viks om på grund av policyinställningarna, viks med hjälp av en algoritm som fullt ut implementerar RFC-vikningsalgoritmerna, inklusive att veta var kodade ord krävs och tillåts.

Ur programmets synvinkel innebär detta att varje header som erhålls genom EmailMessage är ett headerobjekt med extra attribut, vars strängvärde är headerns fullständigt avkodade unicode-värde. På samma sätt kan ett huvud tilldelas ett nytt värde, eller ett nytt huvud skapas, med hjälp av en unicode-sträng, och policyn tar hand om att konvertera unicode-strängen till rätt RFC-kodad form.

Header-objekten och deras attribut beskrivs i headerregistry.

class email.policy.Compat32(**kw)

Denna konkreta Policy är policyn för bakåtkompatibilitet. Den replikerar beteendet hos email-paketet i Python 3.2. Modulen policy definierar också en instans av denna klass, compat32, som används som standardpolicy. Standardbeteendet för e-postpaketet är alltså att upprätthålla kompatibilitet med Python 3.2.

Följande attribut har värden som skiljer sig från standardvärdet för Policy:

mangle_from_

Standardvärdet är True.

Klassen tillhandahåller följande konkreta implementationer av de abstrakta metoderna i Policy:

header_source_parse(sourcelines)

Namnet parsas som allt upp till ’:’ och returneras oförändrat. Värdet bestäms genom att ta bort ledande blanksteg från återstoden av den första raden, sammanfoga alla efterföljande rader och ta bort eventuella efterföljande tecken för vagnsretur eller radmatning.

header_store_parse(name, value)

Namn och värde returneras oförändrade.

header_fetch_parse(name, value)

Om värdet innehåller binära data konverteras det till ett Header-objekt med teckenuppsättningen unknown-8bit. Annars returneras det oförändrat.

fold(name, value)

Rubrikerna viks med hjälp av Header-vikningsalgoritmen, som bevarar befintliga radbrytningar i värdet och viker varje resulterande rad till max_line_length. Icke-ASCII binärdata CTE-kodas med hjälp av teckenuppsättningen unknown-8bit.

fold_binary(name, value)

Rubriker viks med hjälp av Header-vikningsalgoritmen, som bevarar befintliga radbrytningar i värdet och viker varje resulterande rad till max_line_length. Om cte_type är 7bit, CTE-kodas binära data som inte är ascii med hjälp av teckenuppsättningen unknown-8bit. I annat fall används det ursprungliga källhuvudet, med befintliga radbrytningar och eventuella (RFC ogiltiga) binära data som det kan innehålla.

email.policy.compat32

En instans av Compat32, som ger bakåtkompatibilitet med beteendet hos e-postpaketet i Python 3.2.

Fotnoter