`imaplib` — IMAP4-protokollklient¶

Källkod: Lib/imaplib.py

Denna modul definierar tre klasser, IMAP4, IMAP4_SSL och IMAP4_stream, som kapslar in en anslutning till en IMAP4-server och implementerar en stor del av IMAP4rev1-klientprotokollet enligt definitionen i RFC 2060. Den är bakåtkompatibel med IMAP4 (RFC 1730) servrar, men observera att kommandot STATUS inte stöds i IMAP4.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Tre klasser tillhandahålls av modulen imaplib, varav IMAP4 är basklassen:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶

Denna klass implementerar det faktiska IMAP4-protokollet. Anslutningen skapas och protokollversionen (IMAP4 eller IMAP4rev1) bestäms när instansen initialiseras. Om host inte specificeras används '' (den lokala värden). Om port utelämnas används IMAP4:s standardport (143). Den valfria parametern timeout anger en timeout i sekunder för anslutningsförsöket. Om timeout inte anges eller är None används den globala standardtimeouten för socket.

Klassen IMAP4 har stöd för with-satsen. När det används på detta sätt utfärdas IMAP4-kommandot LOGOUT automatiskt när with-satsen avslutas. T.ex.:

>>> from imaplib import IMAP4
>>> with IMAP4("domain.org") as M:
...     M.noop()
...
('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])

Ändrad i version 3.5: Stöd för with statement har lagts till.

Ändrad i version 3.9: Den valfria parametern timeout har lagts till.

Tre undantag är definierade som attribut för klassen IMAP4:

exception IMAP4.error¶: Undantag som uppstår vid eventuella fel. Anledningen till undantaget skickas till konstruktören som en sträng.

exception IMAP4.abort¶: Fel i IMAP4-servern orsakar att detta undantag tas upp. Detta är en subklass av IMAP4.error. Observera att om du stänger instansen och instansierar en ny, kommer du vanligtvis att kunna återhämta dig från detta undantag.

exception IMAP4.readonly¶: Detta undantag uppstår när en skrivbar brevlåda har fått sin status ändrad av servern. Detta är en underklass till IMAP4.error. Någon annan klient har nu skrivbehörighet och brevlådan måste öppnas på nytt för att återfå skrivbehörighet.

Det finns också en underklass för säkra anslutningar:

class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)¶

Detta är en underklass till IMAP4 som ansluter via en SSL-krypterad socket (för att använda den här klassen behöver du en socketmodul som kompilerats med SSL-stöd). Om host inte anges används '' (den lokala värden). Om port utelämnas används standardporten för IMAP4-over-SSL (993). ssl_context är ett ssl.SSLContext-objekt som gör det möjligt att samla SSL-konfigurationsalternativ, certifikat och privata nycklar i en enda (potentiellt långlivad) struktur. Läs Överväganden om säkerhet för bästa praxis.

Den valfria parametern timeout anger en timeout i sekunder för anslutningsförsöket. Om timeout inte anges eller är None används den globala standardtimeouten för socket.

Ändrad i version 3.3: parametern ssl_context har lagts till.

Ändrad i version 3.4: Klassen stöder nu kontroll av värdnamn med ssl.SSLContext.check_hostname och Server Name Indication (se ssl.HAS_SNI).

Ändrad i version 3.9: Den valfria parametern timeout har lagts till.

Ändrad i version 3.12: De föråldrade parametrarna keyfile och certfile har tagits bort.

Den andra underklassen tillåter anslutningar som skapas av en underordnad process:

class imaplib.IMAP4_stream(command)¶: Detta är en underklass som härrör från IMAP4 som ansluter till filbeskrivarna stdin/stdout som skapas genom att skicka command till subprocess.Popen().

Följande nyttofunktioner definieras:

imaplib.Internaldate2tuple(datestr)¶: Analyserar en IMAP4 INTERNALDATE-sträng och returnerar motsvarande lokal tid. Returvärdet är en tupel av time.struct_time eller None om strängen har fel format.

