# `imaplib` — IMAP4 protocol client

Вихідний код: Lib/imaplib.py

Цей модуль визначає три класи: `IMAP4`, `IMAP4_SSL` і `IMAP4_stream`, які інкапсулюють підключення до сервера IMAP4 і реалізують велику підмножину клієнтського протоколу IMAP4rev1, як визначено в RFC 2060. Він зворотно сумісний із серверами IMAP4 (RFC 1730), але зауважте, що команда `STATUS` не підтримується в IMAP4.

Availability: not WASI.

This module does not work or is not available on WebAssembly. See WebAssembly platforms for more information.

Three classes are provided by the `imaplib` module, `IMAP4` is the base class:

class imaplib.IMAP4(host='', port=IMAP4_PORT, timeout=None)

  This class implements the actual IMAP4 protocol. The connection is created and protocol version (IMAP4 or IMAP4rev1) is determined when the instance is initialized. If host is not specified, `''` (the local host) is used. If port is omitted, the standard IMAP4 port (143) is used. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is `None`, the global default socket timeout is used.

  Клас `IMAP4` підтримує оператор `with`. При такому використанні команда `LOGOUT` IMAP4 виконується автоматично, коли завершується оператор `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 не вказано, використовується `''` (локальний хост). Якщо порт не вказано, використовується стандартний порт IMAP4 через SSL (993). ssl_context — це об’єкт `ssl.SSLContext`, який дозволяє об’єднувати параметри конфігурації SSL, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

  The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is `None`, the global default socket timeout is used.

  Змінено в версії 3.3: Додано параметр ssl_context.

  Змінено в версії 3.4: The class now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

  Змінено в версії 3.9: Додано необов’язковий параметр timeout.

  Змінено в версії 3.12: The deprecated keyfile and certfile parameters have been removed.

Другий підклас дозволяє з’єднання, створені дочірнім процесом:

class imaplib.IMAP4_stream(command)

  Це підклас, похідний від `IMAP4`, який підключається до файлових дескрипторів `stdin/stdout`, створених передачею команди до `subprocess.Popen()`.

Визначаються наступні функції корисності:

imaplib.Internaldate2tuple(datestr)

  Проаналізуйте рядок `INTERNALDATE` IMAP4 і поверніть відповідний місцевий час. Поверненим значенням є `time.struct_time` кортеж або `None`, якщо рядок має неправильний формат.

imaplib.Int2AP(num)

  Перетворює ціле число на представлення байтів за допомогою символів із набору [`A` .. `P`].

imaplib.ParseFlags(flagstr)

  Перетворює відповідь `FLAGS` IMAP4 на кортеж окремих прапорів.

imaplib.Time2Internaldate(date_time)

  Перетворіть date_time на представлення `INTERNALDATE` IMAP4. Поверненим значенням є рядок у формі: `"ДД-МММ-РРРР ГГ:ХМ:СС +ГГММ"` (включаючи подвійні лапки). Аргумент date_time може бути числом (int або float), що представляє секунди з епохи (як повертає `time.time()`), 9-кортеж, що представляє місцевий час, екземпляр `time.struct_time` (як повертає `time.localtime()`), відомий екземпляр `datetime.datetime` або рядок у подвійних лапках. В останньому випадку передбачається, що він уже має правильний формат.

Зверніть увагу, що номери повідомлень IMAP4 змінюються разом зі зміною поштової скриньки; зокрема, після видалення командою `EXPUNGE` повідомлення, що залишилися, перенумеровуються. Тому вкрай доцільно використовувати натомість UID з командою UID.

Наприкінці модуля є тестовий розділ, який містить докладніший приклад використання.

Дивись також

Документи, що описують протокол, джерела для серверів, які його реалізують, Інформаційний центр IMAP Університету Вашингтона можна знайти за адресою (Вихідний код) https://github.com/uw-imap/imap (Не підтримується).

## Об’єкти IMAP4

All IMAP4rev1 commands are represented by methods of the same name, either uppercase or lowercase.

Усі аргументи команд перетворюються на рядки, за винятком `AUTHENTICATE` і останнього аргументу `APPEND`, який передається як літерал IMAP4. Якщо необхідно (рядок містить чутливі до протоколу IMAP4 символи та не взятий ні в дужки, ні в подвійні лапки), кожен рядок береться в лапки. Однак аргумент password для команди `LOGIN` завжди береться в лапки. Якщо ви хочете уникнути рядка аргументу в лапках (наприклад, аргумент flags для `STORE`), то візьміть рядок у круглі дужки (наприклад: `r'(\Deleted)'`).

Most commands return a tuple: `(type, [data, ...])` where type is usually `'OK'` or `'NO'`, and data is either the text from the command response, or mandated results from the command. Each data is either a `bytes`, or a tuple. If a tuple, then the first part is the header of the response, and the second part contains the data (ie: „literal“ value).

Параметри message_set для наведених нижче команд — це рядок, що вказує на одне або кілька повідомлень, які потрібно виконати. Це може бути простий номер повідомлення (`'1'`), діапазон номерів повідомлень (`'2:4'`) або група несуміжних діапазонів, розділених комами (`'1 :3,6:9''`). Діапазон може містити зірочку для позначення нескінченної верхньої межі (`'3:*'`).

