## 4 電子メールおよび MIME オブジェクトをゼロから作成する

ふつう、メッセージオブジェクト構造はファイルまたは何がしかの テキストをパーザに通すことで得られます。パーザは与えられた テキストを解析し、基底となる root のメッセージオブジェクトを返します。 しかし、完全なメッセージオブジェクト構造を何もないところから作成することも また可能です。個別の `Message` を手で作成することさえできます。 実際には、すでに存在するメッセージオブジェクト構造をとってきて、 そこに新たな `Message` オブジェクトを追加したり、あるものを 別のところへ移動させたりできます。これは MIME メッセージを 切ったりおろしたりするために非常に便利なインターフェイスを提供します。

新しいメッセージオブジェクト構造は `Message` インスタンスを 作成することにより作れます。ここに添付ファイルやその他適切なものを すべて手で加えてやればよいのです。MIME メッセージの場合、 `email` パッケージはこれらを簡単におこなえるようにするために いくつかの便利なサブクラスを提供しています。これらのサブクラスは `email` パッケージ内にある、 そのクラスと同じ名前をもつモジュールから import してやります。 たとえば:

    import email.MIMEImage.MIMEImage

または以下のようにします:

    from email.MIMEText import MIMEText

以下がそのサブクラスです:

クラス `MIMEBase`( | _maintype, _subtype, **_params)

  これはすべての MIME 用サブクラスの基底となるクラスです。 とくに `MIMEBase` のインスタンスを直接作成することは (可能ではありますが) ふつうはしないでしょう。`MIMEBase` は 単により特化された MIME 用サブクラスのための便宜的な基底クラスとして提供されています。

  _maintype は Content-Type: の主形式 (maintype) であり (text や image など)、_subtype は Content-Type: の副形式 (subtype) です (plain や gif など)。 _params は各パラメータのキーと値を格納した辞書であり、 これは直接 `Message.add_header()` に渡されます。

  `MIMEBase` クラスはつねに (_maintype、 _subtype、 および _params にもとづいた) Content-Type: ヘッダと、 MIME-Version: ヘッダ (必ず `1.0` に設定される) を追加します。

クラス `MIMENonMultipart`( | )

  `MIMEBase` のサブクラスで、これは multipart 形式でない MIME メッセージのための中間的な基底クラスです。このクラスのおもな目的は、 通常 multipart 形式のメッセージに対してのみ意味をなす `attach()` メソッドの使用をふせぐことです。もし `attach()` メソッドが 呼ばれた場合、これは `MultipartConversionError` 例外を発生します。

  バージョン 2.2.2 で 新たに追加 された仕様です。

クラス `MIMEMultipart`( | [subtype[, boundary[, _subparts[, _params]]]])

  `MIMEBase` のサブクラスで、これは multipart 形式の MIME メッセージのための中間的な基底クラスです。オプション引数 _subtype は デフォルトでは mixed になっていますが、そのメッセージの副形式 (subtype) を 指定するのに使うことができます。メッセージオブジェクトには multipart/_subtype という値をもつ Content-Type: ヘッダとともに、 MIME-Version: ヘッダが追加されるでしょう。

  オプション引数 boundary は multipart の境界文字列です。 これが `None` の場合 (デフォルト)、境界は必要に応じて計算されます。

  _subparts はそのペイロードの subpart の初期値からなるシーケンスです。 このシーケンスはリストに変換できるようになっている必要があります。 新しい subpart はつねに `Message.attach()` メソッドを使って そのメッセージに追加できるようになっています。

  Content-Type: ヘッダに対する追加のパラメータは キーワード引数 _params を介して取得あるいは設定されます。 これはキーワード辞書になっています。

  バージョン 2.2.2 で 新たに追加 された仕様です。

