imaplib — IMAP4 protocol client

Вихідний код: Lib/imaplib.py

Цей модуль визначає три класи: IMAP4, IMAP4_SSL і IMAP4_stream, які інкапсулюють підключення до сервера IMAP4 і реалізують велику підмножину клієнтського протоколу IMAP4rev1, як визначено в RFC 2060. Він зворотно сумісний із серверами IMAP4 (RFC 1730), але зауважте, що команда STATUS не підтримується в IMAP4.

Три класи надаються модулем 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 is None, 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, keyfile=None, certfile=None, ssl_context=None, timeout=None)

Це підклас, похідний від IMAP4, який підключається через сокет, зашифрований SSL (щоб використовувати цей клас, вам потрібен модуль сокета, скомпільований із підтримкою SSL). Якщо host не вказано, використовується '' (локальний хост). Якщо порт не вказано, використовується стандартний порт IMAP4 через SSL (993). ssl_context — це об’єкт ssl.SSLContext, який дозволяє об’єднувати параметри конфігурації SSL, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

keyfile and certfile are a legacy alternative to ssl_context - they can point to PEM-formatted private key and certificate chain files for the SSL connection. Note that the keyfile/certfile parameters are mutually exclusive with ssl_context, a ValueError is raised if keyfile/certfile is provided along with ssl_context.

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 (see ssl.HAS_SNI).

Застаріло починаючи з версії 3.6: keyfile and certfile are deprecated in favor of ssl_context. Please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system’s trusted CA certificates for you.

Змінено в версії 3.9: Додано необов’язковий параметр timeout.

Другий підклас дозволяє з’єднання, створені дочірнім процесом:

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 upper-case or lower-case.

Усі аргументи команд перетворюються на рядки, за винятком 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).

Нове в версії 3.5: Сам метод enable() і підтримка 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.namespace()

Повертає простори імен IMAP, як визначено в RFC 2342.

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 a ValueError to reject creating a non-blocking socket. This method is implicitly called by the IMAP4 constructor. The connection objects established by this method will be used in the IMAP4.read(), IMAP4.readline(), IMAP4.send(), and IMAP4.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. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

Нове в версії 3.2.

Змінено в версії 3.4: The method now supports hostname check with ssl.SSLContext.check_hostname and Server Name Indication (see ssl.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 nonetheless 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 a uid thread command which corresponds to thread the way that uid search corresponds to search. The thread 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(), за винятком того, що повідомлення не видаляються назавжди з поточної вибраної поштової скриньки.

Нове в версії 3.9.

IMAP4.xatom(name[, ...])

Дозволити прості команди розширення, сповіщені сервером у відповіді CAPABILITY.

Наступні атрибути визначені для екземплярів IMAP4:

IMAP4.PROTOCOL_VERSION

Останній підтримуваний протокол у відповіді CAPABILITY від сервера.

IMAP4.debug

Ціле значення для керування виведенням налагодження. Значення ініціалізації береться зі змінної модуля Debug. Значення більше трьох відстежують кожну команду.

IMAP4.utf8_enabled

Логічне значення, яке зазвичай має значення False, але встановлюється на True, якщо команда enable() успішно виконана для можливості UTF8=ACCEPT.

Нове в версії 3.5.

Приклад IMAP4

Ось мінімальний приклад (без перевірки помилок), який відкриває поштову скриньку, отримує та друкує всі повідомлення:

import getpass, imaplib

M = imaplib.IMAP4()
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()