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

Исходный код: 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)

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

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

Необязательный параметр 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 вместо этого, с помощью команды 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, либо кортежем. Если это кортеж, то первая часть — заголовок ответа, а вторая часть содержит данные (т.е. значение ‘literal’).

Параметр 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]]): Список имен почтовых ящиков в directory, соответствующих 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(). Вы можете переопределить этот метод.

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

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

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

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

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 сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает номера соответствующих сообщений.

Это расширение команды 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 сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает сообщения, отсортированные по потокам в соответствии с указанным алгоритмом.

Это расширение команды 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()