"email.mime": 電子メールと MIME オブジェクトを一から作成する
************************************************************

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

======================================================================

このモジュールは従来の ("Compat32") email API の一部です。 新しい API
では機能の一部が "contentmanager" に置き換えられていますが、用途によっ
ては新しいコードでもこれらのクラスが役立ちます。

ふつう、メッセージオブジェクト構造はファイルまたは何がしかのテキストを
パーザに通すことで得られます。パーザは与えられたテキストを解析し、基底
となる 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" に渡されます。

   *policy* を指定すると "Message" に渡されます (デフォルトは
   "compat32" ポリシーです)。

   "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" メソッドを使ってそのメ
   ッセージに追加できるようになっています。

   オプション引数 *policy* のデフォルトは "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"

   "MIMEApplication" クラスは "MIMENonMultipart" のサブクラスで、主形
   式が *application* の MIME メッセージオブジェクトを表します。
   *_data* は未加工のアプリケーションデータのバイト列です。 オプション
   引数 *_subtype* は MIME の副形式を指定し、デフォルトは *octet-
   stream* です。

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

   オプション引数 *policy* のデフォルトは "compat32" です。

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

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

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

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

   "MIMEAudio" クラスは "MIMENonMultipart" のサブクラスで、主形式が
   *audio* の MIME メッセージオブジェクトを作成します。 *_audiodata*
   は未加工の音声データのバイト列です。 このデータを au、wav、aiff、
   aifc としてデコードできる場合、副形式は自動的に *Content-Type* ヘッ
   ダに含められます。 それ以外の場合は *_subtype* 引数で音声の副形式を
   明示的に指定できます。 副形式を推測できず、*_subtype* も指定されて
   いない場合は "TypeError" が送出されます。

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

   オプション引数 *policy* のデフォルトは "compat32" です。

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

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

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

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

   "MIMEImage" クラスは "MIMENonMultipart" のサブクラスで、主形式が
   *image* の MIME メッセージオブジェクトを作成します。 *_imagedata*
   は未加工の画像データのバイト列です。 このデータの形式を検出できる場
   合 (jpeg、png、gif、tiff、rgb、pbm、pgm、ppm、rast、xbm、bmp、webp
   、exr の検出を試みます)、副形式は自動的に *Content-Type* ヘッダに含
   められます。 それ以外の場合は *_subtype* 引数で画像の副形式を明示的
   に指定できます。 副形式を推測できず、*_subtype* も指定されていない
   場合は "TypeError" が送出されます。

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

   オプション引数 *policy* のデフォルトは "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* になっています。

   オプション引数 *policy* のデフォルトは "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-Encoding* ヘッダの両方を持ちます。 これは後続の
   "set_payload" 呼び出しが、 "set_payload" コマンドに charset を渡し
   たとしてもエンコードされたペイロードにはならないことを意味します。
   "Content-Transfer-Encoding" ヘッダを削除することでこの振る舞いを「
   リセット」出来ます。 これにより "set_payload" 呼び出しが新たなペイ
   ロードを自動的にエンコード (そして新たな *Content-Transfer-
   Encoding* ヘッダを追加) します。

   オプション引数 *policy* のデフォルトは "compat32" です。

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

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