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
ellerNone
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()
ochutf8
nedan för undantag), men kroppsdelar kan använda8bit
CTE.Ett
cte_type
-värde på8bit
fungerar bara medBytesGenerator
, inte medGenerator
, eftersom strängar inte kan innehålla binära data. Om enGenerator
arbetar under en policy som angercte_type=8bit
, kommer den att fungera som omcte_type
är7bit
.
- raise_on_defect¶
Om
True
, kommer alla defekter som påträffas att tas upp som fel. OmFalse
(standard), kommer defekter att skickas till metodenregister_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 fallMessage
används.Tillagd i version 3.6.
- verify_generated_headers¶
Om
True
(standard), genererar generatornHeaderWriteError
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 modulenemail
.Eftersom det är en säkerhetsfunktion är standardvärdet
True
även i policynCompat32
. För bakåtkompatibelt, men osäkert, beteende måste det uttryckligen sättas tillFalse
.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 ärTrue
, tas defect upp som ett undantag. Om den ärFalse
(standard), skickas obj och defect tillregister_defect()
.
- register_defect(obj, defect)¶
Registrera en defekt på obj. I e-postpaketet kommer defect alltid att vara en underklass till
MessageDefect
.Standardimplementeringen anropar metoden
append
i attributetdefects
i obj. När e-postpaketet anroparhandle_defect
kommer obj normalt att ha ettdefects
-attribut som har enappend
-metod. Anpassade objekttyper som används med e-postpaketet (t.ex. anpassadeMessage
-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
- ellerMessage
-objekt. Om det returnerade värdet inte är0
ellerNone
, och det redan finns ett antal headers med namnet name som är större än eller lika med det returnerade värdet, skapas ettValueError
.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 ettMessage
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 iMessage
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 ettMessage
som skapats av en parser). Metoden bör returnera den tupel(namn, värde)
som skall lagras iMessage
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 iMessage
; 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 infogalinesep
-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.
- 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
ärEmailMessage
.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”. IfTrue
, follow RFC 6532 and useutf-8
encoding for headers. Meddelanden som formaterats på detta sätt kan skickas till SMTP-servrar som har stöd för tilläggetSMTPUTF8
(RFC 6531).
- refold_source¶
Om värdet för en rubrik i objektet
Message
härrör från enparser`
(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 omall
alla värden omformuleras.
Standardvärdet är
long
.
- header_factory¶
En anropsbar funktion som tar två argument,
name
ochvalue
, därname
är ett namn på ett rubrikfält ochvalue
är ett värde på ett ovikt rubrikfält, och returnerar en strängunderklass som representerar rubriken. En standardheader_factory
(seheaderregistry
) 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()
ellerset_content()
i ettEmailMessage
-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 ärcontent_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 tillheader_factory
och det resulterande header-objektet returneras som värde. I detta fall uppstår ettValueError
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 tillheader_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 attributetname
(om det har attributetname
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 tillheader_factory
. Fällning av ett header-objekt görs genom att anropa dessfold
-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 avlinesep
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örrefold_source
, vilket gör att binärdata CTE-kodas med teckenuppsättningenunknown-8bit
.
- fold_binary(name, value)¶
Samma sak som
fold()
omcte_type
är7bit
, förutom att det returnerade värdet är bytes.Om
cte_type
är8bit
konverteras binärdata som inte är ASCII tillbaka till bytes. Rubriker med binära data viks inte om, oavsett inställningenrefold_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 medlinesep
satt tillr\n
, vilket är RFC-kompatibelt.
- email.policy.SMTPUTF8¶
Samma som
SMTP
förutom attutf8
ärTrue
. 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 (metodensmtplib.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 attmax_line_length
är satt tillNone
(obegränsad).
- email.policy.strict¶
Bekvämlighetsinstans. Samma som
default
förutom attraise_on_defect
är satt tillTrue
. 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. Modulenpolicy
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ättningenunknown-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 tillmax_line_length
. Icke-ASCII binärdata CTE-kodas med hjälp av teckenuppsättningenunknown-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 tillmax_line_length
. Omcte_type
är7bit
, CTE-kodas binära data som inte är ascii med hjälp av teckenuppsättningenunknown-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