imaplib.Int2AP(num)¶: Konverterar ett heltal till en bytesrepresentation med hjälp av tecken från uppsättningen [A .. P].

imaplib.ParseFlags(flagstr)¶: Konverterar ett IMAP4 FLAGS-svar till en tupel av individuella flaggor.

imaplib.Time2Internaldate(date_time)¶: Konverterar date_time till en IMAP4 INTERNALDATE representation. Returvärdet är en sträng i formen: "DD-Mmm-YYYY HH:MM:SS +HHMM" (inklusive dubbla citattecken). Argumentet date_time kan vara ett tal (int eller float) som representerar sekunder sedan epok (som returneras av time.time()), en 9-tupel som representerar lokal tid, en instans av time.struct_time (som returneras av time.localtime()), en medveten instans av datetime.datetime eller en sträng med dubbla citattecken. I det sista fallet antas den redan vara i rätt format.

Observera att IMAP4-meddelandenumren ändras när brevlådan ändras; i synnerhet efter att ett EXPUNGE-kommando har raderat meddelanden numreras de återstående meddelandena om. Det är därför mycket lämpligt att använda UID:er i stället, med kommandot UID.

I slutet av modulen finns ett testavsnitt som innehåller ett mer omfattande exempel på användning.

Se även

Dokument som beskriver protokollet, källor för servrar som implementerar det, från University of Washingtons IMAP Information Center finns alla på (Source Code) https://github.com/uw-imap/imap (Not Maintained).

IMAP4-objekt¶

Alla IMAP4rev1-kommandon representeras av metoder med samma namn, antingen stora eller små bokstäver.

Alla argument till kommandon konverteras till strängar, utom för AUTHENTICATE och det sista argumentet till APPEND som skickas som en IMAP4-litteral. Om det behövs (strängen innehåller IMAP4-protokollkänsliga tecken och är inte omsluten av parenteser eller dubbla citattecken) citeras varje sträng. Argumentet password till kommandot LOGIN är dock alltid citerat. Om du vill undvika att en argumentsträng citeras (t.ex. argumentet flags i kommandot STORE) ska du sätta strängen inom parentes (t.ex. r'(\Deleted)').

De flesta kommandon returnerar en tupel: (typ, [data, ...]) där typ vanligtvis är 'OK' eller 'NO', och data är antingen texten från kommandosvaret eller obligatoriska resultat från kommandot. Varje data är antingen en bytes eller en tupel. Om det är en tupel är den första delen svarets rubrik och den andra delen innehåller data (dvs. ett ”bokstavligt” värde).

Alternativen message_set till kommandona nedan är en sträng som anger ett eller flera meddelanden som ska åtgärdas. Det kan vara ett enkelt meddelandenummer ('1'), ett intervall av meddelandenummer ('2:4') eller en grupp av icke sammanhängande intervall separerade med kommatecken ('1:3,6:9'). Ett intervall kan innehålla en asterisk för att ange en oändlig övre gräns ('3:*').

En instans av IMAP4 har följande metoder:

IMAP4.append(mailbox, flags, date_time, message)¶: Lägg till meddelande i en namngiven brevlåda.

IMAP4.authenticate(mechanism, authobject)¶

Autentiseringskommando — kräver svarsbehandling.

mechanism anger vilken autentiseringsmekanism som ska användas - den ska finnas i instansvariabeln capabilities i formen AUTH=mechanism.

authobject måste vara ett anropsbart objekt:

data = authobject(response)

Den kommer att anropas för att bearbeta serverns fortsättningssvar; argumentet response som den får är bytes. Den bör returnera bytes data som kommer att base64-kodas och skickas till servern. Den ska returnera None om klientens avbrottssvar * ska skickas istället.

Ändrad i version 3.5: stränganvändarnamn och lösenord kodas nu till utf-8 istället för att begränsas till ASCII.

IMAP4.check()¶: Checkpoint-brevlåda på server.

IMAP4.close()¶: Stäng aktuell vald brevlåda. Raderade meddelanden tas bort från den skrivbara brevlådan. Detta är det rekommenderade kommandot före LOGOUT.

