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; если keyfile/certfile указаны вместе с ssl_context, возникает исключение ValueError.

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

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

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

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

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 удаления, оставшиеся сообщения переиндексируются. Поэтому настоятельно рекомендуется использовать UIDs вместо них, используя команду UID.

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

21.15.1. Объекты IMAP4

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

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

Каждая команда возвращает кортеж: (type, [data, ...]), где type обычно 'OK' или 'NO', и data — это либо текст из ответа команды, либо обязательные результаты от команды. Каждое data — это либо строка, либо кортеж. Если кортеж, то первая часть — заголовок ответа, а вторая часть содержит данные (например: значение ‘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)

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

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, как определено в RFC 2342.

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). По умолчанию mailbox — '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’а. Этот метод является частью расширения 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.xatom(name[, ...])

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

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

IMAP4.PROTOCOL_VERSION

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

IMAP4.debug

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

IMAP4.utf8_enabled

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

Введено в версии 3.5.

21.15.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()