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)

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

Класс 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.

В качестве атрибутов класса 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)

Это подкласс, унаследованный от IMAP4, который подключается через SSL-зашифрованный сокет (для использования этого класса вам нужен модуль сокетов, скомпилированный с поддержкой SSL). Если host не указан, используется '' (локальный хост). Если port опущен, используется стандартный порт IMAP4 через SSL (993). ssl_context — объект ssl.SSLContext, который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в одну (возможно, долгоживущую) структуру. Обратитесь к разделу Безопасность для получения рекомендаций по лучшим практикам.

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

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

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

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

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.

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

1. Объекты IMAP4

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

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

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

Параметр 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)

Удалить разрешения (удалить все права) для пользователя в почтовом ящике.

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.

IMAP4.lsub(directory='""', pattern='*')

Список подписок на почтовые ящики в каталоге, соответствующие шаблону. directory по умолчанию — корневой каталог, а pattern — соответствие любому почтовому ящику. Возвращаемые данные — кортежи конверта и данных части сообщения.

IMAP4.myrights(mailbox)

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

IMAP4.namespace()

Возвращает пространства имен IMAP, определенные в RFC2342.

IMAP4.noop()

Отправка NOOP на сервер.

IMAP4.open(host, port)

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

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

IMAP4.send(data)

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

IMAP4.setacl(mailbox, who, what)

Установить ACL для mailbox. Метод нестандартный, но поддерживается сервером Cyrus.

IMAP4.setannotation(mailbox, entry, attribute[, ...])

Установить ANNOTATION для mailbox. Метод нестандартный, но поддерживается сервером Cyrus.

IMAP4.setquota(root, limits)

Установить quota root’s ресурсные limits. Этот метод является частью расширения 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()

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.xatom(name[, ...])

Разрешить простые команды расширений, уведомлённые сервером в ответ CAPABILITY.

Следующие атрибуты определены для экземпляров IMAP4:

IMAP4.PROTOCOL_VERSION

Последняя поддерживаемая версия протокола в ответ CAPABILITY от сервера.

IMAP4.debug

Целое значение для управления выводом отладки. Начальное значение взято из модульной переменной Debug. Значения, большие чем три, отслеживают каждую команду.

IMAP4.utf8_enabled

Булево значение, которое обычно False, но устанавливается в True если команда enable() успешно выполнена для возможности UTF8=ACCEPT.

Новая в версии 3.5.

2. Пример 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()