IMAP4.copy(message_set, new_mailbox)¶: Kopiera message_set meddelanden till slutet av new_mailbox.

IMAP4.create(mailbox)¶: Skapa en ny brevlåda med namnet brevlåda.

IMAP4.delete(mailbox)¶: Ta bort en gammal brevlåda med namnet brevlåda.

IMAP4.deleteacl(mailbox, who)¶: Ta bort de ACL:er (ta bort alla rättigheter) som angetts för vem i brevlådan.

IMAP4.enable(capability)¶: Aktivera funktion (se RFC 5161). De flesta funktioner behöver inte aktiveras. För närvarande stöds endast UTF8=ACCEPT-funktionen (se RFC 6855).

Tillagd i version 3.5: Själva metoden enable() och stöd för RFC 6855.

IMAP4.expunge()¶: Ta bort raderade objekt permanent från vald brevlåda. Genererar ett EXPUNGE-svar för varje borttaget meddelande. Returnerade data innehåller en lista över meddelandenumren för EXPUNGE i den ordning de mottagits.

IMAP4.fetch(message_set, message_parts)¶: Hämta (delar av) meddelanden. message_parts ska vara en sträng med namn på meddelandedelar inom parentes, t.ex.: "(UID BODY[TEXT])". Data som returneras är tupler av kuvert och data för meddelandedelar.

IMAP4.getacl(mailbox)¶: Hämta ACL för mailbox. Metoden är inte standard, men stöds av Cyrus-servern.

IMAP4.getannotation(mailbox, entry, attribute)¶: Hämtar angivna ANNOTATION för mailbox. Metoden är inte standard, men stöds av Cyrus-servern.

IMAP4.getquota(root)¶: Hämta quota root:s resursanvändning och begränsningar. Den här metoden är en del av IMAP4 QUOTA-tillägget som definieras i rfc2087.

IMAP4.getquotaroot(mailbox)¶: Hämta listan över quota roots för den namngivna mailbox. Denna metod är en del av IMAP4 QUOTA-tillägget som definieras i rfc2087.

IMAP4.idle(duration=None)¶

Returnera en Idler: en iterabel kontexthanterare som implementerar IMAP4-kommandot IDLE enligt definitionen i RFC 2177.

Det returnerade objektet skickar kommandot IDLE när det aktiveras av with-satsen, producerar IMAP-svar utan taggar via iterator-protokollet och skickar DONE när kontexten avslutas.

Alla omärkta svar som anländer efter att kommandot IDLE har skickats (inklusive de som anländer innan servern bekräftar kommandot) kommer att vara tillgängliga via iteration. Eventuella kvarvarande svar (de som inte har itererats i with-kontexten) kan hämtas på vanligt sätt efter att IDLE har avslutats, med IMAP4.response().

Svaren representeras som (typ, [data, ...])-tupler, enligt beskrivningen i IMAP4 Objects.

Argumentet duration anger en maximal tid (i sekunder) för tomgångskörning, varefter alla pågående iterationer stoppas. Det kan vara en int eller float, eller None för ingen tidsgräns. Anropare som vill undvika tidsgränser för inaktivitet på servrar som inför dem bör hålla detta till högst 29 minuter (1740 sekunder). Kräver en socket-anslutning; duration måste vara None på IMAP4_stream-anslutningar.

>>> with M.idle(duration=29 * 60) as idler:
...     for typ, data in idler:
...         print(typ, data)
...
EXISTS [b'1']
RECENT [b'1']

Idler.burst(interval=0.1)¶

Ger en serie svar med högst intervall sekunders mellanrum (uttryckt som en int eller float).

Denna generator är ett alternativ till att iterera ett svar i taget och är avsedd att underlätta effektiv batchbearbetning. Den hämtar nästa svar tillsammans med alla omedelbart tillgängliga efterföljande svar. (Till exempel en snabb serie med EXPUNGE-svar efter en massradering)

