email --- An email and MIME handling package

Kode sumber: 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.

Struktur keseluruhan paket email dapat dibagi menjadi tiga komponen utama, ditambah komponen keempat yang mengontrol perilaku komponen lainnya.

Komponen utama dari paket tersebut adalah "model objek" yang mewakili pesan email. Aplikasi berinteraksi dengan paket terutama melalui antarmuka model objek yang ditentukan dalam sub-modul message. Aplikasi dapat menggunakan API ini untuk mengajukan pertanyaan tentang email yang sudah ada, membuat email baru, atau untuk menambah atau menghapus subkomponen email yang menggunakan antarmuka model objek yang sama. Artinya, mengikuti sifat pesan email dan subkomponen MIME-nya, model objek email adalah struktur pohon objek yang semuanya menyediakan API EmailMessage.

Dua komponen utama lainnya dari paket tersebut adalah parser dan generator. Parser mengambil versi serial dari pesan email (aliran byte) dan mengubahnya menjadi pohon objek EmailMessage. Generator mengambil EmailMessage dan mengubahnya kembali menjadi aliran byte serial. (Pengurai dan generator juga menangani aliran karakter teks, tetapi penggunaan ini tidak disarankan karena terlalu mudah untuk berakhir dengan pesan yang tidak valid dalam satu atau lain cara.)

Komponen kontrolnya adalah modul policy. Setiap EmailMessage, setiap generator, dan setiap parser memiliki objek terkait policy yang mengontrol perilakunya. Biasanya aplikasi hanya perlu menetapkan kebijakan ketika EmailMessage dibuat, baik dengan langsung membuat instance EmailMessage untuk membuat email baru, atau dengan mengurai aliran input menggunakan parser. Namun kebijakan tersebut dapat diubah jika pesan diserialkan menggunakan generator. Hal ini memungkinkan, misalnya, pesan email umum diurai dari disk, tetapi untuk membuat serialnya menggunakan pengaturan SMTP standar saat mengirimnya ke server email.

Пакет електронної пошти робить усе можливе, щоб приховати деталі різних керівних 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 з причин зворотної сумісності.

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

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

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

Lihat juga

Модуль smtplib

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

Модуль poplib

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

Модуль imaplib

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

Модуль mailbox

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