email.mime: Creating email and MIME objects from scratch

ソースコード: Lib/email/mime/

This module is part of the legacy (Compat32) email API. Its functionality is partially replaced by the contentmanager in the new API, but in certain applications these classes may still be useful, even in non-legacy code.

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

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

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

class email.mime.base.MIMEBase(_maintype, _subtype, *, policy=compat32, **_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 に渡されます。

If policy is specified, (defaults to the compat32 policy) it will be passed to Message.

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

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

class email.mime.nonmultipart.MIMENonMultipart

モジュール: email.mime.nonmultipart

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

class email.mime.multipart.MIMEMultipart(_subtype='mixed', boundary=None, _subparts=None, *, policy=compat32, **_params)

モジュール: email.mime.multipart

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

オプション引数 boundary は multipart の境界文字列です。これが None の場合 (デフォルト)、境界は必要に応じて計算されます（例えばメッセージがシリアライズされるときなど）。

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

Optional policy argument defaults to compat32.

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

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

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.application

A subclass of MIMENonMultipart, the MIMEApplication class is used to represent MIME message objects of major type application. _data contains the bytes for the raw application data. Optional _subtype specifies the MIME subtype and defaults to octet-stream.

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

Optional policy argument defaults to compat32.

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

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

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.audio

A subclass of MIMENonMultipart, the MIMEAudio class is used to create MIME message objects of major type audio. _audiodata contains the bytes for the raw audio data. If this data can be decoded as au, wav, aiff, or aifc, then the subtype will be automatically included in the Content-Type header. Otherwise you can explicitly specify the audio subtype via the _subtype argument. If the minor type could not be guessed and _subtype was not given, then TypeError is raised.

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

Optional policy argument defaults to compat32.

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

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

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_params)

モジュール: email.mime.image

A subclass of MIMENonMultipart, the MIMEImage class is used to create MIME message objects of major type image. _imagedata contains the bytes for the raw image data. If this data type can be detected (jpeg, png, gif, tiff, rgb, pbm, pgm, ppm, rast, xbm, bmp, webp, and exr attempted), then the subtype will be automatically included in the Content-Type header. Otherwise you can explicitly specify the image subtype via the _subtype argument. If the minor type could not be guessed and _subtype was not given, then TypeError is raised.

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

Optional policy argument defaults to compat32.

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

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

class email.mime.message.MIMEMessage(_msg, _subtype='rfc822', *, policy=compat32)

モジュール: email.mime.message

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

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

Optional policy argument defaults to compat32.

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

class email.mime.text.MIMEText(_text, _subtype='plain', _charset=None, *, policy=compat32)

モジュール: email.mime.text

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

_charset 引数に明示的に None をセットしない限りは、作成される MIMEText オブジェクトは charset の付いた Content-Type ヘッダと Content-Transfer-Endcoding ヘッダの両方を持ちます。これは後続の set_payload 呼び出しが、 set_payload コマンドに charset が渡したとしてもエンコードされたペイロードにはならないことを意味します。 Content-Transfer-Encoding ヘッダを削除することでこの振る舞いを「リセット」出来ます。これにより set_payload 呼び出しが新たなペイロードを自動的にエンコード (そして新たな Content-Transfer-Encoding ヘッダを追加) します。

Optional policy argument defaults to compat32.

バージョン 3.5 で変更: _charset は Charset インスタンスも受け取ります。

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