email.utils: Diverse verktyg

Källkod: Lib/email/utils.py

Det finns ett par användbara verktyg i modulen email.utils:

email.utils.localtime(dt=None)

Returnerar lokal tid som ett medvetet datetime-objekt. Om den anropas utan argument, returneras aktuell tid. Annars bör dt-argumentet vara en datetime-instans, och den konverteras till den lokala tidszonen enligt systemets tidszonsdatabas. Om dt är naiv (det vill säga, dt.tzinfo är None), antas den vara i lokal tid.

Tillagd i version 3.3.

Deprecated since version 3.12, removed in version 3.14: Parametern isdst.

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

Returnerar en sträng som passar för ett RFC 2822-kompatibelt Message-ID-huvud. Valfri idstring om den anges, är en sträng som används för att stärka det unika i meddelandets id. Valfri domain om den anges, anger den del av msgid som kommer efter ”@”. Standardvärdet är det lokala värdnamnet. Det är normalt inte nödvändigt att åsidosätta denna standard, men det kan vara användbart i vissa fall, t.ex. i ett distribuerat system som använder ett konsekvent domännamn på flera värdar.

Ändrad i version 3.2: Nyckelordet domain har lagts till.

De återstående funktionerna är en del av det äldre (Compat32) e-post-API:et. Det finns inget behov av att direkt använda dessa med det nya API:et, eftersom den parsning och formatering som de tillhandahåller görs automatiskt av det nya API:ets maskineri för parsning av rubriker.

email.utils.quote(str)

Returnerar en ny sträng med bindestreck i str ersatta av två bindestreck och dubbla citattecken ersatta av backslash-dubbla citattecken.

email.utils.unquote(str)

Returnerar en ny sträng som är en okvoterad version av str. Om str börjar och slutar med dubbla citattecken tas de bort. Likaså om str slutar och börjar med vinkelparenteser, tas de bort.

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

Analyserar adressen – som bör vara värdet i ett adressinnehållande fält som To eller Cc – i dess beståndsdelar realname och email address. Returnerar en tupel av denna information, såvida inte parsen misslyckas, i vilket fall en 2-tupel av ('', '') returneras.

Om strict är true, använd en strikt parser som avvisar felaktiga inmatningar.

Ändrad i version 3.13: Lägg till strict valfri parameter och avvisa felaktiga inmatningar som standard.

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

Detta är inversen av parseaddr() och tar en 2-tupel av formen (realname, email_address) och returnerar det strängvärde som passar för en To eller Cc header. Om det första elementet i pair är falskt returneras det andra elementet oförändrat.

Valfri charset är den teckenuppsättning som kommer att användas i RFC 2047-kodningen av realname om realname innehåller icke-ASCII-tecken. Kan vara en instans av str eller en Charset. Standardvärdet är utf-8.

Ändrad i version 3.3: Alternativet charset har lagts till.

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

Denna metod returnerar en lista med 2-tuples av den form som returneras av parseaddr(). fieldvalues är en sekvens av värden för rubrikfält som kan returneras av Message.get_all.

Om strict är true, använd en strikt parser som avvisar felaktiga inmatningar.

Här är ett enkelt exempel som hämtar alla mottagare av ett meddelande:

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)

Ändrad i version 3.13: Lägg till strict valfri parameter och avvisa felaktiga inmatningar som standard.

email.utils.parsedate(date)

Försöker tolka ett datum enligt reglerna i RFC 2822. Vissa utskick följer dock inte formatet som det är specificerat, så parsedate() försöker gissa rätt i sådana fall. date är en sträng som innehåller ett RFC 2822 datum, till exempel "Mon, 20 Nov 1995 19:12:08 -0500". Om den lyckas analysera datumet returnerar parsedate() en 9-tupel som kan skickas direkt till time.mktime(); annars returneras None. Observera att index 6, 7 och 8 i resultattupeln inte är användbara.

email.utils.parsedate_tz(date)

