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 під час надсилання на сервер електронної пошти.

The email package does its best to hide the details of the various governing RFCs from the application. Conceptually the application should be able to treat the email message as a structured tree of Unicode text and binary attachments, without having to worry about how these are represented when serialized. In practice, however, it is often necessary to be aware of at least some of the rules governing MIME messages and their structure, specifically the names and nature of the MIME «content types» and how they identify multipart documents. For the most part this knowledge should only be required for more complex applications, and even then it should only be the high level structure in question, and not the details of how those structures are represented. Since MIME content types are used widely in modern internet software (not just email), this will be a familiar concept to many programmers.

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

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

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

The foregoing represent the modern (Unicode friendly) API of the email package. The remaining sections, starting with the Message class, cover the legacy compat32 API that deals much more directly with the details of how email messages are represented. The compat32 API does not hide the details of the RFCs from the application, but for applications that need to operate at that level, they can be useful tools. This documentation is also relevant for applications that are still using the compat32 API for backward compatibility reasons.

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

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

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

Дивись також

Модуль smtplib

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

Модуль poplib

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

Модуль imaplib

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

Модуль mailbox

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