imaplib — Клиент протокола IMAP4

Исходный код: Lib/imaplib.py

В этом модуле определены три класса, IMAP4, IMAP4_SSL и IMAP4_stream, которые инкапсулируют соединение с сервером IMAP4 и реализуют большое подмножество протокола IMAP4rev1 клиента, как определено в RFC 2060. Он совместим с серверами IMAP4 (RFC 1730), но обратите внимание, что команда STATUS не поддерживается в IMAP4.

Доступность: не Emscripten, не WASI.

Этот модуль не работает и недоступен на платформах WebAssembly wasm32-emscripten и wasm32-wasi. Дополнительная информация в Платформы WebAssembly.

Модуль imaplib предоставляет три класса, IMAP4 — базовый класс:

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

Этот класс реализует фактический протокол IMAP4. Соединение создается, и версия протокола (IMAP4 или IMAP4rev1) определяется при инициализации экземпляра. Если host не указан, используется '' (локальный хост). Если port опущен, используется стандартный порт IMAP4 (143). Необязательный параметр timeout задаёт таймаут в секундах для попытки подключения. Если timeout не задан или равен None, используется глобальный значение таймаута сокета по умолчанию.

Класс IMAP4 поддерживает оператор with. При использовании таким образом, команда IMAP4 LOGOUT автоматически выполняется при выходе из оператора 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 не указан, используется '' (локальный хост). Если port опущен, используется стандартный порт IMAP4 через SSL (993). ssl_context — объект ssl.SSLContext, позволяющий объединять параметры конфигурации SSL, сертификаты и закрытые ключи в единую (возможно, долгоживущую) структуру. Обратитесь к Рекомендациям по безопасности для соблюдения лучших практик.

keyfile и certfile — устаревший альтернативный вариант ssl_context; они могут указывать на файлы закрытого ключа и цепочки сертификатов PEM для SSL-соединения. Обратите внимание, что параметры keyfile/certfile взаимно исключают ssl_context; в случае их одновременного предоставления будет поднято исключение ValueError.

Необязательный параметр timeout задаёт таймаут в секундах для попытки подключения. Если timeout не задан или равен None, используется глобальный значение таймаута сокета по умолчанию.

Изменено в версии 3.3: Добавлен параметр ssl_context.

Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

Устарело начиная с версии 3.6: keyfile и certfile устарели в пользу ssl_context. Используйте ssl.SSLContext.load_cert_chain() вместо этого или позвольте ssl.create_default_context() выбрать доверенные сертификаты CA вашей системы.

Изменено в версии 3.9: Добавлен необязательный параметр timeout.

Второй подкласс позволяет создавать соединения, созданные дочерним процессом:

class imaplib.IMAP4_stream(command): Это подкласс, производный от IMAP4, который подключается к stdin/stdout дескрипторам файлов, созданным с помощью параметра command для subprocess.Popen().

Определены следующие вспомогательные функции:

imaplib.Internaldate2tuple(datestr): Парсит строку IMAP4 INTERNALDATE и возвращает соответствующее локальное время. Возвращаемое значение — кортеж time.struct_time или None если строка имеет неправильный формат.

imaplib.Int2AP(num): Преобразует целое число в представление в байтах, используя символы из набора [A .. P].

imaplib.ParseFlags(flagstr): Преобразует ответ IMAP4 FLAGS в кортеж отдельных флагов.

imaplib.Time2Internaldate(date_time): Преобразует date_time в представление IMAP4 INTERNALDATE. Возвращаемое значение — строка в формате: "DD-Mmm-YYYY HH:MM:SS +HHMM" (включая двойные кавычки). Аргумент date_time может быть числом (int или float), представляющим секунды с эпохи (как возвращает time.time()), 9-ти кортежем, представляющим локальное время, экземпляром time.struct_time (как возвращает time.localtime()), осознанным экземпляром datetime.datetime или строкой в двойных кавычках. В последнем случае предполагается, что она уже имеет правильный формат.

Обратите внимание, что номера сообщений IMAP4 изменяются при изменении почтового ящика; в частности, после выполнения команды EXPUNGE удаления, оставшиеся сообщения переиндексируются. Поэтому настоятельно рекомендуется использовать идентификаторы (UID) с помощью соответствующей команды.

В конце модуля есть тестовый раздел, содержащий более подробный пример использования.

См. также

Документы, описывающие протокол, источники серверов, реализующих его, и центр информации по IMAP Университета Вашингтона находятся по адресу (Исходный код) https://github.com/uw-imap/imap (Не поддерживается).

Объекты IMAP4

Все команды IMAP4rev1 представлены методами с одинаковым именем, либо в верхнем, либо в нижнем регистре.

Все аргументы команд преобразуются в строки, за исключением AUTHENTICATE, и последнего аргумента для APPEND, который передаётся как литерал IMAP4. При необходимости (строка содержит чувствительные к протоколу IMAP4 символы и не заключена в скобки или двойные кавычки), каждая строка приводит к цитированию. Однако аргумент password для команды LOGIN всегда цитируется. Если вы хотите избежать цитирования аргумента строки (например, аргумента flags для STORE) , то заключите строку в скобки (например, r'(\Deleted)').

Каждая команда возвращает кортеж: (type, [data, ...]) , где type обычно 'OK' или 'NO', а data — это либо текст из ответа команды, либо обязательные результаты от команды. Каждое data — это либо bytes, либо кортеж. Если это кортеж, то первая часть — заголовок ответа, а вторая часть содержит данные (т.е. значение «литерал»).

Опции message_set для команд ниже — это строка, указывающая один или несколько сообщений, на которые должно быть произведено действие. Это может быть просто номер сообщения ('1'), диапазон номеров сообщений ('2:4') или группа несмежных диапазонов, разделённых запятыми ('1:3,6:9'). Диапазон может содержать звездочку для указания бесконечного верхнего предела ('3:*').

Экземпляр IMAP4 имеет следующие методы:

IMAP4.append(mailbox, flags, date_time, message): Добавление message в почтовый ящик с указанным именем.

IMAP4.authenticate(mechanism, authobject)

Команда аутентификации — требует обработки ответа.

mechanism указывает, какой механизм аутентификации использовать — он должен отображаться в переменной экземпляра capabilities в форме AUTH=mechanism.

authobject должен быть вызываемым объектом:

data = authobject(response)

Он будет вызван для обработки продолжения серверных ответов; аргумент response, который ему передаётся, будет bytes. Он должен вернуть bytes data, которое будет закодировано в base64 и отправлено на сервер. Он должен вернуть None , если вместо этого должен быть отправлен ответ об отмене клиента *.

Изменено в версии 3.5: строковые имена пользователей и пароли теперь кодируются в utf-8 вместо ограничения ASCII.

IMAP4.check(): Контрольная точка почтового ящика на сервере.

IMAP4.close(): Закрытие текущего выбранного почтового ящика. Удалённые сообщения удаляются из записи почтового ящика. Эта команда рекомендуется перед LOGOUT.

IMAP4.copy(message_set, new_mailbox): Копирование сообщений message_set в конец new_mailbox.

IMAP4.create(mailbox): Создание нового почтового ящика с именем mailbox.

IMAP4.delete(mailbox): Удаление старого почтового ящика с именем mailbox.

IMAP4.deleteacl(mailbox, who): Удаление разрешений ACL (удаление любых прав) для пользователя в почтовом ящике.

IMAP4.enable(capability): Включение 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 для mailbox. Метод нестандартный, но поддерживается сервером Cyrus.

IMAP4.getannotation(mailbox, entry, attribute): Извлечение указанных ANNOTATION для mailbox. Метод нестандартный, но поддерживается сервером Cyrus.

IMAP4.getquota(root): Получение quota использования ресурсов и лимитов root. Этот метод является частью расширения IMAP4 QUOTA, определённого в rfc2087.

IMAP4.getquotaroot(mailbox): Получение списка quota roots для указанного mailbox. Этот метод является частью расширения IMAP4 QUOTA, определённого в rfc2087.

IMAP4.list([directory[, pattern]]): Вывод имён почтовых ящиков в каталоге, соответствующих шаблону pattern. directory по умолчанию — верхнеуровневая папка почты, а pattern по умолчанию — совпадение со всем. Возвращаемые данные содержат список LIST ответов.

IMAP4.login(user, password): Идентификация клиента с помощью пароля в открытом тексте. password будет цитироваться.

IMAP4.login_cram_md5(user, password): Принудительное использование аутентификации CRAM-MD5 при идентификации клиента для защиты пароля. Будет работать только в том случае, если сервер CAPABILITY ответ включает фразу AUTH=CRAM-MD5.

IMAP4.logout(): Завершение соединения с сервером. Возвращает ответ сервера BYE.

Изменено в версии 3.8: Метод больше не игнорирует произвольные исключения.

IMAP4.lsub(directory='""', pattern='*'): Вывод имён подписанных почтовых ящиков в каталоге, соответствующих шаблону. directory по умолчанию — верхнеуровневый каталог, а pattern по умолчанию — совпадение с любым почтовым ящиком. Возвращаемые данные — кортежи с конвертом и данными части сообщения.

IMAP4.myrights(mailbox): Отображение моих разрешений ACL для почтового ящика (т.е. прав, которые у меня есть на почтовый ящик).

IMAP4.namespace(): Возвращает пространства имён IMAP, как определено в RFC 2342.

IMAP4.noop(): Отправка NOOP на сервер.

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

