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

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

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

メッセージオブジェクトの構造を作成する方法は 2 つあります。
"EmailMessage" オブジェクトを作成し、辞書インターフェイスでヘッダを追
加し、"set_content()" や関連メソッドでペイロードを追加して一から組み立
てる方法と、シリアライズされた電子メールメッセージを解析する方法です。

"email" パッケージには、MIME 文書を含むほとんどの電子メール文書の構造
を解釈できる標準のパーザがあります。 パーザにバイト列、文字列、または
ファイルオブジェクトを渡すと、オブジェクト構造のルートに当たる
"EmailMessage" インスタンスが返されます。 MIME 形式でない単純なメッセ
ージでは、通常、このルートオブジェクトのペイロードはメッセージのテキス
トを含む文字列になります。 MIME メッセージではルートオブジェクトの
"is_multipart()" メソッドが "True" を返し、"get_body()"、
"iter_parts()"、"walk()" などのペイロード操作用メソッドで各部分にアク
セスできます。

利用できるパーザインターフェイスは、"Parser" API と逐次解析を行う
"FeedParser" API の 2 つです。 "Parser" API は、メッセージ全体のテキス
トがメモリ内にある場合や、メッセージ全体がファイルシステム上のファイル
に格納されている場合に適しています。 追加の入力を待ってブロックする可
能性があるストリームからメッセージを読む場合 (例えばソケットから電子メ
ールメッセージを読む場合) は、"FeedParser" の方が適しています。
"FeedParser" はメッセージを少しずつ取り込んで解析でき、パーザを閉じた
ときに初めてルートオブジェクトを返します。

パーザは限られた範囲で拡張でき、もちろん独自のパーザを一から実装するこ
ともできます。 "email" パッケージに付属するパーザと "EmailMessage" ク
ラスを結び付けるロジックはすべて "Policy" クラスにまとめられています。
そのため独自のパーザは、適切な "Policy" メソッドを独自に実装することで
、必要な方法でメッセージオブジェクトのツリーを作成できます。


FeedParser API
==============

The "BytesFeedParser", imported from the "email.feedparser" module,
provides an API that is conducive to incremental parsing of email
messages, such as would be necessary when reading the text of an email
message from a source that can block (such as a socket).  The
"BytesFeedParser" can of course be used to parse an email message
fully contained in a *bytes-like object*, string, or file, but the
"BytesParser" API may be more convenient for such use cases.  The
semantics and results of the two parser APIs are identical.

"BytesFeedParser" API は簡単です。 まずインスタンスをつくり、それに
bytes を (渡す bytes がなくなるまで) 流しこみます。 その後パーザを
close すると根っこ (root) のメッセージオブジェクトが返されます。 標準
に従ったメッセージを解析する場合、 "BytesFeedParser" は非常に正確であ
り、標準に従っていないメッセージでもちゃんと動きます。 そのさい、これ
はメッセージがどのように壊れていると認識されたかについての情報を残しま
す。 これはメッセージオブジェクトの "defects" 属性にリストとして現れ、
メッセージ中に発見された問題が記録されます。 パーザが検出できる障害
(defect) については "email.errors" モジュールを参照してください。

以下は "BytesFeedParser" の API です:

class email.parser.BytesFeedParser(_factory=None, *, policy=policy.compat32)

   "BytesFeedParser" インスタンスを作成します。 オプション引数
   *_factory* は引数を取らない呼び出し可能オブジェクトです。 指定しな
   ければ *policy* の "message_factory" を使います。 新しいメッセージ
   オブジェクトが必要になるたびに *_factory* を呼び出します。

   *policy* を指定した場合、そのルールに従ってメッセージの表現を更新し
   ます。 指定しない場合は "compat32" ポリシーを使います。 このポリシ
   ーは Python 3.2 の email パッケージとの後方互換性を維持し、デフォル
   トのファクトリとして "Message" を提供します。 その他のポリシーはす
   べて、デフォルトの *_factory* として "EmailMessage" を提供します。
   *policy* が制御するその他の内容は "policy" のドキュメントを参照して
   ください。

   Note: **The policy keyword should always be specified**. The
   default will change to "email.policy.default" in a future version
   of Python.

   Added in version 3.2.

   バージョン 3.3 で変更: キーワード引数 *policy* が追加されました。

   バージョン 3.6 で変更: *_factory* のデフォルトがポリシーの
   "message_factory" になりました。

   feed(data)

      パーサーにデータを供給します。 *data* は 1行または複数行からなる
      *bytes-like object* を渡します。渡される行は完結していなくてもよ
      く、その場合パーサーは部分的な行を適切につなぎ合わせます。各行は
      3種類の標準的な行末文字 (復帰 CR、改行 LF、または CR+LF) どれか
      の組み合わせでよく、これらが混在してもかまいません。

   close()

      それまでに渡されたすべてのデータの解析を完了し、ルートのメッセー
      ジオブジェクトを返します。 このメソッドを呼び出した後で "feed()"
      を呼び出した場合の動作は未定義です。

