18.1.4. "email.mime": ゼロからのメールと MIME オブジェクトの作成
****************************************************************

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

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

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

class email.mime.base.MIMEBase(_maintype, _subtype, **_params)

   モジュール: "email.mime.base"

   これはすべての "Message" の 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" に設定される) を追加します。

class email.mime.nonmultipart.MIMENonMultipart

   モジュール: "email.mime.nonmultipart"

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

   バージョン 2.2.2 で追加.

class email.mime.multipart.MIMEMultipart([_subtype[, boundary[, _subparts[, _params]]]])

   モジュール: "email.mime.multipart"

   "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 で追加.

class email.mime.application.MIMEApplication(_data[, _subtype[, _encoder[, **_params]]])

   モジュール: "email.mime.application"

   "MIMENonMultipart" のサブクラスである "MIMEApplication" クラスは
   MIME メッセージオブジェクトのメジャータイプ *application* を表しま
   す。 *_data* は生のバイト列が入った文字列です。オプション引数
   *_subtype* は MIME のサブタイプを設定します。サブタイプのデフォルト
   は *octet-stream* です。

   オプション引数の *_encoder* は呼び出し可能なオブジェクト (関数など)
   で、データの転送に使う実際のエンコード処理を行います。この呼び出し
   可能なオブジェクトは引数を 1 つ取り、それは "MIMEApplication" のイ
   ンスタンスです。ペイロードをエンコードされた形式に変更するために
   "get_payload()" と "set_payload()" を使い、必要に応じて *Content-
   Transfer-Encoding* やその他のヘッダをメッセージオブジェクトに追加す
   るべきです。デフォルトのエンコードは base64 です。組み込みのエンコ
   ーダの一覧は "email.encoders" モジュールを見てください。

   *_params* は基底クラスのコンストラクタにそのまま渡されます。

   バージョン 2.5 で追加.

class email.mime.audio.MIMEAudio(_audiodata[, _subtype[, _encoder[, **_params]]])

   モジュール: "email.mime.audio"

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

   オプション引数の *_encoder* は呼び出し可能なオブジェクト (関数など)
   で、オーディオデータの転送に使う実際のエンコード処理を行います。こ
   の呼び出し可能なオブジェクトは引数を 1 つ取り、それは "MIMEAudio"
   のインスタンスです。ペイロードをエンコードされた形式に変更するため
   に "get_payload()" と "set_payload()" を使い、必要に応じて
   *Content-Transfer-Encoding* やその他のヘッダをメッセージオブジェク
   トに追加するべきです。デフォルトのエンコードは base64 です。組み込
   みのエンコーダの一覧は "email.encoders" モジュールを見てください。

   *_params* は基底クラスのコンストラクタにそのまま渡されます。

class email.mime.image.MIMEImage(_imagedata[, _subtype[, _encoder[, **_params]]])

   モジュール: "email.mime.image"

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

   オプション引数の *_encoder* は呼び出し可能なオブジェクト (関数など)
   で、画像データの転送に使う実際のエンコード処理を行います。この呼び
   出し可能なオブジェクトは引数を 1 つ取り、それは "MIMEImage" のイン
   スタンスです。ペイロードをエンコードされた形式に変更するために
   "get_payload()" と "set_payload()" を使い、必要に応じて *Content-
   Transfer-Encoding* やその他のヘッダをメッセージオブジェクトに追加す
   るべきです。デフォルトのエンコードは base64 です。組み込みのエンコ
   ーダの一覧は "email.encoders" モジュールを見てください。

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

class email.mime.message.MIMEMessage(_msg[, _subtype])

   モジュール: "email.mime.message"

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

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

class email.mime.text.MIMEText(_text[, _subtype[, _charset]])

   モジュール: "email.mime.text"

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

   バージョン 2.4 で変更: 以前、推奨されない引数であった *_encoding*
   は削除されました。 *_charset* 引数を基にして Content Transfer
   Encodnig が暗黙に決定されます。

   Unless the "_charset" parameter is explicitly set to "None", the
   MIMEText object created will have both a *Content-Type* header with
   a "charset" parameter, and a *Content-Transfer-Encoding* header.
   This means that a subsequent "set_payload" call will not result in
   an encoded payload, even if a charset is passed in the
   "set_payload" command.  You can "reset" this behavior by deleting
   the "Content-Transfer-Encoding" header, after which a "set_payload"
   call will automatically encode the new payload (and add a new
   *Content-Transfer-Encoding* header).