クラス `MIMEAudio`( | _audiodata[, _subtype[, _encoder[, **_params]]])

  `MIMEAudio` クラスは `MIMENonMultipart` のサブクラスで、 主形式 (maintype) が audio の MIME オブジェクトを作成するのに使われます。 _audiodata は実際の音声データを格納した文字列です。 もしこのデータが標準の Python モジュール `sndhdr` によって 認識できるものであれば、Content-Type: ヘッダの 副形式 (subtype) は自動的に決定されます。 そうでない場合はその画像の形式 (subtype) を _subtype で 明示的に指定する必要があります。副形式が自動的に決定できず、 _subtype の指定もない場合は、`TypeError` が発生します。

  オプション引数 _encoder は呼び出し可能なオブジェクト (関数など) で、 トランスポートのさいに画像の実際のエンコードをおこないます。 このオブジェクトは `MIMEAudio` インスタンスの引数をひとつだけ取ることができます。 この関数は、与えられたペイロードをエンコードされた形式に変換するのに `get_payload()` および `set_payload()` を使う必要があります。 また、これは必要に応じて Content-Transfer-Encoding: あるいは そのメッセージに適した何らかのヘッダを追加する必要があります。 デフォルトのエンコーディングは base64 です。組み込みのエンコーダの詳細については `email.Encoders` を参照してください。

  _params は `MIMEBase` コンストラクタに直接渡されます。

クラス `MIMEImage`( | _imagedata[, _subtype[, _encoder[, **_params]]])

  `MIMEImage` クラスは `MIMENonMultipart` のサブクラスで、 主形式 (maintype) が image の MIME オブジェクトを作成するのに使われます。 _imagedata は実際の画像データを格納した文字列です。 もしこのデータが標準の Python モジュール `imghdr` によって 認識できるものであれば、Content-Type: ヘッダの 副形式 (subtype) は自動的に決定されます。 そうでない場合はその画像の形式 (subtype) を _subtype で 明示的に指定する必要があります。副形式が自動的に決定できず、 _subtype の指定もない場合は、`TypeError` が発生します。

  オプション引数 _encoder は呼び出し可能なオブジェクト (関数など) で、 トランスポートのさいに画像の実際のエンコードをおこないます。 このオブジェクトは `MIMEImage` インスタンスの引数をひとつだけ取ることができます。 この関数は、与えられたペイロードをエンコードされた形式に変換するのに `get_payload()` および `set_payload()` を使う必要があります。 また、これは必要に応じて Content-Transfer-Encoding: あるいは そのメッセージに適した何らかのヘッダを追加する必要があります。 デフォルトのエンコーディングは base64 です。組み込みのエンコーダの詳細については `email.Encoders` を参照してください。

  _params は `MIMEBase` コンストラクタに直接渡されます。

クラス `MIMEMessage`( | _msg[, _subtype])

  `MIMEMessage` クラスは `MIMENonMultipart` のサブクラスで、 主形式 (maintype) が message の MIME オブジェクトを作成するのに使われます。ペイロードとして使われるメッセージは _msg になります。これは `Message` クラス (あるいはそのサブクラス) の インスタンスでなければいけません。そうでない場合、この関数は `TypeError` を発生します。

  オプション引数 _subtype はそのメッセージの副形式 (subtype) を設定します。 デフォルトではこれは rfc822 になっています。

クラス `MIMEText`( | _text[, _subtype[, _charset]])

  `MIMEText` クラスは `MIMENonMultipart` のサブクラスで、 主形式 (maintype) が text の MIME オブジェクトを作成するのに使われます。ペイロードの文字列は _text になります。_subtype には副形式 (subtype) を指定し、 デフォルトは plain です。_charset はテキストの 文字セットで、`MIMENonMultipart` コンストラクタに引数として渡されます。 デフォルトではこの値は `us-ascii` になっています。 テキストデータに対しては文字コードの推定やエンコードはまったく行われません。

  バージョン 2.4 で 変更 された仕様: 以前、推奨されない引数であった _encoding は撤去されました。 エンコーディングは _charset 引数をもとにして暗黙のうちに決定されます。