Открывает сокет для port на host. Необязательный параметр timeout задаёт таймаут в секундах для попытки подключения. Если таймаут не указан или равен None, используется глобальный значение таймаута сокета по умолчанию. Обратите внимание, что если параметр timeout равен нулю, будет вызвано исключение ValueError для отказа от создания сокета без блокировки. Этот метод неявно вызывается конструктором IMAP4. Объекты соединения, созданные этим методом, будут использоваться в методах IMAP4.read(), IMAP4.readline(), IMAP4.send() и IMAP4.shutdown(). Вы можете переопределить этот метод.

Вызывает событие аудита аудита imaplib.open с аргументами self, host, port.

Изменено в версии 3.9: Добавлен параметр timeout.

IMAP4.partial(message_num, message_part, start, length): Извлечение усечённой части сообщения. Возвращаемые данные — кортеж с конвертом и данными части сообщения.

IMAP4.proxyauth(user): Принятие аутентификации как user. Позволяет авторизованному администратору стать прокси для любой почтовой ящика пользователя.

END_OF_DOCUMENT_MARKER

IMAP4.read(size): Считывает size байт с удалённого сервера. Вы можете переопределить этот метод.

IMAP4.readline(): Считывает одну строку с удалённого сервера. Вы можете переопределить этот метод.

IMAP4.recent(): Запрашивает обновление у сервера. Возвращаемые данные — None , если новых сообщений нет, иначе значение ответа RECENT.

IMAP4.rename(oldmailbox, newmailbox): Переименовывает папку с именем oldmailbox в newmailbox.

IMAP4.response(code): Возвращает данные для ответа 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): Выбирает папку. Возвращаемые данные — количество сообщений в папке mailbox (ответ EXISTS). По умолчанию mailbox — 'INBOX'. Если установлен флаг readonly, изменения в папке запрещены.

IMAP4.send(data)

Отправляет data на удалённый сервер. Вы можете переопределить этот метод.

Возбуждает событие аудита аудита imaplib.send с аргументами self, data.

IMAP4.setacl(mailbox, who, what): Устанавливает ACL для mailbox. Метод нестандартный, но поддерживается сервером Cyrus.

IMAP4.setannotation(mailbox, entry, attribute[, ...]): Устанавливает ANNOTATION для mailbox. Метод нестандартный, но поддерживается сервером Cyrus.

IMAP4.setquota(root, limits): Устанавливает quota лимиты ресурсов root. Этот метод является частью расширения IMAP4 QUOTA, определённого в rfc2087.

IMAP4.shutdown(): Закрывает соединение, установленное в open. Этот метод неявно вызывается методом IMAP4.logout(). Вы можете переопределить этот метод.

IMAP4.socket(): Возвращает экземпляр сокета, используемый для подключения к серверу.

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

Команда sort — вариант команды search с семантикой сортировки результатов. Возвращаемые данные содержат список совпадающих номеров сообщений, разделённых пробелами.

Команда sort имеет два аргумента перед аргументом(ами) search_criterion: список sort_criteria в скобках и кодировку поиска charset. В отличие от 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: Метод теперь поддерживает проверку имени хоста с помощью ssl.SSLContext.check_hostname и Server Name Indication (см. ssl.HAS_SNI).

IMAP4.status(mailbox, names): Запрашивает указанные статусные условия для mailbox.

IMAP4.store(message_set, command, flag_list)

Изменяет расположение флагов для сообщений в почтовом ящике. command указан в разделе 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()

Примечание

Создание флагов, содержащих ‘]’ (например: “[test]”), нарушает RFC 3501 (протокол IMAP). Однако imaplib исторически позволял создавать такие теги, и популярные IMAP-сервера, такие как Gmail, принимают и генерируют такие флаги. Существуют программы, не написанные на Python, которые также создают такие теги. Хотя это нарушение RFC и IMAP-клиенты и сервера должны быть строгими, imaplib по-прежнему позволяет создавать такие теги из-за обратной совместимости и, начиная с Python 3.6, обрабатывает их, если они отправляются сервером, поскольку это улучшает совместимость в реальных условиях.

IMAP4.subscribe(mailbox): Подписаться на новую папку.

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

Команда thread — это вариант команды search с семантикой нитей для результатов. Возвращаемые данные содержат список номеров совпадающих сообщений, разделённых пробелами.

Члены потока состоят из нуля или более номеров сообщений, разделённых пробелами, указывающих на последовательных родительских и дочерних элементов.

Команда Thread имеет два аргумента перед аргументом(ами) search_criterion: threading_algorithm и кодировку поиска charset. В отличие от search, аргумент кодировки поиска charset обязателен. Существует также команда uid thread, которая соответствует команде thread так же, как команда uid search соответствует команде search . Команда thread сначала ищет в папке сообщения, соответствующие заданным критериям поиска, используя аргумент кодировки для интерпретации строк в критериях поиска. Затем она возвращает соответствующие сообщения, сгруппированные в потоки согласно указанному алгоритму.

Это расширение команды IMAP4rev1.

IMAP4.uid(command, arg[, ...]): Выполняет команду args с идентификаторами сообщений 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()