class email.parser.FeedParser(_factory=None, *, policy=policy.compat32)

   "BytesFeedParser" と同様に動作しますが、"feed()" メソッドへの入力は
   文字列でなければなりません。 このようなメッセージが有効となるのは、
   ASCII テキストのみを含む場合、または "utf8" が "True" でバイナリの
   添付ファイルを含まない場合に限られるため、用途は限定されます。

   バージョン 3.3 で変更: キーワード引数 *policy* が追加されました。


Parser API
==========

"email.parser" モジュールからインポートする "BytesParser" クラスは、メ
ッセージ全体が *bytes-like object* やファイルに格納されている場合に解
析するための API を提供します。 "email.parser" モジュールには、文字列
を解析する "Parser" と、メッセージのヘッダだけが必要な場合に使えるヘッ
ダ専用パーザ "BytesHeaderParser" および "HeaderParser" もあります。
"BytesHeaderParser" と "HeaderParser" はメッセージ本体を解析せず、その
ままペイロードに設定するため、このような場合には大幅に高速になることが
あります。

class email.parser.BytesParser(_class=None, *, policy=policy.compat32)

   "BytesParser" インスタンスを作成します。 *_class* 引数と *policy*
   引数の意味と動作は、"BytesFeedParser" の *_factory* 引数と *policy*
   引数と同じです。

   Note: **The policy keyword should always be specified**. The
   default will change to "email.policy.default" in a future version
   of Python.

   バージョン 3.3 で変更: 2.4 で非推奨になった *strict* 引数の削除。キ
   ーワード引数 *policy* の追加。

   バージョン 3.6 で変更: *_class* のデフォルトがポリシーの
   "message_factory" になりました。

   parse(fp, headersonly=False)

      バイナリのファイル類似オブジェクト *fp* からすべてのデータを読み
      込み、得られたバイト列を解析してメッセージオブジェクトを返します
      。 *fp* は "readline()" と "read()" の両方のメソッドをサポートし
      なければなりません。

      *fp* 内のバイト列は、**RFC 5322** (または "utf8" が "True" の場
      合は **RFC 6532**) 形式のヘッダとヘッダの継続行からなるブロック
      で始まらなければなりません。 その前にエンベロープヘッダがあって
      もかまいません。 ヘッダブロックはデータの終端または空行で終わり
      ます。 ヘッダブロックの後にはメッセージ本体が続きます (本体には
      、*Content-Transfer-Encoding* が "8bit" の部分を含め、MIME エン
      コードされた部分が含まれていることがあります)。

      オプション引数 *headersonly* はヘッダを読み終えた後にパースを止
      めるかを指定するフラグです。デフォルトは "False" で、ファイルの
      内容全体をパースします。

   parsebytes(bytes, headersonly=False)

      "parse()" メソッドと似ていますが、ファイル類似オブジェクトではな
      く *bytes-like object* を受け取ります。 *bytes-like object* に対
      してこのメソッドを呼び出すことは、*bytes* を "BytesIO" インスタ
      ンスに包んで "parse()" を呼び出すことと同じです。

      オプション引数 *headersonly* は "parse()" メソッドと同じです。

   Added in version 3.2.

class email.parser.BytesHeaderParser(_class=None, *, policy=policy.compat32)

   *headersonly* のデフォルトが "True" である点を除き、"BytesParser"
   とまったく同じです。

   Added in version 3.3.

