"email" --- 電子メールと MIME 処理のためのパッケージ
****************************************************

**ソースコード:** Lib/email/__init__.py

======================================================================

"email" パッケージは電子メールメッセージを管理するライブラリです。
SMTP (**RFC 2821**)、NNTP などのサーバーへ電子メールを送信するためのも
のでは *ありません*。 送信は "smtplib" などのモジュールが担当します。
"email" パッケージは、**RFC 5322** と **RFC 6532** に加え、**RFC
2045**、**RFC 2046**、**RFC 2047**、**RFC 2183**、**RFC 2231** などの
MIME 関連 RFC をサポートし、できる限り 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 設定で直列化できます。

email パッケージは、関連する各種 RFC の詳細をできるだけアプリケーショ
ンから隠します。 概念的には、アプリケーションは直列化時の表現を気にせ
ず、電子メールメッセージを Unicode テキストとバイナリ添付ファイルのツ
リー構造として扱えるはずです。 しかし実際には、MIME メッセージとその構
造を定める規則の少なくとも一部を知っておく必要がよくあります。 特に、
MIME の「コンテントタイプ」の名前や性質と、それによってマルチパート文
書を識別する方法です。 この知識が必要になるのは主に複雑なアプリケーシ
ョンであり、その場合でも必要なのは通常、構造の大枠についての知識であっ
て、構造の表現方法の詳細ではありません。 MIME コンテントタイプは、現在
のインターネットソフトウェアで電子メール以外にも広く使われているため、
多くのプログラマーにはなじみのある概念でしょう。

以下の節では "email" パッケージの機能を説明します。 まず、アプリケーシ
ョンが主に使うインターフェースである "message" オブジェクトモデルを説
明し、続いて "parser" と "generator" を取り上げます。 その後、"policy"
による制御を説明し、ライブラリの主要な構成要素の説明を終えます。

続く 3 つの節では、パッケージが送出する可能性のある例外と、"parser" が
検出する可能性のある欠陥 (RFC に準拠していない点) を説明します。 その
後、ヘッダーとペイロードをそれぞれより細かく操作するための
"headerregistry" と "contentmanager" を取り上げます。 どちらにも複雑な
メッセージの処理や作成に役立つ機能がありますが、高度なアプリケーション
向けの拡張用 API についても説明します。

続いて、それまでの節で説明した API の基本部分を使う例を示します。

ここまでが、email パッケージの現代的な、Unicode を扱いやすい API です
。 "Message" クラスから始まる残りの節では、電子メールメッセージの表現
方法の詳細をより直接的に扱う、従来の "compat32" API を説明します。
"compat32" API は RFC の詳細をアプリケーションから隠し *ません* が、そ
の水準で操作する必要があるアプリケーションには役立ちます。 この説明は
、後方互換性のために引き続き "compat32" API を使用しているアプリケーシ
ョンにも関係します。

バージョン 3.6 で変更: 新しい "EmailMessage"/"EmailPolicy" API の利用
を促すため、ドキュメントを再構成し、書き直しました。

"email" パッケージのドキュメントの目次:

* "email.message": 電子メールメッセージの表現

* "email.parser": 電子メールメッセージの解析

  * FeedParser API

  * Parser API

  * 追記事項

* "email.generator": MIME 文書の生成

* "email.policy": ポリシーオブジェクト

* "email.errors": 例外クラスと障害クラス

* "email.headerregistry": カスタムヘッダーオブジェクト

* "email.contentmanager": MIME コンテンツの管理

  * コンテンツマネージャーのインスタンス

* "email": 使用例

レガシーAPI:

* "email.message.Message": "compat32" API を使用した電子メールメッセー
  ジの表現

* "email.mime": 電子メールと MIME オブジェクトを一から作成する

* "email.header": 国際化されたヘッダー

* "email.charset": 文字集合の表現

* "email.encoders": エンコーダー

* "email.utils": 各種ユーティリティ

* "email.iterators": イテレータ

参考:

  "smtplib" モジュール
     SMTP（簡易メール転送プロトコル）クライアント

  "poplib" モジュール
     POP (Post Office Protocol) クライアント

  モジュール "imaplib"
     IMAP (Internet Message Access Protocol) クライアント

  "mailbox" モジュール
     さまざまな標準形式でディスク上のメッセージの集まりを作成、読み込
     み、管理するためのツール。
