imaplib
— IMAP4 protocol client¶
Вихідний код: Lib/imaplib.py
Цей модуль визначає три класи: IMAP4
, IMAP4_SSL
і IMAP4_stream
, які інкапсулюють підключення до сервера IMAP4 і реалізують велику підмножину клієнтського протоколу IMAP4rev1, як визначено в RFC 2060. Він зворотно сумісний із серверами IMAP4 (RFC 1730), але зауважте, що команда STATUS
не підтримується в IMAP4.
Availability: not WASI.
This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.
Три класи надаються модулем imaplib
, IMAP4
є базовим класом:
- class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶
This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If host is not specified,
''
(the local host) is used. If port is omitted, the standard IMAP4 port (143) is used. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or isNone
, the global default socket timeout is used.Клас
IMAP4
підтримує операторwith
. При такому використанні командаLOGOUT
IMAP4 виконується автоматично, коли завершується операторwith
. Наприклад:>>> from imaplib import IMAP4 >>> with IMAP4("domain.org") as M: ... M.noop() ... ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
Змінено в версії 3.5: Додано підтримку оператора
with
.Змінено в версії 3.9: Додано необов’язковий параметр timeout.
Три винятки визначено як атрибути класу IMAP4
:
- exception IMAP4.error¶
Виняток створено для будь-яких помилок. Причина винятку передається конструктору у вигляді рядка.
- exception IMAP4.abort¶
Помилки сервера IMAP4 призводять до виникнення цього винятку. Це підклас
IMAP4.error
. Зауважте, що закриття екземпляра та створення нового екземпляра зазвичай дозволяє відновлення після цього винятку.
- exception IMAP4.readonly¶
Цей виняток виникає, коли сервер змінює статус доступної для запису поштової скриньки. Це підклас
IMAP4.error
. Інший клієнт тепер має дозвіл на запис, і поштову скриньку потрібно буде повторно відкрити, щоб знову отримати дозвіл на запис.
Існує також підклас для безпечних з’єднань:
- class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)¶
Це підклас, похідний від
IMAP4
, який підключається через сокет, зашифрований SSL (щоб використовувати цей клас, вам потрібен модуль сокета, скомпільований із підтримкою SSL). Якщо host не вказано, використовується''
(локальний хост). Якщо порт не вказано, використовується стандартний порт IMAP4 через SSL (993). ssl_context — це об’єктssl.SSLContext
, який дозволяє об’єднувати параметри конфігурації SSL, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is
None
, the global default socket timeout is used.Змінено в версії 3.3: Додано параметр ssl_context.
Змінено в версії 3.4: The class now supports hostname check with
ssl.SSLContext.check_hostname
and Server Name Indication (seessl.HAS_SNI
).Змінено в версії 3.9: Додано необов’язковий параметр timeout.
Змінено в версії 3.12: The deprecated keyfile and certfile parameters have been removed.
Другий підклас дозволяє з’єднання, створені дочірнім процесом:
- class imaplib.IMAP4_stream(command)¶
Це підклас, похідний від
IMAP4
, який підключається до файлових дескрипторівstdin/stdout
, створених передачею команди доsubprocess.Popen()
.
Визначаються наступні функції корисності:
- imaplib.Internaldate2tuple(datestr)¶
Проаналізуйте рядок
INTERNALDATE
IMAP4 і поверніть відповідний місцевий час. Поверненим значенням єtime.struct_time
кортеж абоNone
, якщо рядок має неправильний формат.
- imaplib.Int2AP(num)¶
Перетворює ціле число на представлення байтів за допомогою символів із набору [
A
..P
].
- imaplib.ParseFlags(flagstr)¶
Перетворює відповідь
FLAGS
IMAP4 на кортеж окремих прапорів.
- imaplib.Time2Internaldate(date_time)¶
Перетворіть date_time на представлення
INTERNALDATE
IMAP4. Поверненим значенням є рядок у формі:"ДД-МММ-РРРР ГГ:ХМ:СС +ГГММ"
(включаючи подвійні лапки). Аргумент date_time може бути числом (int або float), що представляє секунди з епохи (як повертаєtime.time()
), 9-кортеж, що представляє місцевий час, екземплярtime.struct_time
(як повертаєtime.localtime()
), відомий екземплярdatetime.datetime
або рядок у подвійних лапках. В останньому випадку передбачається, що він уже має правильний формат.
Зверніть увагу, що номери повідомлень IMAP4 змінюються разом зі зміною поштової скриньки; зокрема, після видалення командою EXPUNGE
повідомлення, що залишилися, перенумеровуються. Тому вкрай доцільно використовувати натомість UID з командою UID.
Наприкінці модуля є тестовий розділ, який містить докладніший приклад використання.
Дивись також
Документи, що описують протокол, джерела для серверів, які його реалізують, Інформаційний центр IMAP Університету Вашингтона можна знайти за адресою (Вихідний код) https://github.com/uw-imap/imap (Не підтримується).
Об’єкти IMAP4¶
All IMAP4rev1 commands are represented by methods of the same name, either uppercase or lowercase.
Усі аргументи команд перетворюються на рядки, за винятком AUTHENTICATE
і останнього аргументу APPEND
, який передається як літерал IMAP4. Якщо необхідно (рядок містить чутливі до протоколу IMAP4 символи та не взятий ні в дужки, ні в подвійні лапки), кожен рядок береться в лапки. Однак аргумент password для команди LOGIN
завжди береться в лапки. Якщо ви хочете уникнути рядка аргументу в лапках (наприклад, аргумент flags для STORE
), то візьміть рядок у круглі дужки (наприклад: r'(\Deleted)'
).
Кожна команда повертає кортеж: (type, [data, ...])
, де type зазвичай 'OK''
або 'NO'
, а data є або текст із відповіді на команду або обов’язкові результати з команди. Кожні дані є або байтами
, або кортежем. Якщо кортеж, то перша частина є заголовком відповіді, а друга частина містить дані (тобто: «літеральне» значення).
Параметри message_set для наведених нижче команд — це рядок, що вказує на одне або кілька повідомлень, які потрібно виконати. Це може бути простий номер повідомлення ('1'
), діапазон номерів повідомлень ('2:4'
) або група несуміжних діапазонів, розділених комами ('1 :3,6:9''
). Діапазон може містити зірочку для позначення нескінченної верхньої межі ('3:*'
).
Екземпляр IMAP4
має такі методи:
- IMAP4.append(mailbox, flags, date_time, message)¶
Додайте повідомлення до вказаної поштової скриньки.
- IMAP4.authenticate(mechanism, authobject)¶
Команда автентифікації — вимагає обробки відповіді.
mechanism вказує, який механізм автентифікації буде використано - він має відображатися в змінній екземпляра
capabilities
у форміAUTH=mechanism
.authobject повинен бути викликаним об’єктом:
data = authobject(response)
Він буде викликаний для обробки відповідей продовження сервера; аргумент відповідь, який він передає, буде
байт
. Він має повернутибайти
дані, які будуть закодовані в base64 і надіслані на сервер. Він має повертатиNone
, якщо замість цього потрібно надіслати відповідь*
про переривання клієнта.Змінено в версії 3.5: рядкові імена користувачів і паролі тепер кодуються як
utf-8
замість обмеження ASCII.
- IMAP4.check()¶
Контрольна поштова скринька на сервері.
- IMAP4.close()¶
Закрити вибрану поштову скриньку. Видалені повідомлення видаляються з доступної для запису поштової скриньки. Це рекомендована команда перед
ВИХОДОМ
.
- IMAP4.copy(message_set, new_mailbox)¶
Скопіюйте повідомлення message_set у кінець new_mailbox.
- IMAP4.create(mailbox)¶
Створіть нову поштову скриньку з назвою mailbox.
- IMAP4.delete(mailbox)¶
Видалити стару поштову скриньку з назвою mailbox.
- IMAP4.deleteacl(mailbox, who)¶
Видалити списки керування доступом (вилучити будь-які права), встановлені для поштової скриньки who.
- IMAP4.enable(capability)¶
Увімкнути можливість (див. RFC 5161). Більшість можливостей не потрібно вмикати. Наразі підтримується лише можливість
UTF8=ACCEPT
(див. RFC 6855).
- IMAP4.expunge()¶
Назавжди видалити видалені елементи з вибраної поштової скриньки. Генерує відповідь
EXPUNGE
для кожного видаленого повідомлення. Повернуті дані містять список номерів повідомленьEXPUNGE
у порядку отримання.
- IMAP4.fetch(message_set, message_parts)¶
Отримати (частини) повідомлень. message_parts має бути рядком імен частин повідомлення, укладених у круглі дужки, наприклад:
"(UID BODY[TEXT])
. Повернуті дані – це кортежі конверта частини повідомлення та даних.
- IMAP4.getacl(mailbox)¶
Отримайте
ACL
для поштової скриньки. Метод нестандартний, але підтримується серверомCyrus
.
- IMAP4.getannotation(mailbox, entry, attribute)¶
Отримати вказані
АННОТАЦІЇ
для поштової скриньки. Метод нестандартний, але підтримується серверомCyrus
.
- IMAP4.getquota(root)¶
Отримайте
квоту
root щодо використання ресурсів і обмежень. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.
- IMAP4.getquotaroot(mailbox)¶
Отримайте список
квоти
roots
для вказаної поштової скриньки. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.
- IMAP4.list([directory[, pattern]])¶
Список імен поштових скриньок у каталозі, що відповідає шаблону. каталог за замовчуванням є текою електронної пошти верхнього рівня, а шаблон за замовчуванням відповідає будь-чому. Повернуті дані містять список відповідей
СПИСОК
.
- IMAP4.login(user, password)¶
Ідентифікуйте клієнта за допомогою відкритого пароля. Пароль буде взято в лапки.
- IMAP4.login_cram_md5(user, password)¶
Примусово використовувати автентифікацію
CRAM-MD5
під час ідентифікації клієнта, щоб захистити пароль. Працює, лише якщо відповідь сервераCAPABILITY
містить фразуAUTH=CRAM-MD5
.
- IMAP4.logout()¶
Вимкніть з’єднання з сервером. Повертає відповідь сервера
BYE
.Змінено в версії 3.8: Метод більше не ігнорує мовчки довільні винятки.
- IMAP4.lsub(directory='""', pattern='*')¶
Список імен передплачених поштових скриньок у каталозі, що відповідає шаблону. каталог за замовчуванням є каталогом верхнього рівня, а шаблон за замовчуванням відповідає будь-якій поштовій скриньці. Повернуті дані – це кортежі конверта частини повідомлення та даних.
- IMAP4.myrights(mailbox)¶
Показати мої ACL для поштової скриньки (тобто права, які я маю на поштову скриньку).
- IMAP4.noop()¶
Надіслати
NOOP
на сервер.
- IMAP4.open(host, port, timeout=None)¶
Opens socket to port at host. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is
None
, the global default socket timeout is used. Also note that if the timeout parameter is set to be zero, it will raise aValueError
to reject creating a non-blocking socket. This method is implicitly called by theIMAP4
constructor. The connection objects established by this method will be used in theIMAP4.read()
,IMAP4.readline()
,IMAP4.send()
, andIMAP4.shutdown()
methods. You may override this method.Викликає подію аудиту
imaplib.open
з аргументамиself
,host
,port
.Змінено в версії 3.9: Додано параметр timeout.
- IMAP4.partial(message_num, message_part, start, length)¶
Отримати скорочену частину повідомлення. Повернуті дані — це кортеж із конверта частини повідомлення та даних.
- IMAP4.proxyauth(user)¶
Припустити автентифікацію як користувача. Дозволяє авторизованому адміністратору надсилати проксі до поштової скриньки будь-якого користувача.
- IMAP4.read(size)¶
Читає size байти з віддаленого сервера. Ви можете змінити цей метод.
- IMAP4.readline()¶
Читає один рядок з віддаленого сервера. Ви можете змінити цей метод.
- IMAP4.recent()¶
Запитувати сервер для оновлення. Повернені дані:
None
, якщо немає нових повідомлень, інакше значення відповідіRECENT
.
- IMAP4.rename(oldmailbox, newmailbox)¶
Перейменуйте поштову скриньку з назвою oldmailbox на newmailbox.
- IMAP4.response(code)¶
Повернути дані для відповіді код, якщо отримано, або
None
. Повертає заданий код замість звичайного типу.
- IMAP4.search(charset, criterion[, ...])¶
Пошук поштової скриньки для відповідних повідомлень. charset може мати значення
None
, у цьому випадкуCHARSET
не буде вказано у запиті до сервера. Протокол IMAP вимагає вказівки принаймні одного критерію; виняток буде викликано, коли сервер повертає помилку. charset має бутиNone
, якщо можливістьUTF8=ACCEPT
було ввімкнено за допомогою командиenable()
.Приклад:
# 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)¶
Виберіть поштову скриньку. Повернені дані – це кількість повідомлень у поштовій скриньці (відповідь «ІСНУЄ»). Типовою поштовою скринькою є
'INBOX'
. Якщо встановлено прапорець readonly, зміни поштової скриньки заборонені.
- IMAP4.send(data)¶
Надсилає
дані
на віддалений сервер. Ви можете змінити цей метод.Викликає подію аудиту
imaplib.send
з аргументамиself
,data
.
- IMAP4.setacl(mailbox, who, what)¶
Установіть
ACL
для поштової скриньки. Метод нестандартний, але підтримується серверомCyrus
.
- IMAP4.setannotation(mailbox, entry, attribute[, ...])¶
Установіть
АННОТАЦІЮ
для поштової скриньки. Метод нестандартний, але підтримується серверомCyrus
.
- IMAP4.setquota(root, limits)¶
Встановіть ліміти ресурсів
квоти
root. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.
- IMAP4.shutdown()¶
Закрити з’єднання встановлено в
відкритому
. Цей метод неявно викликаєтьсяIMAP4.logout()
. Ви можете змінити цей метод.
- IMAP4.socket()¶
Повертає екземпляр сокета, який використовується для підключення до сервера.
- IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶
Команда
sort
є варіантомsearch
із семантикою сортування для результатів. Повернуті дані містять розділений пробілами список відповідних номерів повідомлень.Сортування має два аргументи перед аргументом(ами) критерій_пошуку; список критеріїв_сортування в дужках і пошуковий набір символів. Зауважте, що на відміну від
search
, пошуковий аргумент charset є обов’язковим. Існує також командаuid sort
, яка відповідаєsort
так, якuid search
відповідаєsearch
. Командаsort
спочатку шукає в поштовій скриньці повідомлення, які відповідають заданим критеріям пошуку, використовуючи аргумент набору символів для інтерпретації рядків у критеріях пошуку. Потім він повертає номери відповідних повідомлень.Це команда розширення
IMAP4rev1
.
- IMAP4.starttls(ssl_context=None)¶
Надішліть команду
STARTTLS
. Аргумент ssl_context є необов’язковим і має бути об’єктомssl.SSLContext
. Це дозволить шифрувати підключення IMAP. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.Added in version 3.2.
Змінено в версії 3.4: The method now supports hostname check with
ssl.SSLContext.check_hostname
and Server Name Indication (seessl.HAS_SNI
).
- IMAP4.status(mailbox, names)¶
Запит умов іменованого статусу для поштової скриньки.
- IMAP4.store(message_set, command, flag_list)¶
Змінює розміщення прапорців для повідомлень у поштовій скриньці. команда визначена розділом 6.4.6 RFC 2060 як одна з «FLAGS», «+FLAGS» або «-FLAGS», необов’язково з суфіксом «.SILENT».
Наприклад, щоб встановити позначку видалення для всіх повідомлень:
typ, data = M.search(None, 'ALL') for num in data[0].split(): M.store(num, '+FLAGS', '\\Deleted') M.expunge()
Примітка
Creating flags containing „]“ (for example: «[test]») violates RFC 3501 (the IMAP protocol). However, imaplib has historically allowed creation of such tags, and popular IMAP servers, such as Gmail, accept and produce such flags. There are non-Python programs which also create such tags. Although it is an RFC violation and IMAP clients and servers are supposed to be strict, imaplib still continues to allow such tags to be created for backward compatibility reasons, and as of Python 3.6, handles them if they are sent from the server, since this improves real-world compatibility.
- IMAP4.subscribe(mailbox)¶
Підписатися на нову скриньку.
- IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])¶
Команда
thread
є варіантомsearch
із семантикою потоків для результатів. Повернуті дані містять розділений пробілами список учасників потоку.Члени ланцюжка складаються з нуля або більше номерів повідомлень, розділених пробілами, що вказує на послідовне батьківське та дочірнє повідомлення.
Thread has two arguments before the search_criterion argument(s); a threading_algorithm, and the searching charset. Note that unlike
search
, the searching charset argument is mandatory. There is also auid thread
command which corresponds tothread
the way thatuid search
corresponds tosearch
. Thethread
command first searches the mailbox for messages that match the given searching criteria using the charset argument for the interpretation of strings in the searching criteria. It then returns the matching messages threaded according to the specified threading algorithm.Це команда розширення
IMAP4rev1
.
- IMAP4.uid(command, arg[, ...])¶
Виконайте аргументи команди з повідомленнями, ідентифікованими UID, а не номером повідомлення. Повертає відповідь, що відповідає команді. Необхідно надати принаймні один аргумент; якщо їх не надано, сервер поверне повідомлення про помилку та виникне виняток.
- IMAP4.unsubscribe(mailbox)¶
Відписатися від старої поштової скриньки.
- IMAP4.unselect()¶
imaplib.IMAP4.unselect()
звільняє ресурси сервера, пов’язані з вибраною поштовою скринькою, і повертає сервер до автентифікованого стану. Ця команда виконує ті самі дії, що йimaplib.IMAP4.close()
, за винятком того, що повідомлення не видаляються назавжди з поточної вибраної поштової скриньки.Added in version 3.9.
- IMAP4.xatom(name[, ...])¶
Дозволити прості команди розширення, сповіщені сервером у відповіді
CAPABILITY
.
Наступні атрибути визначені для екземплярів IMAP4
:
- IMAP4.PROTOCOL_VERSION¶
Останній підтримуваний протокол у відповіді
CAPABILITY
від сервера.
- IMAP4.debug¶
Ціле значення для керування виведенням налагодження. Значення ініціалізації береться зі змінної модуля
Debug
. Значення більше трьох відстежують кожну команду.
Приклад IMAP4¶
Ось мінімальний приклад (без перевірки помилок), який відкриває поштову скриньку, отримує та друкує всі повідомлення:
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()