Kräver en socket-anslutning; fungerar inte på IMAP4_stream-anslutningar.

>>> with M.idle() as idler:
...     # get a response and any others following by < 0.1 seconds
...     batch = list(idler.burst())
...     print(f'processing {len(batch)} responses...')
...     print(batch)
...
processing 3 responses...
[('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

Tips

IDLE kontextens maximala varaktighet, som skickas till IMAP4.idle(), respekteras när man väntar på det första svaret i en burst. Därför kommer en utgången Idler att få denna generator att återvända omedelbart utan att producera något. Anropare bör tänka på detta om de använder den i en loop.

Anteckning

Den iterator som returneras av IMAP4.idle() är endast användbar i en with-sats. Före eller efter det sammanhanget samlas oönskade svar in internt när ett kommando avslutas och kan hämtas med IMAP4.response().

Anteckning

Klassnamnet och strukturen för Idler är interna gränssnitt som kan komma att ändras. Anropande kod kan förlita sig på att dess kontexthantering, iteration och offentliga metod förblir stabil, men bör inte subklassa, instansiera, jämföra eller på annat sätt direkt referera till klassen.

Tillagd i version 3.14.

IMAP4.list([directory[, pattern]])¶: Lista namn på brevlådor i katalog som matchar mönster. directory är som standard e-postmappen på högsta nivån och pattern är som standard att matcha vad som helst. Returnerade data innehåller en lista med LIST-svar.

IMAP4.login(user, password)¶: Identifiera klienten med hjälp av ett lösenord i klartext. Lösenordet kommer att citeras.

IMAP4.login_cram_md5(user, password)¶: Tvinga fram användning av CRAM-MD5-autentisering när klienten identifieras för att skydda lösenordet. Fungerar endast om serverns CAPABILITY-svar innehåller frasen AUTH=CRAM-MD5.

IMAP4.logout()¶: Stänger av anslutningen till servern. Returnerar serverns BYE-svar.

Ändrad i version 3.8: Metoden ignorerar inte längre godtyckliga undantag i tysthet.

IMAP4.lsub(directory='""', pattern='*')¶: Lista namn på prenumererade brevlådor i en katalog som matchar ett mönster. directory är standard för katalogen på högsta nivån och pattern är standard för att matcha alla brevlådor. Returnerade data är tupler av meddelandedel kuvert och data.

IMAP4.myrights(mailbox)¶: Visa mina ACL:er för en brevlåda (dvs. de rättigheter som jag har för brevlådan).

IMAP4.namespace()¶: Returnerar IMAP-namnrymder enligt definitionen i RFC 2342.

IMAP4.noop()¶: Skicka NOOP till servern.

IMAP4.open(host, port, timeout=None)¶

Öppnar socket till port på host. Den valfria parametern timeout anger en timeout i sekunder för anslutningsförsöket. Om timeout inte anges eller är None används den globala standardtimeouten för socket. Observera också att om parametern timeout sätts till noll kommer den att ge upphov till ett ValueError för att avvisa skapandet av en icke-blockerande socket. Denna metod anropas implicit av IMAP4-konstruktören. De anslutningsobjekt som upprättas med den här metoden kommer att användas i metoderna IMAP4.read(), IMAP4.readline(), IMAP4.send() och IMAP4.shutdown(). Du kan åsidosätta denna metod.

Utlöser en auditing event imaplib.open med argumenten self, host, port.

Ändrad i version 3.9: Parametern timeout har lagts till.

IMAP4.partial(message_num, message_part, start, length)¶: Hämtar en avkortad del av ett meddelande. Returnerade data är en tupel av meddelandets delkuvert och data.

IMAP4.proxyauth(user)¶: Anta autentisering som användare. Tillåter en behörig administratör att använda proxy för att komma åt en användares brevlåda.

IMAP4.read(size)¶: Läser storlek byte från fjärrservern. Du kan åsidosätta den här metoden.

IMAP4.readline()¶: Läser en rad från fjärrservern. Du kan åsidosätta den här metoden.

IMAP4.recent()¶: Frågar servern om en uppdatering. Returnerad data är None om inga nya meddelanden, annars värdet av RECENT svaret.

IMAP4.rename(oldmailbox, newmailbox)¶: Byt namn på brevlådan oldmailbox till newmailbox.

IMAP4.response(code)¶: Returnerar data för svaret code om det mottagits, eller None. Returnerar den angivna koden, istället för den vanliga typen.

IMAP4.search(charset, criterion[, ...])¶

Sök efter matchande meddelanden i brevlådan. charset kan vara None, i vilket fall ingen CHARSET kommer att anges i begäran till servern. IMAP-protokollet kräver att minst ett kriterium anges; ett undantag kommer att göras om servern returnerar ett fel. charset måste vara None om funktionen UTF8=ACCEPT aktiverades med kommandot enable().

Exempel:

# M is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select(mailbox='INBOX', readonly=False)¶: Välj en brevlåda. Data som returneras är antalet meddelanden i mailbox (svar EXISTS). Standardvärdet för brevlåda är 'INBOX'. Om flaggan readonly är inställd är det inte tillåtet att ändra i brevlådan.

IMAP4.send(data)¶

Skickar data till fjärrservern. Du kan åsidosätta den här metoden.

Utlöser en auditing event imaplib.send med argumenten self, data.

IMAP4.setacl(mailbox, who, what)¶: Ställ in en ACL för mailbox. Metoden är inte standard, men stöds av Cyrus-servern.

IMAP4.setannotation(mailbox, entry, attribute[, ...])¶: Ställ in ANNOTATION för brevlåda. Metoden är inte standard, men stöds av Cyrus-servern.

IMAP4.setquota(root, limits)¶: Ställ in resursbegränsningarna för root quota. Denna metod är en del av IMAP4 QUOTA-tillägget som definieras i rfc2087.

IMAP4.shutdown()¶: Stäng anslutningen som upprättades i open. Den här metoden anropas implicit av IMAP4.logout(). Du kan åsidosätta den här metoden.

IMAP4.socket()¶: Returnerar den socket-instans som används för att ansluta till servern.

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶

Kommandot ort är en variant av search med sorteringssemantik för resultaten. Returnerade data innehåller en mellanslagsseparerad lista över matchande meddelandenummer.

Sort har två argument före search_criterion-argumenten: en lista med sort_criteria inom parentes och den sökta charset. Observera att till skillnad från search är argumentet charset obligatoriskt. Det finns också ett uid sort-kommando som motsvarar ort på samma sätt som uid search motsvarar search. Kommandot ort söker först igenom brevlådan efter meddelanden som matchar de angivna sökkriterierna med hjälp av argumentet charset för tolkning av strängar i sökkriterierna. Därefter returneras antalet matchande meddelanden.

Detta är ett tilläggskommando till IMAP4rev1.

IMAP4.starttls(ssl_context=None)¶: Skicka ett STARTTLS-kommando. Argumentet ssl_context är valfritt och bör vara ett ssl.SSLContext-objekt. Detta aktiverar kryptering på IMAP-anslutningen. Läs Överväganden om säkerhet för bästa praxis.

Tillagd i version 3.2.

Ändrad i version 3.4: Metoden stöder nu kontroll av värdnamn med ssl.SSLContext.check_hostname och Server Name Indication (se ssl.HAS_SNI).

IMAP4.status(mailbox, names)¶: Begär namngivna statusvillkor för mailbox.

IMAP4.store(message_set, command, flag_list)¶

Ändrar flaggdispositioner för meddelanden i brevlådan. command anges i avsnitt 6.4.6 i RFC 2060 som ett av ”FLAGS”, ”+FLAGS” eller ”-FLAGS”, eventuellt med suffixet ”.SILENT”.

Till exempel, för att sätta raderingsflaggan på alla meddelanden:

typ, data = M.search(None, 'ALL')
for num in data[0].split():
   M.store(num, '+FLAGS', '\\Deleted')
M.expunge()

Anteckning

Att skapa flaggor som innehåller ’]’ (till exempel: ”[test]”) bryter mot RFC 3501 (IMAP-protokollet). Imaplib har dock historiskt tillåtit skapandet av sådana taggar, och populära IMAP-servrar, som Gmail, accepterar och producerar sådana flaggor. Det finns icke-Python-program som också skapar sådana taggar. Även om det är en RFC-överträdelse och IMAP-klienter och -servrar ska vara strikta, fortsätter imaplib fortfarande att tillåta att sådana taggar skapas av bakåtkompatibilitetsskäl, och från och med Python 3.6 hanteras de om de skickas från servern, eftersom detta förbättrar kompatibiliteten i verkligheten.

IMAP4.subscribe(mailbox)¶: Prenumerera på ny brevlåda.

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])¶

