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

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

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

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

クラス MIMEBase( _maintype, _subtype, **_params)
Module: email.mime.base

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

_maintypeContent-Type: の主形式 (maintype) であり (textimage など)、_subtypeContent-Type: の副形式 (subtype) です (plaingif など)。 _params は各パラメータのキーと値を格納した辞書であり、 これは直接 Message.add_header() に渡されます。

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

クラス MIMENonMultipart( )
Module: email.mime.nonmultipart

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

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

クラス MIMEMultipart( [subtype[, boundary[, _subparts[, _params]]]])
Module: 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 で 新たに追加 された仕様です。

クラス MIMEApplication( _data[, _subtype[, _encoder[, **_params]]])
Module: 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 で 新たに追加 された仕様です。

クラス MIMEAudio( _audiodata[, _subtype[, _encoder[, **_params]]])
Module: email.mime.audio

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 を参照してください。

_paramsMIMEBase コンストラクタに直接渡されます。

クラス MIMEImage( _imagedata[, _subtype[, _encoder[, **_params]]])
Module: email.mime.image

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 を参照してください。

_paramsMIMEBase コンストラクタに直接渡されます。

クラス MIMEMessage( _msg[, _subtype])
Module: email.mime.message

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

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

クラス MIMEText( _text[, _subtype[, _charset]])
Module: email.mime.text

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

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

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。