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

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

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

import email.MIMEImage.MIMEImage

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

from email.MIMEText import MIMEText

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

class 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 に設定される) を追加します。

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

class 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 以降で新規追加された仕様です。

class 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 コンストラクタに直接渡されます。

class 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 コンストラクタに直接渡されます。

class MIMEMessage( _msg[, _subtype]): MIMEMessage クラスは MIMENonMultipart のサブクラスで、主形式 (maintype) が message の MIME オブジェクトを作成するのに使われます。ペイロードとして使われるメッセージは _msg になります。これは Message クラス (あるいはそのサブクラス) のインスタンスでなければいけません。そうでない場合、この関数は TypeError を発生します。
オプション引数 _subtype はそのメッセージの副形式 (subtype) を設定します。デフォルトではこれは rfc822 になっています。

class MIMEText( _text[, _subtype[, _charset[, _encoder]]])

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

リリース 2.2.2 以降で撤廃された仕様です。 The _encoding 引数はもはや時代遅れとなっており、推奨されません。現在ではエンコードは _charset 引数にもとづき暗黙のうちに行われます。

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