Екземпляр `IMAP4` має такі методи:

IMAP4.append(mailbox, flags, date_time, message)

  Додайте повідомлення до вказаної поштової скриньки.

  flags may be `None` or a string of IMAP flag tokens. Multiple flags are separated by spaces, for example `r'\Seen \Answered'`. If flags is not already enclosed in parentheses, parentheses are added automatically.

IMAP4.authenticate(mechanism, authobject)

  Команда автентифікації — вимагає обробки відповіді.

  mechanism вказує, який механізм автентифікації буде використано - він має відображатися в змінній екземпляра `capabilities` у формі `AUTH=mechanism`.

  authobject повинен бути викликаним об’єктом:

      data = authobject(response)

  Він буде викликаний для обробки відповідей продовження сервера; аргумент відповідь, який він передає, буде `байт`. Він має повернути `байти` дані, які будуть закодовані в base64 і надіслані на сервер. Він має повертати `None`, якщо замість цього потрібно надіслати відповідь `*` про переривання клієнта.

  Змінено в версії 3.5: рядкові імена користувачів і паролі тепер кодуються як `utf-8` замість обмеження ASCII.

IMAP4.check()

  Контрольна поштова скринька на сервері.

IMAP4.close()

  Закрити вибрану поштову скриньку. Видалені повідомлення видаляються з доступної для запису поштової скриньки. Це рекомендована команда перед `ВИХОДОМ`.

IMAP4.copy(message_set, new_mailbox)

  Скопіюйте повідомлення message_set у кінець new_mailbox.

IMAP4.create(mailbox)

  Створіть нову поштову скриньку з назвою mailbox.

IMAP4.delete(mailbox)

  Видалити стару поштову скриньку з назвою mailbox.

IMAP4.deleteacl(mailbox, who)

  Видалити списки керування доступом (вилучити будь-які права), встановлені для поштової скриньки who.

IMAP4.enable(capability)

  Увімкнути можливість (див. RFC 5161). Більшість можливостей не потрібно вмикати. Наразі підтримується лише можливість `UTF8=ACCEPT` (див. RFC 6855).

  Added in version 3.5: Сам метод `enable()` і підтримка RFC 6855.

IMAP4.expunge()

  Назавжди видалити видалені елементи з вибраної поштової скриньки. Генерує відповідь `EXPUNGE` для кожного видаленого повідомлення. Повернуті дані містять список номерів повідомлень `EXPUNGE` у порядку отримання.

IMAP4.fetch(message_set, message_parts)

  Отримати (частини) повідомлень. message_parts має бути рядком імен частин повідомлення, укладених у круглі дужки, наприклад: `"(UID BODY[TEXT])`. Повернуті дані – це кортежі конверта частини повідомлення та даних.

IMAP4.getacl(mailbox)

  Отримайте `ACL` для поштової скриньки. Метод нестандартний, але підтримується сервером `Cyrus`.

IMAP4.getannotation(mailbox, entry, attribute)

  Отримати вказані `АННОТАЦІЇ` для поштової скриньки. Метод нестандартний, але підтримується сервером `Cyrus`.

IMAP4.getquota(root)

  Отримайте `квоту` root щодо використання ресурсів і обмежень. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.

IMAP4.getquotaroot(mailbox)

  Отримайте список `квоти` `roots` для вказаної поштової скриньки. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.

