`imaplib.md`

375 строк · 30.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.5/library/imaplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.15. [`imaplib`](https://python-all.ru/3.5/library/imaplib.html#module-imaplib) – клиент протокола IMAP489**Исходный код:** [Lib/imaplib.py](https://python-all.ru/src/3.5/Lib/imaplib.py)1011---1213Этот модуль определяет три класса, [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4), [`IMAP4_SSL`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4_SSL) и [`IMAP4_stream`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4_stream), которые инкапсулируют соединение с IMAP4-сервером и реализуют большую часть клиентского протокола IMAP4rev1, описанного в [**RFC 2060**](https://python-all.ru/3.5/library/imaplib.html). Он обратно совместим с IMAP4-серверами ([**RFC 1730**](https://python-all.ru/3.5/library/imaplib.html)), но следует учесть, что команда `STATUS` не поддерживается в IMAP4.1415Модуль [`imaplib`](https://python-all.ru/3.5/library/imaplib.html#module-imaplib) предоставляет три класса, [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4) – это базовый класс:1617#### `class imaplib.IMAP4(host='', port=IMAP4_PORT)`1819Этот класс реализует протокол IMAP4. Соединение создается, а версия протокола (IMAP4 или IMAP4rev1) определяется при инициализации экземпляра. Если *host* не указан, используется `''` (локальный хост). Если *port* опущен, используется стандартный порт IMAP4 (143).2021Класс [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4) поддерживает оператор [`with`](https://python-all.ru/3.5/reference/compound_stmts.html#with). При таком использовании команда IMAP4 `LOGOUT` выполняется автоматически при выходе из оператора [`with`](https://python-all.ru/3.5/reference/compound_stmts.html#with). Например:2223```python24>>> from imaplib import IMAP425>>> with IMAP4("domain.org") as M:26...     M.noop()27...28('OK', [b'Nothing Accomplished. d25if65hy903weo.87'])29```3031Изменено в версии 3.5: Поддержка оператора [`with`](https://python-all.ru/3.5/reference/compound_stmts.html#with) была добавлена.3233Три исключения определены как атрибуты класса [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4):3435#### `exception IMAP4.error`3637Исключение возникает при любых ошибках. Причина исключения передаётся конструктору в виде строки.3839#### `exception IMAP4.abort`4041Ошибки сервера IMAP4 вызывают это исключение. Оно является подклассом [`IMAP4.error`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.error). Обратите внимание, что закрытие экземпляра и создание нового обычно позволяет восстановиться после этого исключения.4243#### `exception IMAP4.readonly`4445Это исключение возникает, когда сервер изменяет статус почтового ящика, доступного для записи. Оно является подклассом [`IMAP4.error`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.error). Теперь другой клиент имеет права на запись, и для повторного получения прав на запись необходимо заново открыть почтовый ящик.4647Также существует подкласс для безопасных соединений:4849#### `class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None)`5051Это подкласс, производный от [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4), который подключается через SSL-зашифрованный сокет (для использования этого класса необходим модуль сокета, скомпилированный с поддержкой SSL). Если *host* не указан, используется `''` (локальный хост). Если *port* опущен, используется стандартный порт IMAP4 через SSL (993). *ssl\_context* – это объект [`ssl.SSLContext`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext), который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Пожалуйста, прочтите [Рекомендации по безопасности](https://python-all.ru/3.5/library/ssl.html#ssl-security) для получения рекомендаций.5253*keyfile* и *certfile* являются устаревшей альтернативой *ssl\_context* – они могут указывать на файлы закрытого ключа и цепочки сертификатов в формате PEM для SSL-соединения. Обратите внимание, что параметры *keyfile*/*certfile* взаимно исключают *ssl\_context*, и [`ValueError`](https://python-all.ru/3.5/library/exceptions.html#ValueError) возникает, если *keyfile*/*certfile* указаны вместе с *ssl\_context*.5455Изменено в версии 3.3: добавлен параметр *ssl\_context*.5657Изменено в версии 3.4: Теперь класс поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.5/library/ssl.html#ssl.HAS_SNI)).5859Второй подкласс предназначен для соединений, создаваемых дочерним процессом:6061#### `class imaplib.IMAP4_stream(command)`6263Это подкласс, производный от [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4), который подключается к файловым дескрипторам `stdin/stdout`, создаваемым путём передачи *command* в `subprocess.Popen()`.6465Определены следующие вспомогательные функции:6667#### `imaplib.Internaldate2tuple(datestr)`6869Разбирает строку `INTERNALDATE` IMAP4 и возвращает соответствующее локальное время. Возвращаемое значение – кортеж [`time.struct_time`](https://python-all.ru/3.5/library/time.html#time.struct_time) или `None`, если строка имеет неверный формат.7071#### `imaplib.Int2AP(num)`7273Преобразует целое число в строковое представление, используя символы из набора \[`A` .. `P`\].7475#### `imaplib.ParseFlags(flagstr)`7677Преобразует ответ IMAP4 `FLAGS` в кортеж отдельных флагов.7879#### `imaplib.Time2Internaldate(date_time)`8081Преобразует *date\_time* в представление IMAP4 `INTERNALDATE`. Возвращается строка вида: `"DD-Mmm-YYYY HH:MM:SS +HHMM"` (включая двойные кавычки). Аргумент *date\_time* может быть числом (int или float), представляющим секунды с начала эпохи (как возвращается [`time.time()`](https://python-all.ru/3.5/library/time.html#time.time)), 9-кортежем, представляющим местное время, экземпляром [`time.struct_time`](https://python-all.ru/3.5/library/time.html#time.struct_time) (как возвращается [`time.localtime()`](https://python-all.ru/3.5/library/time.html#time.localtime)), осознанным экземпляром [`datetime.datetime`](https://python-all.ru/3.5/library/datetime.html#datetime.datetime) или строкой в двойных кавычках. В последнем случае считается, что она уже находится в правильном формате.8283Обратите внимание, что номера сообщений IMAP4 меняются при изменении почтового ящика; в частности, после выполнения команды `EXPUNGE`, которая удаляет сообщения, оставшиеся перенумеровываются. Поэтому настоятельно рекомендуется использовать UID с командой UID.8485В конце модуля есть тестовый раздел, содержащий более полный пример использования.8687> **См. также**88>89> Документы, описывающие протокол, а также исходные коды и бинарные файлы для серверов, реализующих его, можно найти в *IMAP Information Center* Вашингтонского университета ([https://www.washington.edu/imap/](https://python-all.ru/3.5/library/imaplib.html)).9091## 21.15.1. Объекты IMAP49293Все команды IMAP4rev1 представлены методами с теми же именами, в верхнем или нижнем регистре.9495Все аргументы команд преобразуются в строки, за исключением `AUTHENTICATE`, и последнего аргумента для `APPEND`, который передаётся как литерал IMAP4. При необходимости (строка содержит чувствительные к протоколу IMAP4 символы и не заключена в круглые скобки или двойные кавычки) каждая строка заключается в кавычки. Однако аргумент *password* команды `LOGIN` всегда заключается в кавычки. Если требуется избежать заключения строки аргумента в кавычки (например, аргумент *flags* для `STORE`), то строку следует заключить в круглые скобки (например, `r'(\Deleted)'`).9697Каждая команда возвращает кортеж: `(type, [data, ...])`, где *type* обычно равен `'OK'` или `'NO'`, а *data* – это либо текст ответа команды, либо обязательные результаты команды. Каждый *data* – это либо строка, либо кортеж. Если кортеж, то первая часть – заголовок ответа, а вторая часть содержит данные (то есть буквальное значение).9899Параметр *message\_set* в командах ниже – это строка, задающая одно или несколько сообщений, над которыми нужно выполнить действие. Это может быть простой номер сообщения (`'1'`), диапазон номеров сообщений (`'2:4'`) или группа несмежных диапазонов, разделённых запятыми (`'1:3,6:9'`). Диапазон может содержать звёздочку для обозначения бесконечной верхней границы (`'3:*'`).100101Экземпляр [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4) имеет следующие методы:102103#### `IMAP4.append(mailbox, flags, date_time, message)`104105Добавляет *message* в указанный почтовый ящик.106107#### `IMAP4.authenticate(mechanism, authobject)`108109Команда аутентификации – требуется обработка ответа.110111*mechanism* указывает, какой механизм аутентификации следует использовать – он должен присутствовать в переменной экземпляра `capabilities` в форме `AUTH=mechanism`.112113*authobject* должен быть вызываемым объектом:114115```python116data = authobject(response)117```118119Он будет вызываться для обработки ответов продолжения сервера; передаваемый ему аргумент *response* будет равен `bytes`. Он должен возвращать `bytes` *data*, которые будут закодированы в base64 и отправлены на сервер. Он должен возвращать `None`, если вместо этого следует отправить ответ прерывания клиента `*`.120121Изменено в версии 3.5: теперь строковые имена пользователей и пароли кодируются в `utf-8`, а не ограничиваются ASCII.122123#### `IMAP4.check()`124125Контрольная точка почтового ящика на сервере.126127#### `IMAP4.close()`128129Закрывает текущий выбранный почтовый ящик. Удалённые сообщения удаляются из почтового ящика с правом записи. Это рекомендуемая команда перед `LOGOUT`.130131#### `IMAP4.copy(message_set, new_mailbox)`132133Копирует сообщения *message\_set* в конец *new\_mailbox*.134135#### `IMAP4.create(mailbox)`136137Создаёт новый почтовый ящик с именем *mailbox*.138139#### `IMAP4.delete(mailbox)`140141Удаляет старый почтовый ящик с именем *mailbox*.142143#### `IMAP4.deleteacl(mailbox, who)`144145Удалить ACL (убрать все права), установленные для who на mailbox.146147#### `IMAP4.enable(capability)`148149Включить возможность (capability) *capability* (см. [**RFC 5161**](https://python-all.ru/3.5/library/imaplib.html)). Большинство возможностей не нужно включать. Сейчас поддерживается только возможность из `UTF8=ACCEPT` (см. [**RFC 6855**](https://python-all.ru/3.5/library/imaplib.html)).150151Новое в версии 3.5: Метод [`enable()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.enable) и поддержка [**RFC 6855**](https://python-all.ru/3.5/library/imaplib.html).152153#### `IMAP4.expunge()`154155Окончательно удаляет помеченные на удаление письма из выбранного почтового ящика. Генерирует `EXPUNGE`-ответ для каждого удалённого сообщения. Возвращаемые данные содержат список `EXPUNGE` номеров сообщений в порядке их получения.156157#### `IMAP4.fetch(message_set, message_parts)`158159Извлекает (части) сообщений. *message\_parts* должна быть строкой с именами частей сообщения, заключёнными в круглые скобки, например: `"(UID BODY[TEXT])"`. Возвращаемые данные – это кортежи, содержащие конверт (envelope) и данные части сообщения.160161#### `IMAP4.getacl(mailbox)`162163Получает `ACL` для *mailbox*. Метод нестандартный, но поддерживается сервером `Cyrus`.164165#### `IMAP4.getannotation(mailbox, entry, attribute)`166167Извлекает указанные `ANNOTATION` для *mailbox*. Метод нестандартный, но поддерживается сервером `Cyrus`.168169#### `IMAP4.getquota(root)`170171Получает использование ресурсов и лимиты для `quota` *root*. Этот метод является частью расширения IMAP4 QUOTA, определённого в rfc2087.172173#### `IMAP4.getquotaroot(mailbox)`174175Получает список `quota` `roots` для указанного *mailbox*. Этот метод является частью расширения IMAP4 QUOTA, определённого в rfc2087.176177#### `IMAP4.list([directory='""', pattern='*'pattern]])`178179Перечисляет имена почтовых ящиков в *directory*, соответствующие *pattern*. *directory* по умолчанию является корневой папкой почты, а *pattern* по умолчанию соответствует всему. Возвращаемые данные содержат список ответов `LIST`.180181#### `IMAP4.login(user, password)`182183Идентифицирует клиента с помощью пароля в открытом виде. Параметр *password* будет заключён в кавычки.184185#### `IMAP4.login_cram_md5(user, password)`186187Принудительно использует аутентификацию `CRAM-MD5` для защиты пароля при идентификации клиента. Сработает, только если ответ сервера `CAPABILITY` содержит фразу `AUTH=CRAM-MD5`.188189#### `IMAP4.logout()`190191Закрывает соединение с сервером. Возвращает ответ сервера `BYE`.192193#### `IMAP4.lsub(directory='""', pattern='*')`194195Выводит список подписанных почтовых ящиков в указанном каталоге, соответствующих шаблону. По умолчанию *directory* – корневой каталог, а *pattern* – любой почтовый ящик. Возвращаемые данные – кортежи из конверта части сообщения и данных.196197#### `IMAP4.myrights(mailbox)`198199Показывает списки управления доступом (ACL) почтового ящика (т.е. права, которые у клиента есть на этот ящик).200201#### `IMAP4.namespace()`202203Возвращает пространства имён IMAP согласно RFC2342.204205#### `IMAP4.noop()`206207Отправляет `NOOP` на сервер.208209#### `IMAP4.open(host, port)`210211Открывает сокет к *port* на *host*. Этот метод неявно вызывается конструктором [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4). Объекты соединения, установленные этим методом, будут использоваться в методах [`IMAP4.read()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.read), [`IMAP4.readline()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.readline), [`IMAP4.send()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.send) и [`IMAP4.shutdown()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.shutdown). Можно переопределить этот метод.212213#### `IMAP4.partial(message_num, message_part, start, length)`214215Извлекает усечённую часть сообщения. Возвращаемые данные – кортеж из конверта части сообщения и данных.216217#### `IMAP4.proxyauth(user)`218219Предполагает аутентификацию от имени пользователя *user*. Позволяет авторизованному администратору выполнять прокси-доступ к почтовому ящику любого пользователя.220221#### `IMAP4.read(size)`222223Читает *size* байт с удалённого сервера. Этот метод можно переопределить.224225#### `IMAP4.readline()`226227Читает одну строку с удалённого сервера. Этот метод можно переопределить.228229#### `IMAP4.recent()`230231Запрашивает у сервера обновление. Возвращаемые данные – `None`, если нет новых сообщений, иначе значение ответа `RECENT`.232233#### `IMAP4.rename(oldmailbox, newmailbox)`234235Переименовывает почтовый ящик с именем *oldmailbox* в *newmailbox*.236237#### `IMAP4.response(code)`238239Возвращает данные для *кода* ответа, если он получен, или `None`. Возвращает указанный код вместо обычного типа.240241#### `IMAP4.search(charset, criterion[, ...])`242243Ищет в почтовом ящике сообщения, соответствующие условиям. *charset* может быть `None`, и в этом случае `CHARSET` не будет указан в запросе к серверу. Протокол IMAP требует указать хотя бы один критерий; при ошибке со стороны сервера будет возбуждено исключение. *charset* должен быть `None`, если возможность `UTF8=ACCEPT` была включена с помощью команды [`enable()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.enable).244245Пример:246247```python248# M – это подключенный экземпляр IMAP4...249typ, msgnums = M.search(None, 'FROM', '"LDJ"')250251# или:252typ, msgnums = M.search(None, '(FROM "LDJ")')253```254255#### `IMAP4.select(mailbox='INBOX', readonly=False)`256257Выбирает почтовый ящик. Возвращаемые данные – количество сообщений в *mailbox* (ответ `EXISTS`). По умолчанию *mailbox* равен `'INBOX'`. Если установлен флаг *readonly*, изменения в почтовом ящике запрещены.258259#### `IMAP4.send(data)`260261Отправляет `data` на удалённый сервер. Этот метод можно переопределить.262263#### `IMAP4.setacl(mailbox, who, what)`264265Устанавливает `ACL` для *mailbox*. Метод является нестандартным, но поддерживается сервером `Cyrus`.266267#### `IMAP4.setannotation(mailbox, entry, attribute[, ...])`268269Устанавливает `ANNOTATION` для *mailbox*. Метод является нестандартным, но поддерживается сервером `Cyrus`.270271#### `IMAP4.setquota(root, limits)`272273Устанавливает `quota` ресурса *root* – *limits*. Этот метод является частью расширения IMAP4 QUOTA, определённого в rfc2087.274275#### `IMAP4.shutdown()`276277Закрывает соединение, установленное в `open`. Этот метод неявно вызывается методом [`IMAP4.logout()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.logout). Этот метод можно переопределить.278279#### `IMAP4.socket()`280281Возвращает экземпляр сокета, используемый для подключения к серверу.282283#### `IMAP4.sort(sort_criteria, charset, search_criterion[, ...])`284285Команда `sort` является вариантом `search` с семантикой сортировки результатов. Возвращаемые данные содержат список номеров подходящих сообщений, разделённых пробелами.286287Sort имеет два аргумента перед аргументом(ами) *search\_criterion*: список *sort\_criteria* в скобках и поисковый *charset*. Обратите внимание: в отличие от `search`, аргумент *charset* является обязательным. Также существует команда `uid sort`, которая соответствует `sort` так же, как `uid search` соответствует `search`. Команда `sort` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает номера подходящих сообщений.288289Это команда расширения `IMAP4rev1`.290291#### `IMAP4.starttls(ssl_context=None)`292293Отправляет команду `STARTTLS`. Аргумент *ssl\_context* является необязательным и должен быть объектом [`ssl.SSLContext`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext). Это включит шифрование в IMAP-соединении. Пожалуйста, прочитайте [рекомендации по безопасности](https://python-all.ru/3.5/library/ssl.html#ssl-security) для соблюдения лучших практик.294295Новое в версии 3.2.296297Изменено в версии 3.4: Теперь метод поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.5/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.5/library/ssl.html#ssl.HAS_SNI)).298299#### `IMAP4.status(mailbox, names)`300301Запрашивает именованные условия состояния для *mailbox*.302303#### `IMAP4.store(message_set, command, flag_list)`304305Изменяет состояния флагов для сообщений в почтовом ящике. Параметр *command* задаётся в разделе 6.4.6 документа [**RFC 2060**](https://python-all.ru/3.5/library/imaplib.html) как одно из значений «FLAGS», «+FLAGS» или «-FLAGS», возможно с суффиксом «.SILENT».306307Например, чтобы установить флаг удаления на все сообщения:308309```python310typ, data = M.search(None, 'ALL')311for num in data[0].split():312   M.store(num, '+FLAGS', '\\Deleted')313M.expunge()314```315316#### `IMAP4.subscribe(mailbox)`317318Подписаться на новый почтовый ящик.319320#### `IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])`321322Команда `thread` является вариантом `search` с семантикой threading для результатов. Возвращаемые данные содержат разделенный пробелами список участников ветвей.323324Участники ветвей состоят из нуля или более номеров сообщений, разделенных пробелами, указывающих последовательные родительские и дочерние элементы.325326Thread has two arguments before the *search\_criterion* argument(s); a *threading\_algorithm*, and the searching *charset*. Note that unlike `search`, the searching *charset* argument is mandatory. There is also a `uid thread` command which corresponds to `thread` the way that `uid search` corresponds to `search`. The `thread` command first searches the mailbox for messages that match the given searching criteria using the charset argument for the interpretation of strings in the searching criteria. It then returns the matching messages threaded according to the specified threading algorithm.327328Это команда расширения `IMAP4rev1`.329330#### `IMAP4.uid(command, arg[, ...])`331332Выполняет команду с аргументами для сообщений, идентифицированных по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан по крайней мере один аргумент; если ни одного не передано, сервер вернет ошибку, и будет возбуждено исключение.333334#### `IMAP4.unsubscribe(mailbox)`335336Отписаться от старого почтового ящика.337338#### `IMAP4.xatom(name[, ...])`339340Позволяет простые расширенные команды, уведомляемые сервером в ответе `CAPABILITY`.341342На экземплярах [`IMAP4`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4) определены следующие атрибуты:343344#### `IMAP4.PROTOCOL_VERSION`345346Последний поддерживаемый протокол в ответе `CAPABILITY` от сервера.347348#### `IMAP4.debug`349350Целочисленное значение для управления выводом отладочной информации. Начальное значение берется из переменной модуля `Debug`. Значения больше трех трассируют каждую команду.351352#### `IMAP4.utf8_enabled`353354Логическое значение, которое обычно равно `False`, но устанавливается в `True`, если команда [`enable()`](https://python-all.ru/3.5/library/imaplib.html#imaplib.IMAP4.enable) была успешно выдана для возможности `UTF8=ACCEPT`.355356Новое в версии 3.5.357358## 21.15.2. Пример IMAP4359360Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:361362```python363import getpass, imaplib364365M = imaplib.IMAP4()366M.login(getpass.getuser(), getpass.getpass())367M.select()368typ, data = M.search(None, 'ALL')369for num in data[0].split():370    typ, data = M.fetch(num, '(RFC822)')371    print('Message %s\n%s\n' % (num, data[0][1]))372M.close()373M.logout()374```375