Содержание страницы

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

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

Устарело с версии 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)¶: Разбирает строку INTERNALDATE IMAP4 и возвращает соответствующее локальное время. Возвращаемое значение – кортеж 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 Вашингтонского университета, можно найти по адресу (Source Code) https://github.com/uw-imap/imap (Not Maintained).

Объекты IMAP4¶IMAP4 Objects

Все команды 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 (убрать все права), установленные для 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.list([directory='""', pattern='*'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)¶

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

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

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-соединении. Пожалуйста, прочитайте рекомендации по безопасности для соблюдения лучших практик.

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

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

Thread has two arguments before the search_criterion argument(s); a threading_algorithm, and the searching charset. Note that unlike search, the searching charset argument is mandatory. There is also a uid thread command which corresponds to thread the way that uid search corresponds to search. The thread command first searches the mailbox for messages that match the given searching criteria using the charset argument for the interpretation of strings in the searching criteria. It then returns the matching messages threaded according to the specified threading algorithm.

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

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

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

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

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

Объекты IMAP4¶IMAP4 Objects

Пример IMAP4¶IMAP4 Example

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