imaplib
— Клиент протокола IMAP4¶
Источник: Lib/imaplib.py
Этот модуль определяет три класса, IMAP4
, IMAP4_SSL
и IMAP4_stream
, которые инкапсулируют соединение с сервером IMAP4 и реализуют большое подмножество клиентского протокола IMAP4rev1, как определено в RFC 2060. Он обратно совместим с серверами IMAP4 (RFC 1730), но обратите внимание, что команда STATUS
не поддерживается в IMAP4.
Availability: не WASI.
Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.
Три класса предоставляются модулем imaplib
, IMAP4
- базовый класс:
- class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)¶
Этот класс реализует реальный протокол IMAP4. При инициализации экземпляра создается соединение и определяется версия протокола (IMAP4 или IMAP4rev1). Если host не указан, то используется
''
(локальный хост). Если port опущен, используется стандартный порт IMAP4 (143). Необязательный параметр timeout задает таймаут в секундах для попытки соединения. Если таймаут не указан или равенNone
, используется глобальный таймаут сокета по умолчанию.Класс
IMAP4
поддерживает операторwith
. При его использовании команда IMAP4LOGOUT
выдается автоматически после выхода из оператораwith
. Например:>>> from imaplib import IMAP4 >>> with IMAP4("domain.org") as M: ... M.noop() ... ('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])
Изменено в версии 3.5: Добавлена поддержка оператора
with
.Изменено в версии 3.9: Добавлен необязательный параметр timeout.
Три исключения определены как атрибуты класса IMAP4
:
- exception IMAP4.error¶
Исключение, возникающее при любых ошибках. Причина исключения передается в конструктор в виде строки.
- exception IMAP4.abort¶
Ошибки сервера IMAP4 приводят к возникновению этого исключения. Это подкласс
IMAP4.error
. Обратите внимание, что закрытие экземпляра и создание нового экземпляра обычно позволяет избавиться от этого исключения.
- exception IMAP4.readonly¶
Это исключение возникает, когда сервер изменяет статус почтового ящика, доступного для записи. Это подкласс
IMAP4.error
. Какой-то другой клиент теперь имеет право на запись, и почтовый ящик нужно открыть заново, чтобы получить право на запись.
Существует также подкласс для безопасных соединений:
- class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, *, ssl_context=None, timeout=None)¶
Это подкласс, производный от
IMAP4
, который соединяется через зашифрованный сокет SSL (для использования этого класса необходим модуль сокета, скомпилированный с поддержкой SSL). Если host не указан, используется''
(локальный хост). Если port опущен, используется стандартный порт IMAP4-over-SSL (993). ssl_context - это объектssl.SSLContext
, который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Пожалуйста, прочитайте Соображения безопасности о лучших практиках.Необязательный параметр timeout задает таймаут в секундах для попытки соединения. Если таймаут не указан или равен
None
, используется глобальный таймаут сокета по умолчанию.Изменено в версии 3.3: Добавлен параметр ssl_context.
Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью
ssl.SSLContext.check_hostname
и Указание имени сервера (см.ssl.HAS_SNI
).Изменено в версии 3.9: Добавлен необязательный параметр timeout.
Изменено в версии 3.12: Устаревшие параметры keyfile и certfile были удалены.
Второй подкласс позволяет использовать соединения, созданные дочерним процессом:
- class imaplib.IMAP4_stream(command)¶
Это подкласс, производный от
IMAP4
, который подключается к файловым дескрипторамstdin/stdout
, созданным путем передачи команды в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)¶
Преобразование даты_времени в представление 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¶
Все команды IMAP4rev1 представлены одноименными методами, как в верхнем, так и в нижнем регистре.
Все аргументы команд преобразуются в строки, за исключением AUTHENTICATE
и последнего аргумента APPEND
, который передается как литерал IMAP4. При необходимости (строка содержит чувствительные к протоколу IMAP4 символы и не заключена ни в круглые скобки, ни в двойные кавычки) каждая строка заключается в кавычки. Однако аргумент пароль команды 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)¶
Добавить сообщение в именованный почтовый ящик.
- IMAP4.authenticate(mechanism, authobject)¶
Команда Authenticate — требует обработки ответа.
mechanism указывает, какой механизм аутентификации будет использоваться - он должен быть представлен в переменной экземпляра
capabilities
в формеAUTH=mechanism
.authobject должен быть вызываемым объектом:
data = authobject(response)
Он будет вызываться для обработки ответов продолжения сервера; передаваемый ему аргумент ответ будет
bytes
. Он должен вернутьbytes
данные, которые будут закодированы в base64 и отправлены на сервер. Он должен возвращатьNone
, если вместо него должен быть отправлен ответ*
о прерывании работы клиента.Изменено в версии 3.5: Строковые имена пользователей и пароли теперь кодируются в
utf-8
, а не ограничиваются ASCII.
- IMAP4.check()¶
Почтовый ящик Checkpoint на сервере.
- 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)¶
Включите возможность (см. RFC 5161). Большинство возможностей включать не нужно. В настоящее время поддерживается только возможность
UTF8=ACCEPT
(см. RFC 6855).
- IMAP4.expunge()¶
Постоянное удаление удаленных элементов из выбранного почтового ящика. Генерирует ответ
EXPUNGE
для каждого удаленного сообщения. Возвращаемые данные содержат список номеровEXPUNGE
сообщений в порядке их получения.
- IMAP4.fetch(message_set, message_parts)¶
Получение (частей) сообщений. message_parts должно быть строкой имен частей сообщений, заключенных в круглые скобки, например:
"(UID BODY[TEXT])"
. Возвращаемые данные представляют собой кортежи из конверта части сообщения и данных.
- IMAP4.getacl(mailbox)¶
Получение
ACL
s для mailbox. Метод нестандартный, но поддерживается серверомCyrus
.
- IMAP4.getannotation(mailbox, entry, attribute)¶
Получение указанных
ANNOTATION
s для mailbox. Метод нестандартный, но поддерживается серверомCyrus
.
- IMAP4.getquota(root)¶
Получите
quota
*Получение данных об использовании ресурсов корня и их ограничениях. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.
- IMAP4.getquotaroot(mailbox)¶
Получить список
quota
roots
для именованного mailbox. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.
- IMAP4.list([directory[, pattern]])¶
Список имен почтовых ящиков в директории, соответствующих шаблону. По умолчанию директория - это почтовая папка верхнего уровня, а шаблон по умолчанию должен соответствовать чему угодно. Возвращаемые данные содержат список ответов
LIST
.
- IMAP4.login(user, 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.noop()¶
Отправьте
NOOP
на сервер.
- IMAP4.open(host, port, timeout=None)¶
Открывает сокет к порту на хосте. Необязательный параметр timeout задает таймаут в секундах для попытки соединения. Если таймаут не задан или равен
None
, используется глобальный таймаут сокета по умолчанию. Также обратите внимание, что если параметр timeout задан равным нулю, то при попытке создания неблокирующего сокета будет вызвана ошибкаValueError
. Этот метод неявно вызывается конструкторомIMAP4
. Объекты соединения, созданные этим методом, будут использоваться в методахIMAP4.read()
,IMAP4.readline()
,IMAP4.send()
иIMAP4.shutdown()
. Вы можете переопределить этот метод.Поднимает auditing event
imaplib.open
с аргументамиself
,host
,port
.Изменено в версии 3.9: Был добавлен параметр timeout.
- IMAP4.partial(message_num, message_part, start, length)¶
Получение усеченной части сообщения. Возвращаемые данные представляют собой кортеж из конверта части сообщения и данных.
- IMAP4.proxyauth(user)¶
Предполагает аутентификацию в качестве пользователя. Позволяет авторизованному администратору заходить через прокси в почтовый ящик любого пользователя.
- 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 требует, чтобы был указан хотя бы один критерий; если сервер вернет ошибку, будет поднято исключение. charset должен бытьNone
, если возможностьUTF8=ACCEPT
была включена с помощью командыenable()
.Пример:
# M is a connected IMAP4 instance... typ, msgnums = M.search(None, 'FROM', '"LDJ"') # or: typ, msgnums = M.search(None, '(FROM "LDJ")')
- IMAP4.select(mailbox='INBOX', readonly=False)¶
Выберите почтовый ящик. Возвращаемые данные - это количество сообщений в mailbox (ответ``EXISTS``). По умолчанию mailbox имеет значение
'INBOX'
. Если установлен флаг readonly, изменения в почтовом ящике не допускаются.
- IMAP4.send(data)¶
Отправляет
data
на удаленный сервер. Вы можете переопределить этот метод.Поднимает auditing event
imaplib.send
с аргументамиself
,data
.
- IMAP4.setacl(mailbox, who, what)¶
Установите
ACL
для почтового ящика. Метод нестандартный, но поддерживается серверомCyrus
.
- IMAP4.setannotation(mailbox, entry, attribute[, ...])¶
Установите
ANNOTATION
s для mailbox. Метод нестандартный, но поддерживается серверомCyrus
.
- IMAP4.setquota(root, limits)¶
Установите
quota
корневой ресурс лимитов. Этот метод является частью расширения IMAP4 QUOTA, определенного в rfc2087.
- IMAP4.shutdown()¶
Закрыть соединение, установленное в
open
. Этот метод неявно вызываетсяIMAP4.logout()
. Вы можете переопределить этот метод.
- IMAP4.socket()¶
Возвращает экземпляр сокета, используемый для подключения к серверу.
- IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶
Команда
sort
представляет собой вариант командыsearch
с семантикой сортировки результатов. Возвращаемые данные содержат разделенный пробелами список совпадающих номеров сообщений.Sort имеет два аргумента перед аргументом(ами) поиск_критерия; список критериев_сортировки, заключенный в круглые скобки, и набор символов поиска charset. Обратите внимание, что в отличие от
search
, аргумент charset является обязательным. Существует также командаuid sort
, которая соответствуетsort
так же, какuid search
соответствуетsearch
. Командаsort
сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает количество совпадающих сообщений.Это команда расширения
IMAP4rev1
.
- IMAP4.starttls(ssl_context=None)¶
Отправка команды
STARTTLS
. Аргумент ssl_context является необязательным и должен представлять собой объектssl.SSLContext
. Это позволит включить шифрование на IMAP-соединении. Пожалуйста, прочитайте Соображения безопасности о лучших практиках.Added in version 3.2.
Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью
ssl.SSLContext.check_hostname
и Указание имени сервера (см.ssl.HAS_SNI
).
- IMAP4.status(mailbox, names)¶
Запрос именованных условий состояния для mailbox.
- IMAP4.store(message_set, command, flag_list)¶
Изменяет расположение флагов для сообщений в почтовом ящике. команда определена в разделе 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 у Thread есть два аргумента: threading_algorithm и charset поиска. Обратите внимание, что в отличие от
search
, аргумент charset является обязательным. Существует также командаuid thread
, которая соответствуетthread
так же, какuid search
соответствуетsearch
. Командаthread
сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает совпадающие сообщения с потоком в соответствии с заданным алгоритмом потоков.Это команда расширения
IMAP4rev1
.
- IMAP4.uid(command, arg[, ...])¶
Выполняет команду args с сообщениями, идентифицированными по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан хотя бы один аргумент; если не указан ни один, сервер вернет ошибку и будет поднято исключение.
- IMAP4.unsubscribe(mailbox)¶
Отказаться от подписки на старый почтовый ящик.
- IMAP4.unselect()¶
imaplib.IMAP4.unselect()
освобождает ресурсы сервера, связанные с выбранным почтовым ящиком, и возвращает сервер в состояние аутентификации. Эта команда выполняет те же действия, что иimaplib.IMAP4.close()
, за исключением того, что сообщения не удаляются навсегда из выбранного в данный момент почтового ящика.Added in version 3.9.
- IMAP4.xatom(name[, ...])¶
Разрешить простые команды расширения, уведомляемые сервером в ответе
CAPABILITY
.
Следующие атрибуты определены для экземпляров IMAP4
:
- IMAP4.PROTOCOL_VERSION¶
Последний поддерживаемый протокол в ответе
CAPABILITY
от сервера.
- IMAP4.debug¶
Целочисленное значение для управления выводом отладки. Значение инициализации берется из переменной модуля
Debug
. Значения больше трех отслеживают каждую команду.
Пример IMAP4¶
Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик, извлекает и печатает все сообщения:
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()