Kommandot thread är en variant av search med trådningssemantik för resultaten. Data som returneras innehåller en mellanslagsseparerad lista över trådmedlemmar.

Trådmedlemmar består av noll eller flera meddelandenummer, avgränsade av mellanslag, som anger successiv förälder och barn.

Thread har två argument före search_criterion-argumenten: en threading_algoritm och den sökta charset. Observera att till skillnad från search är argumentet charset obligatoriskt. Det finns också ett uid thread-kommando som motsvarar thread på samma sätt som uid search motsvarar search. Kommandot thread söker först igenom brevlådan efter meddelanden som matchar de angivna sökkriterierna med hjälp av argumentet charset för tolkning av strängar i sökkriterierna. Därefter returneras de matchande meddelandena trådade enligt den angivna trådningsalgoritmen.

Detta är ett tilläggskommando till IMAP4rev1.

IMAP4.uid(command, arg[, ...])¶: Utför kommandot med meddelanden som identifieras med UID i stället för meddelandenummer. Returnerar svar som är lämpligt för kommandot. Minst ett argument måste anges; om inget anges kommer servern att returnera ett fel och ett undantag kommer att tas upp.

IMAP4.unsubscribe(mailbox)¶: Avregistrera dig från gammal brevlåda.

IMAP4.unselect()¶: imaplib.IMAP4.unselect() frigör serverns resurser som är associerade med den valda brevlådan och återställer servern till det autentiserade tillståndet. Det här kommandot utför samma åtgärder som imaplib.IMAP4.close(), förutom att inga meddelanden tas bort permanent från den valda brevlådan.