Utför samma funktion som parsedate(), men returnerar antingen None eller en 10-tupel; de första 9 elementen utgör en tupel som kan skickas direkt till time.mktime(), och det tionde är förskjutningen av datumets tidszon från UTC (som är den officiella termen för Greenwich Mean Time) [1]. Om indatasträngen inte har någon tidszon är det sista elementet i den tupel som returneras 0, vilket representerar UTC. Observera att index 6, 7 och 8 i resultattupeln inte är användbara.

email.utils.parsedate_to_datetime(date)

Inversen av format_datetime(). Utför samma funktion som parsedate(), men vid framgång returneras en datetime; annars uppstår ValueError om date innehåller ett ogiltigt värde, t.ex. en timme större än 23 eller en tidszonsförskjutning som inte är mellan -24 och 24 timmar. Om indatadatumet har en tidszon på -0000 kommer datetime att vara en naiv datetime, och om datumet överensstämmer med RFC kommer det att representera en tid i UTC men utan någon indikation på den faktiska källtidszonen för meddelandet som datumet kommer från. Om indatadatumet har någon annan giltig tidszonsförskjutning, kommer datetime att vara en medveten datetime med motsvarande a timezone tzinfo.

Tillagd i version 3.3.

email.utils.mktime_tz(tuple)

Gör om en 10-tupel som returneras av parsedate_tz() till en UTC-tidsmarkör (sekunder sedan epoken). Om tidszonsobjektet i tupeln är None, antas lokal tid.

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

Returnerar en datumsträng enligt RFC 2822, t.ex.:

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

Valfri timeval om den ges är ett tidsvärde med flyttal som accepteras av time.gmtime() och time.localtime(), annars används aktuell tid.

Valfri localtime är en flagga som när den är True tolkar timeval och returnerar ett datum i förhållande till den lokala tidszonen istället för UTC, med korrekt hänsyn till sommartid. Standardvärdet är False, vilket innebär att UTC används.

Valfri usegmt är en flagga som när den är True, matar ut en datumsträng med tidszonen som en ascii-sträng GMT, snarare än en numerisk -0000. Detta behövs för vissa protokoll (t.ex. HTTP). Detta gäller endast när localtime är False. Standardvärdet är False.

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

Som formatdate, men indata är en datetime-instans. Om det är en naiv datatid antas den vara ”UTC utan information om källans tidszon” och den konventionella -0000 används för tidszonen. Om det är en medveten datetime används den numeriska tidszonsförskjutningen. Om det är en medveten tidszon med offset noll, kan usegmt sättas till True, i vilket fall strängen GMT används istället för den numeriska tidszonsförskjutningen. Detta ger ett sätt att generera standardkonforma HTTP-datahuvuden.

Tillagd i version 3.3.

email.utils.decode_rfc2231(s)

Avkoda strängen s enligt RFC 2231.

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

Kodar strängen s enligt RFC 2231. De valfria charset och language, om de anges, är namnet på den teckenuppsättning och det språk som ska användas. Om inget av dessa anges returneras s i befintligt skick. Om charset anges men inte language, kodas strängen med hjälp av den tomma strängen för language.

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

När en rubrikparameter är kodad i RFC 2231-format kan Message.get_param returnera en 3-tupel som innehåller teckenuppsättning, språk och värde. collapse_rfc2231_value() omvandlar detta till en unicode-sträng. Den valfria errors skickas till errors-argumentet i str encode()-metoden; standardvärdet är 'replace'. Valfri fallback_charset anger den teckenuppsättning som ska användas om den i RFC 2231-huvudet inte är känd av Python; standard är 'us-ascii'.

För enkelhetens skull, om värdet som skickas till collapse_rfc2231_value() inte är en tupel, bör det vara en sträng och den returneras utan citat.

email.utils.decode_params(params)

Avkodar parameterlista enligt RFC 2231. params är en sekvens av 2-tupler som innehåller element av formen (content-type, string-value).

Fotnoter