imaplib — клієнт протоколу IMAP4

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

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

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.

Три класи надаються модулем imaplib, IMAP4 є базовим класом:

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

Цей клас реалізує фактичний протокол IMAP4. Під час ініціалізації екземпляра створюється з’єднання та визначається версія протоколу (IMAP4 або IMAP4rev1). Якщо host не вказано, використовується '' (локальний хост). Якщо порт не вказано, використовується стандартний порт IMAP4 (143). Додатковий параметр timeout визначає час очікування в секундах для спроби підключення. Якщо тайм-аут не вказано або має значення None, використовується глобальний тайм-аут сокета за замовчуванням.

Клас 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, сертифікати та приватні ключі в єдину (потенційно довговічну) структуру. Будь ласка, прочитайте Міркування безпеки, щоб дізнатися про найкращі практики.

Додатковий параметр timeout визначає час очікування в секундах для спроби підключення. Якщо тайм-аут не вказано або має значення None, використовується глобальний тайм-аут сокета за замовчуванням.

Змінено в версії 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)').

Кожна команда повертає кортеж: (type, [data, ...]), де type зазвичай 'OK'' або 'NO', а data є або текст із відповіді на команду або обов’язкові результати з команди. Кожні дані є або байтами, або кортежем. Якщо кортеж, то перша частина є заголовком відповіді, а друга частина містить дані (тобто: «літеральне» значення).

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

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

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

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

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.list([directory[, pattern]])

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

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)

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

IMAP4.namespace()

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

IMAP4.noop()

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

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

Відкриває сокет до порту на хості. Додатковий параметр timeout визначає час очікування в секундах для спроби підключення. Якщо тайм-аут не вказано або має значення None, використовується глобальний тайм-аут сокета за замовчуванням. Також зауважте, що якщо параметр timeout дорівнює нулю, це викличе ValueError, щоб відхилити створення неблокуючого сокета. Цей метод неявно викликається конструктором IMAP4. Об’єкти підключення, встановлені цим методом, використовуватимуться в методах IMAP4.read(), IMAP4.readline(), IMAP4.send() і IMAP4.shutdown(). Ви можете змінити цей метод.

Викликає подію аудиту 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()

Примітка

Створення прапорів, що містять „]“ (наприклад: «[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 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.

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