IMAP4.idle(duration=None)

  Return an `Idler`: an iterable context manager implementing the IMAP4 `IDLE` command as defined in RFC 2177.

  The returned object sends the `IDLE` command when activated by the `with` statement, produces IMAP untagged responses via the iterator protocol, and sends `DONE` upon context exit.

  All untagged responses that arrive after sending the `IDLE` command (including any that arrive before the server acknowledges the command) will be available via iteration. Any leftover responses (those not iterated in the `with` context) can be retrieved in the usual way after `IDLE` ends, using `IMAP4.response()`.

  Responses are represented as `(type, [data, ...])` tuples, as described in IMAP4 Objects.

  The duration argument sets a maximum duration (in seconds) to keep idling, after which any ongoing iteration will stop. It can be an `int` or `float`, or `None` for no time limit. Callers wishing to avoid inactivity timeouts on servers that impose them should keep this at most 29 minutes (1740 seconds). Requires a socket connection; duration must be `None` on `IMAP4_stream` connections.

      >>> with M.idle(duration=29 * 60) as idler:
      ...     for typ, data in idler:
      ...         print(typ, data)
      ...
      EXISTS [b'1']
      RECENT [b'1']

  Idler.burst(interval=0.1)

    Yield a burst of responses no more than interval seconds apart (expressed as an `int` or `float`).

    This generator is an alternative to iterating one response at a time, intended to aid in efficient batch processing. It retrieves the next response along with any immediately available subsequent responses. (For example, a rapid series of `EXPUNGE` responses after a bulk delete.)

    Requires a socket connection; does not work on `IMAP4_stream` connections.

        >>> with M.idle() as idler:
        ...     # get a response and any others following by < 0.1 seconds
        ...     batch = list(idler.burst())
        ...     print(f'processing {len(batch)} responses...')
        ...     print(batch)
        ...
        processing 3 responses...
        [('EXPUNGE', [b'2']), ('EXPUNGE', [b'1']), ('RECENT', [b'0'])]

    Порада

    The `IDLE` context’s maximum duration, as passed to `IMAP4.idle()`, is respected when waiting for the first response in a burst. Therefore, an expired `Idler` will cause this generator to return immediately without producing anything. Callers should consider this if using it in a loop.

  Примітка

  The iterator returned by `IMAP4.idle()` is usable only within a `with` statement. Before or after that context, unsolicited responses are collected internally whenever a command finishes, and can be retrieved with `IMAP4.response()`.

  Примітка

  The `Idler` class name and structure are internal interfaces, subject to change. Calling code can rely on its context management, iteration, and public method to remain stable, but should not subclass, instantiate, compare, or otherwise directly reference the class.

  Added in version 3.14.

IMAP4.list([directory[, pattern]])

  Список імен поштових скриньок у каталозі, що відповідає шаблону. каталог за замовчуванням є текою електронної пошти верхнього рівня, а шаблон за замовчуванням відповідає будь-чому. Повернуті дані містять список відповідей `СПИСОК`.

IMAP4.login(user, password)

  Ідентифікуйте клієнта за допомогою відкритого пароля. Пароль буде взято в лапки.

IMAP4.login_cram_md5(user, password)

  Примусово використовувати автентифікацію `CRAM-MD5` під час ідентифікації клієнта, щоб захистити пароль. Працює, лише якщо відповідь сервера `CAPABILITY` містить фразу `AUTH=CRAM-MD5`.

  Змінено в версії 3.15: An `IMAP4.error` is raised if MD5 support is not available.

IMAP4.logout()

  Вимкніть з’єднання з сервером. Повертає відповідь сервера `BYE`.

  Змінено в версії 3.8: Метод більше не ігнорує мовчки довільні винятки.

IMAP4.lsub(directory='""', pattern='*')

  Список імен передплачених поштових скриньок у каталозі, що відповідає шаблону. каталог за замовчуванням є каталогом верхнього рівня, а шаблон за замовчуванням відповідає будь-якій поштовій скриньці. Повернуті дані – це кортежі конверта частини повідомлення та даних.

IMAP4.myrights(mailbox)

  Показати мої ACL для поштової скриньки (тобто права, які я маю на поштову скриньку).

IMAP4.namespace()

  Повертає простори імен IMAP, як визначено в RFC 2342.

IMAP4.noop()

  Надіслати `NOOP` на сервер.

IMAP4.open(host, port, timeout=None)

  Opens socket to port at host. The optional timeout parameter specifies a timeout in seconds for the connection attempt. If timeout is not given or is `None`, the global default socket timeout is used. Also note that if the timeout parameter is set to be zero, it will raise a `ValueError` to reject creating a non-blocking socket. This method is implicitly called by the `IMAP4` constructor. The connection objects established by this method will be used in the `IMAP4.read()`, `IMAP4.readline()`, `IMAP4.send()`, and `IMAP4.shutdown()` methods. You may override this method.

  Викликає подію аудиту `imaplib.open` з аргументами `self`, `host`, `port`.

  Змінено в версії 3.9: Додано параметр timeout.

IMAP4.partial(message_num, message_part, start, length)

  Отримати скорочену частину повідомлення. Повернуті дані — це кортеж із конверта частини повідомлення та даних.

IMAP4.proxyauth(user)

  Припустити автентифікацію як користувача. Дозволяє авторизованому адміністратору надсилати проксі до поштової скриньки будь-якого користувача.

IMAP4.read(size)

  Читає size байти з віддаленого сервера. Ви можете змінити цей метод.

