`imaplib.md`

695 строк · 25.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/imaplib.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.13. `imaplib` – клиент протокола IMAP489Этот модуль определяет три класса: [`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4), [`IMAP4_SSL`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4_SSL) и [`IMAP4_stream`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4_stream), которые инкапсулируют соединение с сервером IMAP4 и реализуют большой подмножество клиентского протокола IMAP4rev1, определённого в [**RFC 2060**](https://python-all.ru/3.1/library/imaplib.html). Он обратно совместим с серверами IMAP4 ([**RFC 1730**](https://python-all.ru/3.1/library/imaplib.html)), но следует учесть, что команда `STATUS` в IMAP4 не поддерживается.1011Модуль `imaplib` предоставляет три класса, [`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4) является базовым классом:1213#### `class imaplib.IMAP4(host='', port=IMAP4_PORT)`1415Этот класс реализует протокол IMAP4. Соединение создается, а версия протокола (IMAP4 или IMAP4rev1) определяется при инициализации экземпляра. Если1617*host*1819не указан, используется2021`''`2223(локальный хост). Если2425*port*2627опущен, используется стандартный порт IMAP4 (143).2829Три исключения определены как атрибуты класса [`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4):3031#### `exception IMAP4.error`3233Исключение возникает при любых ошибках. Причина исключения передаётся конструктору в виде строки.3435#### `exception IMAP4.abort`3637Ошибки сервера IMAP4 вызывают это исключение. Оно является подклассом3839[`IMAP4.error`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4.error)4041. Обратите внимание, что закрытие экземпляра и создание нового обычно позволяет восстановиться после этого исключения.4243#### `exception IMAP4.readonly`4445Это исключение возникает, когда сервер изменяет статус почтового ящика, доступного для записи. Оно является подклассом4647[`IMAP4.error`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4.error)4849. Теперь какой-то другой клиент имеет права на запись, и для повторного получения прав на запись потребуется открыть ящик заново.5051Также существует подкласс для безопасных соединений:5253#### `class imaplib.IMAP4_SSL(host='', port=IMAP4_SSL_PORT, keyfile=None, certfile=None)`5455Это подкласс5657[`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4)5859, который подключается через SSL-шифрованный сокет (для использования этого класса нужен модуль socket, скомпилированный с поддержкой SSL). Если6061*host*6263не указан, используется6465`''`6667(локальный хост). Если6869*port*7071опущен, используется стандартный IMAP4-over-SSL порт (993).7273*keyfile*7475и7677*certfile*7879также необязательны – они могут содержать PEM-форматированный закрытый ключ и файл цепочки сертификатов для SSL-соединения.8081Второй подкласс предназначен для соединений, создаваемых дочерним процессом:8283#### `class imaplib.IMAP4_stream(command)`8485Это подкласс, производный от8687[`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4)8889, который подключается к файловым дескрипторам9091`stdin/stdout`9293, созданным передачей9495*command*9697в9899`subprocess.Popen()`100101.102103Определены следующие вспомогательные функции:104105#### `imaplib.Internaldate2tuple(datestr)`106107Преобразует строку INTERNALDATE IMAP4 во всемирное координированное время. Возвращает кортеж модуля108109[`time`](https://python-all.ru/3.1/library/time.html#module-time)110111.112113#### `imaplib.Int2AP(num)`114115Преобразует целое число в строковое представление, используя символы из набора \[116117`A`118119..120121`P`122123\].124125#### `imaplib.ParseFlags(flagstr)`126127Преобразует ответ IMAP4128129`FLAGS`130131в кортеж отдельных флагов.132133#### `imaplib.Time2Internaldate(date_time)`134135Преобразует кортеж модуля136137[`time`](https://python-all.ru/3.1/library/time.html#module-time)138139в представление IMAP4140141`INTERNALDATE`142143. Возвращает строку вида:144145`"DD-Mmm-YYYY HH:MM:SS +HHMM"`146147(включая dвойные кавычки).148149Обратите внимание, что номера сообщений IMAP4 изменяются при изменении почтового ящика; в частности, после выполнения команды `EXPUNGE`, удаляющей сообщения, оставшиеся сообщения перенумеровываются. Поэтому настоятельно рекомендуется использовать UID с командой UID.150151В конце модуля есть тестовый раздел, содержащий более полный пример использования.152153> **См. также**154>155> Документы, описывающие протокол, а также исходные коды и бинарные сборки для серверов, реализующих его, можно найти в *IMAP Information Center* Вашингтонского университета ([http://www.washington.edu/imap/](https://python-all.ru/3.1/library/imaplib.html)).156157## 20.13.1. Объекты IMAP4158159Все команды IMAP4rev1 представлены методами с теми же именами, в верхнем или нижнем регистре.160161Все аргументы команд преобразуются в строки, за исключением `AUTHENTICATE` и последнего аргумента `APPEND`, который передаётся как литерал IMAP4. При необходимости (если строка содержит символы, чувствительные к протоколу IMAP4, и не заключена в круглые скобки или двойные кавычки) каждая строка заключается в кавычки. Однако аргумент *password* команды `LOGIN` всегда заключается в кавычки. Если требуется избежать заключения строки аргумента в кавычки (например, аргумент *flags* команды `STORE`), то заключите строку в круглые скобки (например: `r'(\Deleted)'`).162163Каждая команда возвращает кортеж: `(type, [data, ...])`, где *type* обычно равно `'OK'` или `'NO'`, а *data* – это либо текст ответа команды, либо обязательные результаты команды. Каждый *data* – это строка или кортеж. Если это кортеж, то первая часть – заголовок ответа, а вторая часть содержит данные (т.е. «литеральное» значение).164165Параметр *message\_set* в командах ниже – это строка, задающая одно или несколько сообщений, над которыми нужно выполнить действие. Это может быть простой номер сообщения (`'1'`), диапазон номеров сообщений (`'2:4'`) или группа несмежных диапазонов, разделённых запятыми (`'1:3,6:9'`). Диапазон может содержать звёздочку для обозначения бесконечной верхней границы (`'3:*'`).166167Экземпляр [`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4) имеет следующие методы:168169#### `IMAP4.append(mailbox, flags, date_time, message)`170171Добавляет172173*message*174175в указанный почтовый ящик.176177#### `IMAP4.authenticate(mechanism, authobject)`178179Команда аутентификации – требуется обработка ответа.180181*mechanism* указывает, какой механизм аутентификации следует использовать; он должен присутствовать в переменной экземпляра `capabilities` в форме `AUTH=mechanism`.182183*authobject* должен быть вызываемым объектом:184185```python186data = authobject(response)187```188189Она будет вызвана для обработки серверных ответов продолжения. Она должна возвращать `data`, которые будут закодированы и отправлены на сервер. Она должна возвращать `None`, если вместо этого должен быть отправлен ответ `*` об отмене клиентом.190191#### `IMAP4.check()`192193Контрольная точка почтового ящика на сервере.194195#### `IMAP4.close()`196197Закрывает текущий выбранный почтовый ящик. Удаленные сообщения удаляются из доступного для записи почтового ящика. Это рекомендуемая команда перед198199`LOGOUT`200201.202203#### `IMAP4.copy(message_set, new_mailbox)`204205Копирует сообщения206207*message\_set*208209в конец210211*new\_mailbox*212213.214215#### `IMAP4.create(mailbox)`216217Создаёт новый почтовый ящик с именем218219*mailbox*220221.222223#### `IMAP4.delete(mailbox)`224225Удаляет старый почтовый ящик с именем226227*mailbox*228229.230231#### `IMAP4.deleteacl(mailbox, who)`232233Удалить ACL (убрать все права), установленные для who на mailbox.234235#### `IMAP4.expunge()`236237Окончательно удаляет удаленные сообщения из выбранного почтового ящика. Генерирует ответ238239`EXPUNGE`240241для каждого удаленного сообщения. Возвращаемые данные содержат список номеров сообщений242243`EXPUNGE`244245в порядке получения.246247#### `IMAP4.fetch(message_set, message_parts)`248249Извлекает (части) сообщений.250251*message\_parts*252253должна быть строкой с именами частей сообщения, заключенными в круглые скобки, например:254255`"(UID BODY[TEXT])"`256257. Возвращаемые данные представляют собой кортежи, содержащие конверт и данные части сообщения.258259#### `IMAP4.getacl(mailbox)`260261Получает262263`ACL`264265для266267*mailbox*268269. Этот метод является нестандартным, но поддерживается сервером270271`Cyrus`272273.274275#### `IMAP4.getannotation(mailbox, entry, attribute)`276277Извлекает указанные278279`ANNOTATION`280281для282283*mailbox*284285. Метод является нестандартным, но поддерживается сервером286287`Cyrus`288289.290291#### `IMAP4.getquota(root)`292293Получает использование ресурсов и лимиты294295`quota`296297*root*298299. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.300301#### `IMAP4.getquotaroot(mailbox)`302303Получает список304305`quota`306307`roots`308309для указанного310311*mailbox*312313. Этот метод является частью расширения QUOTA IMAP4, определённого в RFC 2087.314315#### `IMAP4.list([directory[, pattern]])`316317Выводит имена почтовых ящиков в318319*directory*320321, соответствующие322323*pattern*324325.326327*directory*328329по умолчанию равен корневой почтовой папке, а330331*pattern*332333по умолчанию соответствует всему. Возвращаемые данные содержат список ответов334335`LIST`336337.338339#### `IMAP4.login(user, password)`340341Идентифицирует клиента с помощью пароля в открытом виде. Параметр342343*password*344345будет заключён в кавычки.346347#### `IMAP4.login_cram_md5(user, password)`348349Принудительно использует аутентификацию350351`CRAM-MD5`352353при идентификации клиента для защиты пароля. Работает только в том случае, если ответ сервера354355`CAPABILITY`356357содержит строку358359`AUTH=CRAM-MD5`360361.362363#### `IMAP4.logout()`364365Закрывает соединение с сервером. Возвращает ответ сервера366367`BYE`368369.370371#### `IMAP4.lsub(directory='""', pattern='*')`372373Выводит список подписанных почтовых ящиков в указанном каталоге, соответствующих шаблону. По умолчанию374375*directory*376377– корневой каталог, а378379*pattern*380381– любой почтовый ящик. Возвращаемые данные – кортежи из конверта части сообщения и данных.382383#### `IMAP4.myrights(mailbox)`384385Показывает списки управления доступом (ACL) почтового ящика (т.е. права, которые у клиента есть на этот ящик).386387#### `IMAP4.namespace()`388389Возвращает пространства имён IMAP согласно RFC2342.390391#### `IMAP4.noop()`392393Отправляет394395`NOOP`396397на сервер.398399#### `IMAP4.open(host, port)`400401Открывает сокет для подключения к порту402403*порт*404405на хосте406407*хост*408409. Этот метод неявно вызывается конструктором410411[`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4)412413. Объекты соединения, созданные этим методом, будут использоваться в методах414415`read`416417,418419`readline`420421,422423`send`424425и426427`shutdown`428429. Этот метод можно переопределить.430431#### `IMAP4.partial(message_num, message_part, start, length)`432433Извлекает усечённую часть сообщения. Возвращаемые данные – кортеж из конверта части сообщения и данных.434435#### `IMAP4.proxyauth(user)`436437Предполагает аутентификацию от имени пользователя438439*user*440441. Позволяет авторизованному администратору выполнять прокси-доступ к почтовому ящику любого пользователя.442443#### `IMAP4.read(size)`444445Читает446447*size*448449байт с удалённого сервера. Этот метод можно переопределить.450451#### `IMAP4.readline()`452453Читает одну строку с удалённого сервера. Этот метод можно переопределить.454455#### `IMAP4.recent()`456457Запрашивает у сервера обновление. Возвращаемые данные –458459`None`460461, если нет новых сообщений, иначе значение ответа462463`RECENT`464465.466467#### `IMAP4.rename(oldmailbox, newmailbox)`468469Переименовывает почтовый ящик с именем470471*oldmailbox*472473в474475*newmailbox*476477.478479#### `IMAP4.response(code)`480481Возвращает данные для ответа482483*code*484485, если он получен, или486487`None`488489. Возвращает указанный код, а не обычный тип.490491#### `IMAP4.search(charset, criterion[, ...])`492493Ищет в почтовом ящике сообщения, соответствующие критериям. *charset* может быть `None`, в этом случае в запросе к серверу не будет указан `CHARSET`. Протокол IMAP требует указания хотя бы одного критерия; при возврате ошибки сервером будет возбуждено исключение.494495Пример:496497```python498# M – это подключенный экземпляр IMAP4...499typ, msgnums = M.search(None, 'FROM', '"LDJ"')500501# или:502typ, msgnums = M.search(None, '(FROM "LDJ")')503```504505#### `IMAP4.select(mailbox='INBOX', readonly=False)`506507Выбирает почтовый ящик. Возвращаемые данные – количество сообщений в508509*mailbox*510511(ответ512513`EXISTS`514515). Ящик по умолчанию –516517*mailbox*518519, это520521`'INBOX'`522523. Если установлен флаг524525*readonly*526527, изменения в ящике запрещены.528529#### `IMAP4.send(data)`530531Отправляет532533`data`534535на удалённый сервер. Этот метод можно переопределить.536537#### `IMAP4.setacl(mailbox, who, what)`538539Устанавливает540541`ACL`542543для544545*mailbox*546547. Этот метод является нестандартным, но поддерживается сервером548549`Cyrus`550551.552553#### `IMAP4.setannotation(mailbox, entry, attribute[, ...])`554555Устанавливает556557`ANNOTATION`558559для560561*mailbox*562563. Этот метод является нестандартным, но поддерживается сервером564565`Cyrus`566567.568569#### `IMAP4.setquota(root, limits)`570571Устанавливает572573`quota`574575ресурса576577*root*578579–580581*limits*582583. Этот метод является частью расширения QUOTA протокола IMAP4, определённого в RFC 2087.584585#### `IMAP4.shutdown()`586587Закрывает соединение, установленное в588589`open`590591. Этот метод неявно вызывается592593[`IMAP4.logout()`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4.logout)594595. Этот метод можно переопределить.596597#### `IMAP4.socket()`598599Возвращает экземпляр сокета, используемый для подключения к серверу.600601#### `IMAP4.sort(sort_criteria, charset, search_criterion[, ...])`602603Команда `sort` является разновидностью `search` с семантикой сортировки результатов. Возвращаемые данные содержат разделённый пробелами список номеров подходящих сообщений.604605У sort есть два аргумента перед *search\_criterion*: заключённый в скобки список *sort\_criteria* и *charset* для поиска. Обратите внимание: в отличие от `search`, аргумент *charset* является обязательным. Также существует команда `uid sort`, которая соотносится с `sort` так же, как `uid search` соотносится с `search`. Команда `sort` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях. Затем она возвращает номера подходящих сообщений.606607Это расширенная команда `IMAP4rev1`.608609#### `IMAP4.status(mailbox, names)`610611Запрашивает именованные условия состояния для612613*mailbox*614615.616617#### `IMAP4.store(message_set, command, flag_list)`618619Изменяет состояния флагов для сообщений в почтовом ящике. Параметр *command* задаётся в разделе 6.4.6 документа [**RFC 2060**](https://python-all.ru/3.1/library/imaplib.html) как одно из значений «FLAGS», «+FLAGS» или «-FLAGS», возможно с суффиксом «.SILENT».620621Например, чтобы установить флаг удаления на все сообщения:622623```python624typ, data = M.search(None, 'ALL')625for num in data[0].split():626   M.store(num, '+FLAGS', '\\Deleted')627M.expunge()628```629630#### `IMAP4.subscribe(mailbox)`631632Подписаться на новый почтовый ящик.633634#### `IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])`635636Команда `thread` является вариантом `search` с семантикой threading для результатов. Возвращаемые данные содержат разделённый пробелами список участников threading.637638Участники ветвей состоят из нуля или более номеров сообщений, разделенных пробелами, указывающих последовательные родительские и дочерние элементы.639640Команда thread принимает два аргумента перед аргументом(ами) *search\_criterion*: *threading\_algorithm* и *charset* поиска. Обратите внимание, что в отличие от `search`, аргумент *charset* поиска является обязательным. Также существует команда `uid thread`, которая соответствует `thread` так же, как `uid search` соответствует `search`. Команда `thread` сначала ищет в почтовом ящике сообщения, соответствующие заданным критериям поиска, используя аргумент charset для интерпретации строк в критериях поиска. Затем она возвращает соответствующие сообщения, сгруппированные в соответствии с заданным алгоритмом threading.641642Это расширенная команда `IMAP4rev1`.643644#### `IMAP4.uid(command, arg[, ...])`645646Выполняет команду с аргументами для сообщений, идентифицированных по UID, а не по номеру сообщения. Возвращает ответ, соответствующий команде. Должен быть указан по крайней мере один аргумент; если ни одного не передано, сервер вернет ошибку, и будет возбуждено исключение.647648#### `IMAP4.unsubscribe(mailbox)`649650Отписаться от старого почтового ящика.651652#### `IMAP4.xatom(name[, ...])`653654Разрешает простые расширенные команды, уведомляемые сервером в ответе655656`CAPABILITY`657658.659660Следующие атрибуты определены для экземпляров [`IMAP4`](https://python-all.ru/3.1/library/imaplib.html#imaplib.IMAP4):661662#### `IMAP4.PROTOCOL_VERSION`663664Последняя поддерживаемая версия протокола в ответе665666`CAPABILITY`667668от сервера.669670#### `IMAP4.debug`671672Целое число для управления отладочным выводом. Начальное значение берётся из модульной переменной673674`Debug`675676. Значения больше трёх трассируют каждую команду.677678## 20.13.2. Пример IMAP4679680Вот минимальный пример (без проверки ошибок), который открывает почтовый ящик и извлекает и выводит все сообщения:681682```python683import getpass, imaplib684685M = imaplib.IMAP4()686M.login(getpass.getuser(), getpass.getpass())687M.select()688typ, data = M.search(None, 'ALL')689for num in data[0].split():690    typ, data = M.fetch(num, '(RFC822)')691    print('Message %s\n%s\n' % (num, data[0][1]))692M.close()693M.logout()694```695