`imaplib.md`

349 строк · 29.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.4/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.4/library/imaplib.html#module-imaplib) – клиент протокола IMAP489**Исходный код:** [Lib/imaplib.py](https://python-all.ru/src/3.4/Lib/imaplib.py)1011---1213Этот модуль определяет три класса: [`IMAP4`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4), [`IMAP4_SSL`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4_SSL) и [`IMAP4_stream`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4_stream), которые инкапсулируют соединение с сервером IMAP4 и реализуют большой подмножество клиентского протокола IMAP4rev1, определённого в [**RFC 2060**](https://python-all.ru/3.4/library/imaplib.html). Он обратно совместим с серверами IMAP4 ([**RFC 1730**](https://python-all.ru/3.4/library/imaplib.html)), но следует учесть, что команда `STATUS` в IMAP4 не поддерживается.1415Модуль [`imaplib`](https://python-all.ru/3.4/library/imaplib.html#module-imaplib) предоставляет три класса; [`IMAP4`](https://python-all.ru/3.4/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.4/library/imaplib.html#imaplib.IMAP4):2223#### `exception IMAP4.error`2425Исключение возникает при любых ошибках. Причина исключения передаётся конструктору в виде строки.2627#### `exception IMAP4.abort`2829Ошибки сервера IMAP4 вызывают это исключение. Оно является подклассом [`IMAP4.error`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.error). Обратите внимание, что закрытие экземпляра и создание нового обычно позволяет восстановиться после этого исключения.3031#### `exception IMAP4.readonly`3233Это исключение возникает, когда сервер изменяет статус почтового ящика, доступного для записи. Оно является подклассом [`IMAP4.error`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.error). Теперь какой-то другой клиент имеет права на запись, и для повторного получения прав на запись потребуется открыть ящик заново.3435Также существует подкласс для безопасных соединений:3637#### `class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None, ssl_context=None)`3839Это подкласс, производный от [`IMAP4`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4), который подключается через SSL- зашифрованный сокет (для использования этого класса требуется модуль socket, скомпилированный с поддержкой SSL). Если *host* не указан, используется `''` (локальный хост). Если *port* опущен, используется стандартный порт IMAP4-over-SSL (993). *ssl\_context* – это объект [`ssl.SSLContext`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext), который позволяет объединить параметры конфигурации SSL, сертификаты и закрытые ключи в единую (потенциально долгоживущую) структуру. Пожалуйста, прочитайте [*Рекомендации по безопасности*](https://python-all.ru/3.4/library/ssl.html#ssl-security) для получения лучших практик.4041*keyfile* и *certfile* являются устаревшей альтернативой *ssl\_context* – они могут указывать на файлы закрытого ключа и цепочки сертификатов в формате PEM для SSL-соединения. Обратите внимание, что параметры *keyfile*/*certfile* взаимоисключающие с *ssl\_context*; если *keyfile*/*certfile* указаны вместе с *ssl\_context*, возникает [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError).4243Изменено в версии 3.3: добавлен параметр *ssl\_context*.4445Изменено в версии 3.4: Класс теперь поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.4/library/ssl.html#ssl.HAS_SNI)).4647Второй подкласс предназначен для соединений, создаваемых дочерним процессом:4849#### `class imaplib.IMAP4_stream(command)`5051Это подкласс, производный от [`IMAP4`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4), который подключается к файловым дескрипторам `stdin/stdout`, созданным передачей *command* в `subprocess.Popen()`.5253Определены следующие вспомогательные функции:5455#### `imaplib.Internaldate2tuple(datestr)`5657Разбирает строку IMAP4 `INTERNALDATE` и возвращает соответствующее местное время. Возвращаемое значение – кортеж [`time.struct_time`](https://python-all.ru/3.4/library/time.html#time.struct_time) или None, если строка имеет неверный формат.5859#### `imaplib.Int2AP(num)`6061Преобразует целое число в строковое представление, используя символы из набора \[`A` .. `P`\].6263#### `imaplib.ParseFlags(flagstr)`6465Преобразует ответ IMAP4 `FLAGS` в кортеж отдельных флагов.6667#### `imaplib.Time2Internaldate(date_time)`6869Преобразует *date\_time* в представление IMAP4 `INTERNALDATE`. Возвращаемое значение – строка вида: `"DD-Mmm-YYYY HH:MM:SS +HHMM"` (включая двойные кавычки). Аргумент *date\_time* может быть числом (int или float), представляющим секунды с начала эпохи (как возвращено [`time.time()`](https://python-all.ru/3.4/library/time.html#time.time)), 9-кортежем, представляющим местное время, экземпляром [`time.struct_time`](https://python-all.ru/3.4/library/time.html#time.struct_time) (как возвращено [`time.localtime()`](https://python-all.ru/3.4/library/time.html#time.localtime)), «осознанным» экземпляром [`datetime.datetime`](https://python-all.ru/3.4/library/datetime.html#datetime.datetime) или строкой в двойных кавычках. В последнем случае считается, что она уже находится в правильном формате.7071Обратите внимание, что номера сообщений IMAP4 изменяются при изменении почтового ящика; в частности, после выполнения команды `EXPUNGE`, удаляющей сообщения, оставшиеся сообщения перенумеровываются. Поэтому настоятельно рекомендуется использовать UID с командой UID.7273В конце модуля есть тестовый раздел, содержащий более полный пример использования.7475> **См. также**76>77> Документы, описывающие протокол, а также исходные коды и бинарные сборки для серверов, реализующих его, можно найти в *IMAP Information Center* Вашингтонского университета ([http://www.washington.edu/imap/](https://python-all.ru/3.4/library/imaplib.html)).7879## 21.15.1. Объекты IMAP48081Все команды IMAP4rev1 представлены методами с теми же именами, в верхнем или нижнем регистре.8283Все аргументы команд преобразуются в строки, за исключением `AUTHENTICATE` и последнего аргумента `APPEND`, который передаётся как литерал IMAP4. При необходимости (если строка содержит символы, чувствительные к протоколу IMAP4, и не заключена в круглые скобки или двойные кавычки) каждая строка заключается в кавычки. Однако аргумент *password* команды `LOGIN` всегда заключается в кавычки. Если требуется избежать заключения строки аргумента в кавычки (например, аргумент *flags* команды `STORE`), то заключите строку в круглые скобки (например: `r'(\Deleted)'`).8485Каждая команда возвращает кортеж: `(type, [data, ...])`, где *type* обычно равно `'OK'` или `'NO'`, а *data* – это либо текст ответа команды, либо обязательные результаты команды. Каждый *data* – это строка или кортеж. Если это кортеж, то первая часть – заголовок ответа, а вторая часть содержит данные (т.е. «литеральное» значение).8687Параметр *message\_set* в командах ниже – это строка, задающая одно или несколько сообщений, над которыми нужно выполнить действие. Это может быть простой номер сообщения (`'1'`), диапазон номеров сообщений (`'2:4'`) или группа несмежных диапазонов, разделённых запятыми (`'1:3,6:9'`). Диапазон может содержать звёздочку для обозначения бесконечной верхней границы (`'3:*'`).8889Экземпляр [`IMAP4`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4) имеет следующие методы:9091#### `IMAP4.append(mailbox, flags, date_time, message)`9293Добавляет *message* в указанный почтовый ящик.9495#### `IMAP4.authenticate(mechanism, authobject)`9697Команда аутентификации – требуется обработка ответа.9899*mechanism* указывает, какой механизм аутентификации следует использовать; он должен присутствовать в переменной экземпляра `capabilities` в форме `AUTH=mechanism`.100101*authobject* должен быть вызываемым объектом:102103```python104data = authobject(response)105```106107Он будет вызван для обработки ответов продолжения сервера; переданный ему аргумент *response* будет `bytes`. Он должен возвращать `bytes` *data*, которые будут закодированы в base64 и отправлены на сервер. Он должен вернуть `None`, если вместо этого необходимо отправить ответ об отмене клиента `*`.108109#### `IMAP4.check()`110111Контрольная точка почтового ящика на сервере.112113#### `IMAP4.close()`114115Закрывает текущий выбранный почтовый ящик. Удаленные сообщения удаляются из доступного для записи почтового ящика. Это рекомендуемая команда перед `LOGOUT`.116117#### `IMAP4.copy(message_set, new_mailbox)`118119Копирует сообщения *message\_set* в конец *new\_mailbox*.120121#### `IMAP4.create(mailbox)`122123Создаёт новый почтовый ящик с именем *mailbox*.124125#### `IMAP4.delete(mailbox)`126127Удаляет старый почтовый ящик с именем *mailbox*.128129#### `IMAP4.deleteacl(mailbox, who)`130131Удалить ACL (убрать все права), установленные для who на mailbox.132133#### `IMAP4.expunge()`134135Окончательно удаляет удаленные сообщения из выбранного почтового ящика. Генерирует ответ `EXPUNGE` для каждого удаленного сообщения. Возвращаемые данные содержат список номеров сообщений `EXPUNGE` в порядке получения.136137#### `IMAP4.fetch(message_set, message_parts)`138139Извлекает (части) сообщений. *message\_parts* должна быть строкой с именами частей сообщения, заключенными в круглые скобки, например: `"(UID BODY[TEXT])"`. Возвращаемые данные представляют собой кортежи, содержащие конверт и данные части сообщения.140141#### `IMAP4.getacl(mailbox)`142143Получает `ACL` для *mailbox*. Этот метод является нестандартным, но поддерживается сервером `Cyrus`.144145#### `IMAP4.getannotation(mailbox, entry, attribute)`146147Извлекает указанные `ANNOTATION` для *mailbox*. Метод является нестандартным, но поддерживается сервером `Cyrus`.148149#### `IMAP4.getquota(root)`150151Получает использование ресурсов и лимиты `quota` *root*. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.152153#### `IMAP4.getquotaroot(mailbox)`154155Получает список `quota` `roots` для указанного *mailbox*. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.156157#### `IMAP4.list([directory[, pattern]])`158159Выводит имена почтовых ящиков в *directory*, соответствующие *pattern*. *directory* по умолчанию равен корневой почтовой папке, а *pattern* по умолчанию соответствует всему. Возвращаемые данные содержат список ответов `LIST`.160161#### `IMAP4.login(user, password)`162163Идентифицирует клиента с помощью пароля в открытом виде. Параметр *password* будет заключён в кавычки.164165#### `IMAP4.login_cram_md5(user, password)`166167Принудительно использует аутентификацию `CRAM-MD5` при идентификации клиента для защиты пароля. Работает только в том случае, если ответ сервера `CAPABILITY` содержит строку `AUTH=CRAM-MD5`.168169#### `IMAP4.logout()`170171Закрывает соединение с сервером. Возвращает ответ сервера `BYE`.172173#### `IMAP4.lsub(directory='""', pattern='*')`174175Выводит список подписанных почтовых ящиков в указанном каталоге, соответствующих шаблону. По умолчанию *directory* – корневой каталог, а *pattern* – любой почтовый ящик. Возвращаемые данные – кортежи из конверта части сообщения и данных.176177#### `IMAP4.myrights(mailbox)`178179Показывает списки управления доступом (ACL) почтового ящика (т.е. права, которые у клиента есть на этот ящик).180181#### `IMAP4.namespace()`182183Возвращает пространства имён IMAP согласно RFC2342.184185#### `IMAP4.noop()`186187Отправляет `NOOP` на сервер.188189#### `IMAP4.open(host, port)`190191Открывает сокет к *port* на *host*. Этот метод неявно вызывается конструктором [`IMAP4`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4). Установленные этим методом объекты соединения будут использоваться в методах [`IMAP4.read()`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.read), [`IMAP4.readline()`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.readline), [`IMAP4.send()`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.send) и [`IMAP4.shutdown()`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.shutdown). Этот метод можно переопределить.192193#### `IMAP4.partial(message_num, message_part, start, length)`194195Извлекает усечённую часть сообщения. Возвращаемые данные – кортеж из конверта части сообщения и данных.196197#### `IMAP4.proxyauth(user)`198199Предполагает аутентификацию от имени пользователя *user*. Позволяет авторизованному администратору выполнять прокси-доступ к почтовому ящику любого пользователя.200201#### `IMAP4.read(size)`202203Читает *size* байт с удалённого сервера. Этот метод можно переопределить.204205#### `IMAP4.readline()`206207Читает одну строку с удалённого сервера. Этот метод можно переопределить.208209#### `IMAP4.recent()`210211Запрашивает у сервера обновление. Возвращаемые данные – `None`, если нет новых сообщений, иначе значение ответа `RECENT`.212213#### `IMAP4.rename(oldmailbox, newmailbox)`214215Переименовывает почтовый ящик с именем *oldmailbox* в *newmailbox*.216217#### `IMAP4.response(code)`218219Возвращает данные для ответа *code*, если он получен, или `None`. Возвращает указанный код, а не обычный тип.220221#### `IMAP4.search(charset, criterion[, ...])`222223Ищет в почтовом ящике сообщения, соответствующие критериям. *charset* может быть `None`, в этом случае в запросе к серверу не будет указан `CHARSET`. Протокол IMAP требует указания хотя бы одного критерия; при возврате ошибки сервером будет возбуждено исключение.224225Пример:226227```python228# M – это подключенный экземпляр IMAP4...229typ, msgnums = M.search(None, 'FROM', '"LDJ"')230231# или:232typ, msgnums = M.search(None, '(FROM "LDJ")')233```234235#### `IMAP4.select(mailbox='INBOX', readonly=False)`236237Выбирает почтовый ящик. Возвращаемые данные – количество сообщений в *mailbox* (ответ `EXISTS`). Ящик по умолчанию – *mailbox*, это `'INBOX'`. Если установлен флаг *readonly*, изменения в ящике запрещены.238239#### `IMAP4.send(data)`240241Отправляет `data` на удалённый сервер. Этот метод можно переопределить.242243#### `IMAP4.setacl(mailbox, who, what)`244245Устанавливает `ACL` для *mailbox*. Этот метод является нестандартным, но поддерживается сервером `Cyrus`.246247#### `IMAP4.setannotation(mailbox, entry, attribute[, ...])`248249Устанавливает `ANNOTATION` для *mailbox*. Этот метод является нестандартным, но поддерживается сервером `Cyrus`.250251#### `IMAP4.setquota(root, limits)`252253Устанавливает `quota` ресурса *root* – *limits*. Этот метод является частью расширения QUOTA протокола IMAP4, определённого в RFC 2087.254255#### `IMAP4.shutdown()`256257Закрывает соединение, установленное в `open`. Этот метод неявно вызывается [`IMAP4.logout()`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4.logout). Этот метод можно переопределить.258259#### `IMAP4.socket()`260261Возвращает экземпляр сокета, используемый для подключения к серверу.262263#### `IMAP4.sort(sort_criteria, charset, search_criterion[, ...])`264265Команда `sort` является разновидностью `search` с семантикой сортировки результатов. Возвращаемые данные содержат разделённый пробелами список номеров подходящих сообщений.266267У sort есть два аргумента перед *search\_criterion*: заключённый в скобки список *sort\_criteria* и *charset* для поиска. Обратите внимание: в отличие от `search`, аргумент *charset* является обязательным. Также существует команда `uid sort`, которая соотносится с `sort` так же, как `uid search` соотносится с `search`. Команда `sort` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях. Затем она возвращает номера подходящих сообщений.268269Это команда расширения `IMAP4rev1`.270271#### `IMAP4.starttls(ssl_context=None)`272273Отправляет команду `STARTTLS`. Аргумент *ssl\_context* является необязательным и должен быть объектом [`ssl.SSLContext`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext). Это включит шифрование для соединения IMAP. Чтобы узнать о лучших практиках, прочтите [*Рекомендации по безопасности*](https://python-all.ru/3.4/library/ssl.html#ssl-security).274275Новое в версии 3.2.276277Изменено в версии 3.4: Метод теперь поддерживает проверку имени хоста с помощью [`ssl.SSLContext.check_hostname`](https://python-all.ru/3.4/library/ssl.html#ssl.SSLContext.check_hostname) и *Server Name Indication* (см. [`ssl.HAS_SNI`](https://python-all.ru/3.4/library/ssl.html#ssl.HAS_SNI)).278279#### `IMAP4.status(mailbox, names)`280281Запрашивает именованные условия состояния для *mailbox*.282283#### `IMAP4.store(message_set, command, flag_list)`284285Изменяет установки флагов для сообщений в почтовом ящике. *command* задаётся разделом 6.4.6 [**RFC 2060**](https://python-all.ru/3.4/library/imaplib.html) и может быть одним из «FLAGS», «+FLAGS» или «-FLAGS», опционально с суффиксом «.SILENT».286287Например, чтобы установить флаг удаления на все сообщения:288289```python290typ, data = M.search(None, 'ALL')291for num in data[0].split():292   M.store(num, '+FLAGS', '\\Deleted')293M.expunge()294```295296#### `IMAP4.subscribe(mailbox)`297298Подписаться на новый почтовый ящик.299300#### `IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])`301302Команда `thread` является вариантом `search` с семантикой threading для результатов. Возвращаемые данные содержат разделённый пробелами список участников threading.303304Участники ветвей состоят из нуля или более номеров сообщений, разделенных пробелами, указывающих последовательные родительские и дочерние элементы.305306Команда thread принимает два аргумента перед аргументом(ами) *search\_criterion*: *threading\_algorithm* и *charset* поиска. Обратите внимание, что в отличие от `search`, аргумент *charset* поиска является обязательным. Также существует команда `uid thread`, которая соответствует `thread` так же, как `uid search` соответствует `search`. Команда `thread` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает соответствующие сообщения, сгруппированные в соответствии с заданным алгоритмом threading.307308Это расширенная команда `IMAP4rev1`.309310#### `IMAP4.uid(command, arg[, ...])`311312Выполняет команду с аргументами для сообщений, идентифицированных по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан по крайней мере один аргумент; если ни одного не передано, сервер вернет ошибку, и будет возбуждено исключение.313314#### `IMAP4.unsubscribe(mailbox)`315316Отписаться от старого почтового ящика.317318#### `IMAP4.xatom(name[, ...])`319320Разрешает простые расширенные команды, уведомляемые сервером в ответе `CAPABILITY`.321322Следующие атрибуты определены для экземпляров [`IMAP4`](https://python-all.ru/3.4/library/imaplib.html#imaplib.IMAP4):323324#### `IMAP4.PROTOCOL_VERSION`325326Последняя поддерживаемая версия протокола в ответе `CAPABILITY` от сервера.327328#### `IMAP4.debug`329330Целое число для управления отладочным выводом. Начальное значение берётся из модульной переменной `Debug`. Значения больше трёх трассируют каждую команду.331332## 21.15.2. Пример IMAP4333334Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:335336```python337import getpass, imaplib338339M = imaplib.IMAP4()340M.login(getpass.getuser(), getpass.getpass())341M.select()342typ, data = M.search(None, 'ALL')343for num in data[0].split():344    typ, data = M.fetch(num, '(RFC822)')345    print('Message %s\n%s\n' % (num, data[0][1]))346M.close()347M.logout()348```349