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-over-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 и указания имени сервера (Server Name Indication) (см. 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 может быть числом (целым или плавающей точкой), представляющим секунды с момента эпохи (как возвращается time.time()), 9-кортежем, представляющим местное время, экземпляром time.struct_time (как возвращается time.localtime()), осознанным экземпляром datetime.datetime или строкой в двойных кавычках. В последнем случае предполагается, что она уже в правильном формате.

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

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

Объекты 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 данные, которые будут закодированы в 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 response включает фразу AUTH=CRAM-MD5.

IMAP4.logout()

Завершение соединения с сервером. Возвращает ответ сервера BYE.

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

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

IMAP4.myrights(mailbox)

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

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 с семантикой сортировки результатов. Возвращаемые данные содержат список номеров совпавших сообщений, разделённых пробелами.

Команда сортировки имеет два аргумента перед аргументами 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 и указанием имени сервера (см. ssl.HAS_SNI).

IMAP4.status(mailbox, names)

Запрос названных условий состояния для почтового ящика.

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

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

Команда группирования имеет два аргумента перед аргументами 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.

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