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

21.15. `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:

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- зашифрованный сокет (для использования этого класса требуется модуль socket, скомпилированный с поддержкой 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).

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

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

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

См. также

Документы, описывающие протокол, а также исходные коды и бинарные сборки для серверов, реализующих его, можно найти в IMAP Information Center Вашингтонского университета (http://www.washington.edu/imap/).

21.15.1. Объекты IMAP4¶IMAP4 Objects

Все команды 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, если вместо этого необходимо отправить ответ об отмене клиента *.

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.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. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.

IMAP4.getquotaroot(mailbox)¶: Получает список quota roots для указанного mailbox. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.

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)¶: Показывает списки управления доступом (ACL) почтового ящика (т.е. права, которые у клиента есть на этот ящик).

IMAP4.namespace()¶: Возвращает пространства имён IMAP согласно RFC2342.

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

Пример:

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

IMAP4.setacl(mailbox, who, what)¶: Устанавливает ACL для mailbox. Этот метод является нестандартным, но поддерживается сервером Cyrus.

IMAP4.setannotation(mailbox, entry, attribute[, ...])¶: Устанавливает ANNOTATION для mailbox. Этот метод является нестандартным, но поддерживается сервером Cyrus.

IMAP4.setquota(root, limits)¶: Устанавливает quota ресурса root – limits. Этот метод является частью расширения QUOTA протокола IMAP4, определённого в RFC 2087.

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

IMAP4.subscribe(mailbox)¶: Подписаться на новый почтовый ящик.

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])¶

Команда thread является вариантом search с семантикой threading для результатов. Возвращаемые данные содержат разделённый пробелами список участников threading.

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

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

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

IMAP4.uid(command, arg[, ...])¶: Выполняет команду с аргументами для сообщений, идентифицированных по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан по крайней мере один аргумент; если ни одного не передано, сервер вернет ошибку, и будет возбуждено исключение.

IMAP4.unsubscribe(mailbox)¶: Отписаться от старого почтового ящика.

IMAP4.xatom(name[, ...])¶: Разрешает простые расширенные команды, уведомляемые сервером в ответе CAPABILITY.

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

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

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

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

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

21.15.1. Объекты IMAP4¶IMAP4 Objects

21.15.2. Пример IMAP4¶IMAP4 Example

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