imaplib — Клиент протокола IMAP4

Исходный код: Lib/imaplib.py

Модуль определяет три класса, IMAP4, IMAP4_SSL и IMAP4_stream, которые инкапсулируют связь с сервером IMAP4 и осуществляют большое подмножество протокола клиента IMAP4rev1, как определено в RFC 2060. Он обратно совместим с серверами IMAP4 (RFC 1730), но обратите внимание, что команда STATUS не поддерживается в IMAP4.

Три класса обеспечены модулем imaplib, IMAP4 - основа class:

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, ValueError поднимается, если keyfile/certfile предоставляется вместе с ssl_context.

Изменено в версии 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.

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

См.также

Документы, описывающие протокол, и источники и наборы из двух предметов для серверов, осуществляющих его, могут все быть найдены в IMAP Информационный Центр Вашингтонского университета (https://www.washington.edu/imap/).

Объекты 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)

Удалить 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)

Получить ACLs для mailbox. Метод не является стандартным, но поддерживается сервером Cyrus.

IMAP4.getannotation(mailbox, entry, attribute)

Получить указанный ANNOTATIONs для mailbox. Метод не является стандартным, но поддерживается сервером Cyrus.

IMAP4.getquota(root)

Получить использование и пределы ресурса root quota. Этот метод - часть расширения QUOTA IMAP4, определенного в rfc2087.

IMAP4.getquotaroot(mailbox)

Получить список quota roots для именованного mailbox. Этот метод - часть расширения кВОТЫ IMAP4, определенного в 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.

Изменено в версии 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(). Этот метод можно переопределить.

Raises an auditing event imaplib.open with arguments 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)

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

Raises an auditing event imaplib.send with arguments self, data.

IMAP4.setacl(mailbox, who, what)

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

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

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

IMAP4.setquota(root, limits)

Установите ресурс root quota limits. Этот метод - часть расширения кВОТЫ IMAP4, определенного в 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 сначала выполняет поиск в почтовом ящике сообщений, соответствующих заданным критериям поиска, используя аргумент charset для интерпретации строки в критериях поиска. Это тогда возвращает числа соответствия сообщениям.

Это команда расширения 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)

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

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

Поток имеет два аргумента перед аргументами search_criterion; a 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.

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