IMAP4.readline()

  Читає один рядок з віддаленого сервера. Ви можете змінити цей метод.

IMAP4.recent()

  Запитувати сервер для оновлення. Повернені дані: `None`, якщо немає нових повідомлень, інакше значення відповіді `RECENT`.

IMAP4.rename(oldmailbox, newmailbox)

  Перейменуйте поштову скриньку з назвою oldmailbox на newmailbox.

IMAP4.response(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)

  Виберіть поштову скриньку. Повернені дані – це кількість повідомлень у поштовій скриньці (відповідь «ІСНУЄ»). Типовою поштовою скринькою є `'INBOX'`. Якщо встановлено прапорець readonly, зміни поштової скриньки заборонені.

IMAP4.send(data)

  Надсилає `дані` на віддалений сервер. Ви можете змінити цей метод.

  Викликає подію аудиту `imaplib.send` з аргументами `self`, `data`.

IMAP4.setacl(mailbox, who, what)

  Установіть `ACL` для поштової скриньки. Метод нестандартний, але підтримується сервером `Cyrus`.

IMAP4.setannotation(mailbox, entry, attribute[, ...])

  Установіть `АННОТАЦІЮ` для поштової скриньки. Метод нестандартний, але підтримується сервером `Cyrus`.

IMAP4.setquota(root, limits)

  Встановіть ліміти ресурсів `квоти` root. Цей метод є частиною розширення IMAP4 QUOTA, визначеного в rfc2087.

IMAP4.shutdown()

  Закрити з’єднання встановлено в `відкритому`. Цей метод неявно викликається `IMAP4.logout()`. Ви можете змінити цей метод.

IMAP4.socket()

  Повертає екземпляр сокета, який використовується для підключення до сервера.

IMAP4.sort(sort_criteria, charset, search_criterion[, ...])

  Команда `sort` є варіантом `search` із семантикою сортування для результатів. Повернуті дані містять розділений пробілами список відповідних номерів повідомлень.

  Сортування має два аргументи перед аргументом(ами) критерій_пошуку; список критеріїв_сортування в дужках і пошуковий набір символів. Зауважте, що на відміну від `search`, пошуковий аргумент charset є обов’язковим. Існує також команда `uid sort`, яка відповідає `sort` так, як `uid search` відповідає `search`. Команда `sort` спочатку шукає в поштовій скриньці повідомлення, які відповідають заданим критеріям пошуку, використовуючи аргумент набору символів для інтерпретації рядків у критеріях пошуку. Потім він повертає номери відповідних повідомлень.

  Це команда розширення `IMAP4rev1`.

IMAP4.starttls(ssl_context=None)

  Надішліть команду `STARTTLS`. Аргумент ssl_context є необов’язковим і має бути об’єктом `ssl.SSLContext`. Це дозволить шифрувати підключення IMAP. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

  Added in version 3.2.

  Змінено в версії 3.4: The method now supports hostname check with `ssl.SSLContext.check_hostname` and Server Name Indication (see `ssl.HAS_SNI`).

IMAP4.status(mailbox, names)

  Запит умов іменованого статусу для поштової скриньки.

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()

  Примітка

  Creating flags containing „]“ (for example: «[test]») violates RFC 3501 (the IMAP protocol). However, imaplib has historically allowed creation of such tags, and popular IMAP servers, such as Gmail, accept and produce such flags. There are non-Python programs which also create such tags. Although it is an RFC violation and IMAP clients and servers are supposed to be strict, imaplib still continues to allow such tags to be created for backward compatibility reasons, and as of Python 3.6, handles them if they are sent from the server, since this improves real-world compatibility.

IMAP4.subscribe(mailbox)

  Підписатися на нову скриньку.

IMAP4.thread(threading_algorithm, charset, search_criterion[, ...])

  Команда `thread` є варіантом `search` із семантикою потоків для результатів. Повернуті дані містять розділений пробілами список учасників потоку.

  Члени ланцюжка складаються з нуля або більше номерів повідомлень, розділених пробілами, що вказує на послідовне батьківське та дочірнє повідомлення.

  Thread 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.

  Це команда розширення `IMAP4rev1`.

IMAP4.uid(command, arg[, ...])

  Виконайте аргументи команди з повідомленнями, ідентифікованими 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.utf8_enabled

  Логічне значення, яке зазвичай має значення `False`, але встановлюється на `True`, якщо команда `enable()` успішно виконана для можливості `UTF8=ACCEPT`.

  Added in version 3.5.

property IMAP4.file

  Internal `BufferedReader` associated with the underlying socket. This property is documented for legacy purposes but not part of the public interface. The caller is responsible to ensure that the current file is closed before changing it.

  Deprecated since version 3.15, will be removed in version 3.19.

## Приклад 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()