imaplib
— Клиент протокола IMAP4¶
Исходный код: Lib/imaplib.py
Этот модуль определяет три класса, IMAP4
, IMAP4_SSL
и IMAP4_stream
, которые инкапсулируют соединение с сервером IMAP4 и реализуют большое количество клиентского протокола IMAP4rev1, как определено в RFC 2060. Он обратно совместим с серверами IMAP4 (RFC 1730), но обратите внимание, что команда STATUS
в IMAP4 не поддерживается.
Availability: это не Emscripten, это был не я.
Этот модуль не работает или недоступен на платформах WebAssembly wasm32-emscripten
и wasm32-wasi
. Дополнительную информацию смотрите в разделе Платформы веб-сборки.
Модуль 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, keyfile=None, certfile=None, ssl_context=None, timeout=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.Необязательный параметр timeout определяет время ожидания в секундах для попытки подключения. Если время ожидания не указано или равно None, используется глобальное время ожидания сокета по умолчанию.
Изменено в версии 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()
выбрать для вас сертификаты доверенного центра сертификации системы.Изменено в версии 3.9: Был добавлен необязательный параметр timeout.
Второй подкласс допускает подключения, созданные дочерним процессом:
- 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
нумерация оставшихся сообщений меняется. Поэтому настоятельно рекомендуется использовать Uuid вместо этого, используя команду UID.
В конце модуля есть раздел тестирования, содержащий более подробный пример использования.
См.также
Документы, описывающие протокол, исходные тексты для серверов, реализующих его, подготовленные Информационным центром IMAP Вашингтонского университета, можно найти по адресу (Исходный код) https://github.com/uw-imap/imap (Не поддерживается).
Объекты IMAP4¶
Все команды IMAP4rev1 представлены методами с одинаковыми именами, как в верхнем, так и в нижнем регистре.
Все аргументы команд преобразуются в строки, за исключением AUTHENTICATE
и последнего аргумента APPEND
, который передается как литерал IMAP4. При необходимости (строка содержит символы, зависящие от протокола IMAP4, и не заключена ни в круглые скобки, ни в двойные кавычки) каждая строка берется в кавычки. Однако аргумент password для команды LOGIN
всегда берется в кавычки. Если вы хотите избежать заключения строки аргумента в кавычки (например, аргумента flags для STORE
), то заключите строку в круглые скобки (например: r'(\Deleted)'
).
Каждая команда возвращает кортеж: (type, [data, ...])
, где type обычно означает 'OK'
или 'NO'
, а data - это либо текст из ответа на команду, либо обязательные результаты выполнения команды. Все данные представляют собой либо bytes
, либо кортеж. Если это кортеж, то первая часть является заголовком ответа, а вторая часть содержит данные (т.е. «буквальное» значение).
Параметры message_set для приведенных ниже команд - это строка, указывающая одно или несколько сообщений, на основании которых необходимо выполнить действия. Это может быть простой номер сообщения ('1'
), диапазон номеров сообщений ('2:4'
), или группа несмежных диапазонов, разделенных запятыми ('1:3,6:9'
). Диапазон может содержать звездочку, указывающую на бесконечную верхнюю границу ('3:*'
).
Экземпляр IMAP4
имеет следующие методы:
- IMAP4.append(mailbox, flags, date_time, message)¶
Добавьте сообщение в указанный почтовый ящик.
- IMAP4.authenticate(mechanism, authobject)¶
Команда аутентификации — требует обработки ответа.
механизм указывает, какой механизм аутентификации должен использоваться - он должен отображаться в переменной экземпляра
capabilities
в видеAUTH=mechanism
.authobject должен быть вызываемым объектом:
data = authobject(response)
Он будет вызван для обработки ответов сервера на продолжение работы; передаваемый аргумент response будет
bytes
. Он должен возвращатьbytes
данные, которые будут закодированы в 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)¶
Удалите списки управления доступом (удалите все права), установленные для пользователей в почтовом ящике.
- 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 для почтового ящика. Метод является нестандартным, но поддерживается серверомCyrus
.
- IMAP4.getannotation(mailbox, entry, attribute)¶
Извлеките указанные
ANNOTATION
s для почтового ящика. Метод является нестандартным, но поддерживается серверомCyrus
.
- IMAP4.getquota(root)¶
Получите данные об использовании ресурсов
quota
root и их ограничениях. Этот метод является частью расширения квоты IMAP4, определенного в rfc2087.
- IMAP4.getquotaroot(mailbox)¶
Получите список
quota
roots
для именованного почтового ящика. Этот метод является частью расширения квоты IMAP4, определенного в 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='*')¶
Перечислите имена подписанных почтовых ящиков в соответствии с шаблоном соответствия каталогу. каталог по умолчанию является каталогом верхнего уровня, а шаблон по умолчанию соответствует любому почтовому ящику. Возвращаемые данные представляют собой кортежи конверта и данных части сообщения.
- IMAP4.myrights(mailbox)¶
Покажите мои списки управления доступом для почтового ящика (т.е. права, которые у меня есть на почтовый ящик).
- 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[, ...])¶
Найдите в почтовом ящике соответствующие сообщения. кодировка может быть
None
, в этом случае в запросе к серверу не будет указаноCHARSET
. Протокол IMAP требует, чтобы был указан хотя бы один критерий; исключение будет вызвано, когда сервер вернет сообщение об ошибке. кодировка должна быть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)¶
Выберите почтовый ящик. Возвращаемые данные - это количество сообщений в почтовом ящике (
EXISTS
ответ). Значение почтового ящика по умолчанию равно'INBOX'
. Если установлен флаг только для чтения, изменения в почтовом ящике запрещены.
- IMAP4.send(data)¶
Отправляет
data
на удаленный сервер. Вы можете переопределить этот метод.Создает auditing event
imaplib.send
с аргументамиself
,data
.
- IMAP4.setacl(mailbox, who, what)¶
Установите
ACL
для почтового ящика. Метод является нестандартным, но поддерживается серверомCyrus
.
- IMAP4.setannotation(mailbox, entry, attribute[, ...])¶
Установите
ANNOTATION
s для почтового ящика. Метод является нестандартным, но поддерживается серверомCyrus
.
- IMAP4.setquota(root, limits)¶
Установите ограничения на ресурсы
quota
для root. Этот метод является частью расширения квоты IMAP4, определенного в rfc2087.
- IMAP4.shutdown()¶
Закрыть соединение, установленное в
open
. Этот метод неявно вызывается вIMAP4.logout()
. Вы можете переопределить этот метод.
- IMAP4.socket()¶
Возвращает экземпляр сокета, используемый для подключения к серверу.
- IMAP4.sort(sort_criteria, charset, search_criterion[, ...])¶
Команда
sort
является вариантом командыsearch
с семантикой сортировки результатов. Возвращаемые данные содержат разделенный пробелом список совпадающих номеров сообщений.Сортировка имеет два аргумента перед аргументом(ами) search_criterion; список sort_criteria, заключенный в круглые скобки, и кодировку для поиска. Обратите внимание, что в отличие от
search
, аргумент searching 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)¶
Запросите условия именованного статуса для почтового ящика.
- IMAP4.store(message_set, command, flag_list)¶
Изменяет расположение флагов для сообщений в почтовом ящике. команда указана в разделе 6.4.6 раздела RFC 2060 как один из «ФЛАГОВ», «+ФЛАГОВ» или «-ФЛАГОВ», необязательно с суффиксом «.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
с семантикой потоков для результатов. Возвращаемые данные содержат список элементов потока, разделенных пробелами.Элементы потока состоят из нуля или более номеров сообщений, разделенных пробелами, указывающих на последовательные родительские и дочерние сообщения.
У Thread есть два аргумента перед аргументом(ами) search_criterion; threading_algorithm и поисковая кодировка. Обратите внимание, что в отличие от
search
, аргумент для поиска кодировки является обязательным. Существует также командаuid thread
, которая соответствуетthread
так же, какuid search
соответствуетsearch
. Командаthread
сначала выполняет поиск в почтовом ящике сообщений, соответствующих заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает соответствующие сообщения, обработанные в соответствии с указанным алгоритмом обработки.Это команда расширения
IMAP4rev1
.
- IMAP4.uid(command, arg[, ...])¶
Выполняет команды с сообщениями, идентифицируемыми по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан хотя бы один аргумент; если он не указан, сервер вернет сообщение об ошибке и будет создано исключение.
- IMAP4.unsubscribe(mailbox)¶
Отписаться от старого почтового ящика.
- IMAP4.unselect()¶
imaplib.IMAP4.unselect()
освобождает ресурсы сервера, связанные с выбранным почтовым ящиком, и возвращает сервер в состояние проверки подлинности. Эта команда выполняет те же действия, что иimaplib.IMAP4.close()
, за исключением того, что никакие сообщения не удаляются безвозвратно из текущего выбранного почтового ящика.Добавлено в версии 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()