class email.parser.Parser(_class=None, *, policy=policy.compat32)

   "BytesParser" に対応するクラスですが、文字列の入力を扱います。

   バージョン 3.3 で変更: *strict* 引数の削除。キーワード引数 *policy*
   の追加。

   バージョン 3.6 で変更: *_class* のデフォルトがポリシーの
   "message_factory" になりました。

   parse(fp, headersonly=False)

      ファイルなどテキストモードのストリーム形式 (file-like) のオブジ
      ェクト *fp* からすべてのデータを読み込み、得られたテキストを解析
      して基底 (root) メッセージオブジェクト構造を返します。 *fp* はス
      トリーム形式のオブジェクトで "readline()" および "read()" 両方の
      メソッドをサポートしている必要があります。

      テキストモードが必要な点を除き、このメソッドは
      "BytesParser.parse()" と同様に動作します。

   parsestr(text, headersonly=False)

      "parse()" メソッドに似ていますが、ファイルなどのストリーム形式の
      かわりに文字列を引数としてとるところが違います。文字列に対してこ
      のメソッドを呼ぶことは、 *text* を "StringIO" インスタンスとして
      作成して "parse()" を適用するのと同じです。

      オプション引数 *headersonly* は "parse()" メソッドと同じです。

class email.parser.HeaderParser(_class=None, *, policy=policy.compat32)

   *headersonly* のデフォルトが "True" である点を除き、"Parser" とまっ
   たく同じです。

ファイルや文字列からメッセージオブジェクト構造を作成するのはかなりよく
おこなわれる作業なので、便宜上次のような 4つの関数が提供されています。
これらは "email" パッケージのトップレベルの名前空間で使用できます。

email.message_from_bytes(s, _class=None, *, policy=policy.compat32)

   *bytes-like オブジェクト* からメッセージオブジェクト構造を作成して
   返します。これは "BytesParser().parsebytes(s)" と同じです。オプショ
   ン引数 *_class* および *policy* は "BytesParser" クラスのコンストラ
   クタと同様に解釈されます。

   Added in version 3.2.

   バージョン 3.3 で変更: *strict* 引数の削除。キーワード引数 *policy*
   の追加。

email.message_from_binary_file(fp, _class=None, *, policy=policy.compat32)

   オープンされたバイナリ *file object* からメッセージオブジェクト構造
   を作成して返します。これは "BytesParser().parse(fp)" と同じです。
   *_class* および *policy* は "BytesParser" クラスのコンストラクタと
   同様に解釈されます。

   Added in version 3.2.

   バージョン 3.3 で変更: *strict* 引数の削除。キーワード引数 *policy*
   の追加。

email.message_from_string(s, _class=None, *, policy=policy.compat32)

   文字列からメッセージオブジェクト構造を作成して返します。これは
   "Parser().parsestr(s)" と同じです。 *_class* および *policy* は
   "Parser" クラスのコンストラクタと同様に解釈されます。

   バージョン 3.3 で変更: *strict* 引数の削除。キーワード引数 *policy*
   の追加。

email.message_from_file(fp, _class=None, *, policy=policy.compat32)

   オープンされた *file object* からメッセージオブジェクト構造を作成し
   て返します。これは "Parser().parse(fp)" と同じです。 *_class* およ
   び *policy* は "Parser" クラスのコンストラクタと同様に解釈されます
   。

   バージョン 3.3 で変更: *strict* 引数の削除。キーワード引数 *policy*
   の追加。

   バージョン 3.6 で変更: *_class* のデフォルトがポリシーの
   "message_factory" になりました。

対話的な Python プロンプトで "message_from_bytes()" を使用するとすれば
、このようになります:

   >>> import email
   >>> msg = email.message_from_bytes(myBytes)


追記事項
========

以下はテキスト解析の際に適用されるいくつかの規約です:

* Most non-*multipart* type messages are parsed as a single message
  object with a string payload.  These objects will return "False" for
  "is_multipart()", and "iter_parts()" will yield an empty list.

* All *multipart* type messages will be parsed as a container message
  object with a list of sub-message objects for their payload.  The
  outer container message will return "True" for "is_multipart()", and
  "iter_parts()" will yield a list of subparts.

* Most messages with a content type of *message/** (such as *message
  /delivery-status* and *message/rfc822*) will also be parsed as
  container object containing a list payload of length 1.  Their
  "is_multipart()" method will return "True". The single element
  yielded by "iter_parts()" will be a sub-message object.

* いくつかの標準的でないメッセージは、 *multipart* の使い方に統一がと
  れていない場合があります。このようなメッセージは *Content-Type* ヘッ
  ダに *multipart* を指定しているものの、その "is_multipart()" メソッ
  ドは "False" を返すことがあります。もしこのようなメッセージが
  "FeedParser" によって解析されると、その *defects* 属性のリスト中には
  "MultipartInvariantViolationDefect" クラスのインスタンスが現れます。
  詳しい情報については "email.errors" を参照してください。
