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. Соединение создается, и версия протокола (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[, keyfile[, certfile]]]])

Это подкласс, производный от IMAP4, который подключается через SSL-шифрованный сокет (для использования этого класса вам нужен модуль сокетов, скомпилированный с поддержкой SSL). Если host не указан, используется '' (локальный хост). Если port опущен, используется стандартный порт IMAP4-over-SSL (993). keyfile и certfile также необязательны — они могут содержать файл с закрытым ключом и цепочкой сертификатов в формате PEM для SSL-соединения.

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

class imaplib.IMAP4_stream(command)

Это подкласс, производный от IMAP4, который подключается к stdin/stdout дескрипторам файлов, созданным с помощью передачи command в os.popen2().

Введено в версии 2.3.

Определены следующие служебные функции:

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

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

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

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

Он вызывается для обработки продолжения ответов сервера. Он должен возвращать data, которое будет закодировано и отправлено серверу. Он должен возвращать 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)

Удалить разрешения (удалить любые права) для кого-либо в почтовом ящике.

Введено в версии 2.4.

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.

Введено в версии 2.5.

IMAP4.getquota(root)

Получение использования ресурсов и ограничений для корневого ресурса. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.

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

IMAP4.getquotaroot(mailbox)

Получение списка пределов использования для указанной папки. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.

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

IMAP4.list([directory[, pattern]])

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

IMAP4.login(user, password)

Идентификация клиента с использованием пароля в открытом виде. Пароль будет заключён в кавычки.

IMAP4.login_cram_md5(user, password)

Принудительное использование аутентификации CRAM-MD5 при идентификации клиента для защиты пароля. Будет работать только если серверный CAPABILITY ответ включает фразу AUTH=CRAM-MD5.

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

IMAP4.logout()

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

IMAP4.lsub([directory[, pattern]])

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

IMAP4.myrights(mailbox)

Отображение моих прав доступа к папке (права, которые я имею на папку).

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

IMAP4.namespace()

Возвращает пространства имён IMAP, как определено в RFC2342.

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

IMAP4.noop()

Отправка NOOP серверу.

IMAP4.open(host, port)

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

IMAP4.partial(message_num, message_part, start, length)

Извлечение усечённой части сообщения. Возвращаемые данные представляют собой кортеж с оболочкой и данными части сообщения.

IMAP4.proxyauth(user)

Принятие аутентификации как пользователя. Позволяет авторизованному администратору получить доступ к любой почтовой папке пользователя.

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

IMAP4.read(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 is a connected IMAP4 instance...
typ, msgnums = M.search(None, 'FROM', '"LDJ"')

# or:
typ, msgnums = M.search(None, '(FROM "LDJ")')

IMAP4.select([mailbox[, readonly]])

Выбор папки. Возвращаемые данные — количество сообщений в mailbox (ответ EXISTS). По умолчанию mailbox — 'INBOX'. Если флаг readonly установлен, изменения в папке запрещены.

IMAP4.send(data)

Отправка data на удалённый сервер. Вы можете переопределить этот метод.

IMAP4.setacl(mailbox, who, what)

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

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

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

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

IMAP4.setquota(root, limits)

Установка ограничений ресурсов для корневого ресурса root. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.

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

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

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

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

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

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

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

Выполнение команды args с идентификацией сообщений по UID, а не по номеру. Возвращает ответ, соответствующий команде. Требуется хотя бы один аргумент; если аргументов нет, сервер вернёт ошибку и будет поднято исключение.

IMAP4.unsubscribe(mailbox)

Отмена подписки на старую почтовую папку.

IMAP4.xatom(name[, arg[, ...]])

Разрешает простые команды расширений, уведомлённые сервером в ответе CAPABILITY.

Экземпляры IMAP4_SSL имеют только один дополнительный метод:

IMAP4_SSL.ssl()

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

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

IMAP4.PROTOCOL_VERSION

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

IMAP4.debug

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

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