# `email` — An email and MIME handling package

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

The `email` package is a library for managing email messages. It is specifically not designed to do any sending of email messages to SMTP (RFC 2821), NNTP, or other servers; those are functions of modules such as `smtplib`. The `email` package attempts to be as RFC-compliant as possible, supporting RFC 5322 and RFC 6532, as well as such MIME-related RFCs as RFC 2045, RFC 2046, RFC 2047, RFC 2183, and RFC 2231.

Загальну структуру пакета електронної пошти можна розділити на три основні компоненти, плюс четвертий компонент, який контролює поведінку інших компонентів.

Центральним компонентом пакету є «об’єктна модель», яка представляє повідомлення електронної пошти. Програма взаємодіє з пакетом переважно через інтерфейс об’єктної моделі, визначений у підмодулі `message`. Програма може використовувати цей API, щоб ставити запитання щодо наявного електронного листа, створювати новий електронний лист або додавати чи видаляти підкомпоненти електронної пошти, які самі використовують той самий інтерфейс об’єктної моделі. Тобто, відповідно до природи повідомлень електронної пошти та їхніх підкомпонентів MIME, об’єктна модель електронної пошти є деревовидною структурою об’єктів, усі з яких забезпечують API `EmailMessage`.

Двома іншими основними компонентами пакета є `parser` і `generator`. Синтаксичний аналізатор бере серіалізовану версію повідомлення електронної пошти (потік байтів) і перетворює його на дерево об’єктів `EmailMessage`. Генератор приймає `EmailMessage` і перетворює його назад на серіалізований потік байтів. (Антаксичний аналізатор і генератор також обробляють потоки текстових символів, але таке використання не рекомендується, оскільки надто легко отримати повідомлення, які тим чи іншим чином є недійсними.)

Керуючим компонентом є модуль `policy`. Кожен `EmailMessage`, кожен `generator` і кожен `parser` має пов’язаний об’єкт `policy`, який контролює його поведінку. Зазвичай програмі потрібно лише вказати політику, коли створюється `EmailMessage`, шляхом безпосереднього створення екземпляра `EmailMessage` для створення нового електронного листа або аналізу вхідний потік за допомогою `parser`. Але політику можна змінити, якщо повідомлення серіалізовано за допомогою `generator`. Це дозволяє, наприклад, аналізувати загальне повідомлення електронної пошти з диска, але серіалізувати його за допомогою стандартних параметрів SMTP під час надсилання на сервер електронної пошти.

Пакет електронної пошти робить усе можливе, щоб приховати деталі різних керівних RFC від програми. Концептуально програма повинна мати можливість розглядати повідомлення електронної пошти як структуроване дерево тексту Юнікод і двійкових вкладень, не турбуючись про те, як вони представлені під час серіалізації. На практиці, однак, часто необхідно знати принаймні деякі правила, що регулюють повідомлення MIME та їхню структуру, зокрема назви та природу «типів вмісту» MIME та те, як вони ідентифікують багатокомпонентні документи. Здебільшого ці знання потрібні лише для більш складних застосувань, і навіть тоді це має бути лише структура високого рівня, а не деталі того, як ці структури представлені. Оскільки типи вмісту MIME широко використовуються в сучасному Інтернет-програмному забезпеченні (не лише в електронній пошті), це буде знайомим поняттям для багатьох програмістів.

У наступних розділах описується функціональність пакета `email`. Ми починаємо з об’єктної моделі `message`, яка є основним інтерфейсом, який використовуватиме додаток, і продовжуємо це з `parser` і `generator` компоненти. Потім ми розглядаємо елементи керування `policy`, що завершує обробку основних компонентів бібліотеки.

У наступних трьох розділах розглядаються винятки, які може викликати пакунок, і дефекти (невідповідність RFC), які може виявити `parser`. Далі ми розглядаємо підкомпоненти `headerregistry` і `contentmanager`, які надають інструменти для більш детального маніпулювання заголовками та корисними навантаженнями відповідно. Обидва ці компоненти містять функції, пов’язані зі споживанням і створенням нетривіальних повідомлень, але також документують їхні API розширюваності, які будуть цікаві для розширених програм.

Після них наведено набір прикладів використання основних частин API, розглянутих у попередніх розділах.

Вищезазначене представляє сучасний (дружній до Unicode) API пакета електронної пошти. Решта розділів, починаючи з класу `Message`, охоплюють застарілий API `compat32`, який має набагато більш пряме справу з деталями представлення повідомлень електронної пошти. `compat32` API не приховує деталі RFC від програми, але для програм, яким потрібно працювати на цьому рівні, вони можуть бути корисними інструментами. Ця документація також актуальна для програм, які все ще використовують `compat32` API з причин зворотної сумісності.

Змінено в версії 3.6: Документи реорганізовано та переписано для просування нового `EmailMessage`/`EmailPolicy` API.

Вміст документації пакета `email`:

- `email.message`: Representing an email message
- `email.parser`: Parsing email messages
  - FeedParser API
  - Parser API
  - Additional notes
- `email.generator`: Generating MIME documents
- `email.policy`: Policy Objects
- `email.errors`: Exception and Defect classes
- `email.headerregistry`: Custom Header Objects
- `email.contentmanager`: Managing MIME Content
  - Content Manager Instances
- `email`: Examples

Застарілий API:

- `email.message.Message`: Representing an email message using the `compat32` API
- `email.mime`: Creating email and MIME objects from scratch
- `email.header`: Internationalized headers
- `email.charset`: Representing character sets
- `email.encoders`: Encoders
- `email.utils`: Miscellaneous utilities
- `email.iterators`: Iterators

Дивись також

Модуль `smtplib`

  Клієнт SMTP (Simple Mail Transport Protocol).

Модуль `poplib`

  Клієнт POP (Post Office Protocol).

Модуль `imaplib`

  Клієнт IMAP (Internet Message Access Protocol).

Модуль `mailbox`

  Інструменти для створення, читання та керування колекціями повідомлень на диску з використанням різноманітних стандартних форматів.