Tillagd i version 3.9.

IMAP4.xatom(name[, ...])¶: Tillåt enkla tilläggskommandon som meddelas av servern i CAPABILITY-svaret.

Följande attribut är definierade för instanser av IMAP4:

IMAP4.PROTOCOL_VERSION¶: Det senaste protokoll som stöds i svaret CAPABILITY från servern.

IMAP4.debug¶: Heltalsvärde för att styra felsökningsutmatningen. Initialiseringsvärdet hämtas från modulvariabeln Debug. Värden större än tre spårar varje kommando.

IMAP4.utf8_enabled¶: Booleskt värde som normalt är False, men som sätts till True om ett enable()-kommando framgångsrikt utfärdas för egenskapen UTF8=ACCEPT.

Tillagd i version 3.5.

IMAP4-exempel¶

Här är ett minimalt exempel (utan felkontroll) som öppnar en brevlåda och hämtar och skriver ut alla meddelanden:

import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
M.login(getpass.getuser(), getpass.getpass())
M.select()
typ, data = M.search(None, 'ALL')
for num in data[0].split():
    typ, data = M.fetch(num, '(RFC822)')
    print('Message %s\n%s\n' % (num, data[0][1]))
M.close()
M.logout()

`imaplib` — IMAP4-protokollklient¶

IMAP4-objekt¶

IMAP4-exempel¶

Innehåll

Föregående ämne

Nästa ämne

Denna sidan

imaplib — IMAP4-protokollklient¶

IMAP4-objekt¶

IMAP4-exempel¶

`imaplib` — IMAP4-protokollklient¶