imaplib – клиент протокола IMAP4¶imaplib – IMAP4 protocol client

Объекты IMAP4¶IMAP4 Objects

Все команды 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 в указанный почтовый ящик.

flags может быть None или строкой токенов флагов IMAP. Несколько флагов разделяются пробелами, например r'\Seen \Answered'. Если flags ещё не заключён в круглые скобки, круглые скобки добавляются автоматически.

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 (убрать все права), установленные для who на mailbox.

IMAP4.enable(capability)¶

Включить возможность (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])". Возвращаемые данные – это кортежи, содержащие конверт (envelope) и данные части сообщения.

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.idle(duration=None)¶

Return an Idler: an iterable context manager implementing the IMAP4 IDLE command as defined in RFC 2177.

Возвращаемый объект отправляет команду IDLE при активации в операторе with, выдаёт непомеченные (untagged) ответы IMAP через протокол итератора и отправляет DONE при выходе из контекста.

Все непомеченные ответы, полученные после отправки команды IDLE (включая те, что приходят до подтверждения команды сервером), будут доступны через итерацию. Оставшиеся ответы (не проитерированные в контексте with) можно получить обычным способом после завершения IDLE, используя IMAP4.response().

Ответы представляются в виде кортежа (type, [data, ...]), как описано в разделе Объекты IMAP4.

Аргумент duration задаёт максимальную длительность (в секундах) ожидания бездействия, после которой любая текущая итерация будет остановлена. Он может быть int или float, или None для отсутствия ограничения по времени. Чтобы избежать тайм-аута бездействия на серверах, где он есть, следует устанавливать не более 29 минут (1740 секунд). Требует сокетного соединения; duration должно быть None на соединениях IMAP4_stream.

>>> with M.idle(duration=29 * 60) as idler:
...     for typ, data in idler:
...         print(typ, data)
...
EXISTS [b'1']
RECENT [b'1']

Idler.burst(interval=0.1)¶

Выдаёт пакет ответов с интервалом не более interval секунд (выражается как int или float).

Этот генератор является альтернативой поочерёдной итерации ответов и предназначен для эффективной пакетной обработки. Он извлекает следующий ответ вместе с любыми сразу доступными последующими ответами. (Например, быстрая серия ответов EXPUNGE после массового удаления.)

Требуется сокетное соединение; не работает на соединениях IMAP4_stream.

>>> with M.idle() as idler:
...     # получить ответ и любые другие, следующие с интервалом менее 0.1 секунды
...     batch = list(idler.burst())
...     print(f'processing {len(batch)} responses...')
...     print(batch)
...
processing 3 responses...
[('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

Совет

Максимальная длительность контекста IDLE, переданная в IMAP4.idle(), соблюдается при ожидании первого ответа в пакете. Поэтому истекший Idler приведёт к тому, что этот генератор завершится немедленно, ничего не выдавая. Разработчикам следует учитывать это при использовании в цикле.

Примечание

Итератор, возвращаемый IMAP4.idle(), можно использовать только внутри оператора with. До или после этого контекста незапрошенные ответы собираются внутренне по завершении любой команды и могут быть получены с помощью IMAP4.response().

Примечание

Имя и структура класса Idler являются внутренними интерфейсами и могут измениться. Вызывающий код может рассчитывать на стабильность его управления контекстом, итерации и публичного метода, но не должен создавать подклассы, экземпляры, сравнивать или иным образом напрямую ссылаться на класс.

Добавлено в версии 3.14.

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.

Изменено в версии 3.14: Если поддержка MD5 недоступна, возбуждается исключение IMAP4.error.

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

IMAP4.read(size)¶

Читает size байт с удалённого сервера. Этот метод можно переопределить.

IMAP4.readline()¶

Читает одну строку с удалённого сервера. Этот метод можно переопределить.

IMAP4.recent()¶

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

IMAP4.rename(oldmailbox, newmailbox)¶

Переименовывает почтовый ящик с именем oldmailbox в newmailbox.

IMAP4.response(code)¶

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

IMAP4.search(charset, criterion[, ...])¶

Ищет в почтовом ящике сообщения, соответствующие условиям. charset может быть None, и в этом случае CHARSET не будет указан в запросе к серверу. Протокол IMAP требует указать хотя бы один критерий; при ошибке со стороны сервера будет возбуждено исключение. charset должен быть None, если возможность UTF8=ACCEPT была включена с помощью команды enable().

Пример:

# M – это подключенный экземпляр IMAP4...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

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

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

IMAP4.starttls(ssl_context=None)¶

Отправляет команду STARTTLS. Аргумент ssl_context является необязательным и должен быть объектом ssl.SSLContext. Это включит шифрование в IMAP-соединении. Пожалуйста, прочитайте рекомендации по безопасности для соблюдения лучших практик.

Примечание

При использовании ssl_context по умолчанию соединение шифруется, но сертификат сервера и имя хоста не проверяются. Для их проверки передайте контекст, созданный с помощью ssl.create_default_context().

Добавлено в версии 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 3501 как один из вариантов: “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 с семантикой threading для результатов. Возвращаемые данные содержат разделенный пробелами список участников ветвей.

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

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

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

IMAP4.uid(command, arg[, ...])¶

Выполняет команду с аргументами для сообщений, идентифицированных по 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¶IMAP4 Example

Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:

import getpass, imaplib

M = imaplib.IMAP4(host='example.org')
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()