email --- 電子メールと MIME 処理のためのパッケージ¶
ソースコード: Lib/email/__init__.py
email パッケージは、電子メールメッセージを管理するライブラリです。 特に、SMTP（RFC 2821)、NNTP、またはその他のサーバーに電子メールメッセージを送信するようには設計されていません。これらは、smtplib などのモジュールの関数群です。 email パッケージは、可能な限りRFCに準拠するよう試みています。 RFC 5322 や RFC 6532 のほか、RFC 2045、RFC 2046、RFC 2047、RFC 2183、RFC 2231 などのMIME関連のRFCに対応しています。
email パッケージの全体構造は、主要な 3 つの構成要素と、それらの動作を制御する 4 つ目の構成要素に分けられます。
パッケージの中心となる構成要素は、電子メールメッセージを表現する「オブジェクトモデル」です。
アプリケーションは主に message サブモジュールで定義されたオブジェクトモデルのインターフェースを通じて、このパッケージを利用します。
この API で、既存の電子メールの情報を調べたり、新しい電子メールを作成したり、同じオブジェクトモデルのインターフェースを持つ構成部分を追加・削除したりできます。
つまり、電子メールメッセージとその MIME 構成部分の性質に合わせて、email のオブジェクトモデルは、すべてのオブジェクトが EmailMessage API を提供するツリー構造になっています。
他の 2 つの主要な構成要素は 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.
The following sections describe the functionality of the email package.
We start with the message object model, which is the primary
interface an application will use, and follow that with the
parser and generator components. Then we cover the
policy controls, which completes the treatment of the main
components of the library.
続く 3 つの節では、パッケージが送出する可能性のある例外と、parser が検出する可能性のある欠陥 (RFC に準拠していない点) を説明します。
その後、ヘッダーとペイロードをそれぞれより細かく操作するための 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: