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

**ソースコード:** 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 で変更: Added *policy* keyword-only parameter.

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 で変更: Added *policy* keyword-only parameter.

class email.mime.application.MIMEApplication(_data, _subtype='octet-stream', _encoder=email.encoders.encode_base64, *, policy=compat32, **_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" モジュールを見てください。

   Optional *policy* argument defaults to "compat32".

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

   バージョン 3.6 で変更: Added *policy* keyword-only parameter.

class email.mime.audio.MIMEAudio(_audiodata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_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" モジュールを見てください。

   Optional *policy* argument defaults to "compat32".

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

   バージョン 3.6 で変更: Added *policy* keyword-only parameter.

class email.mime.image.MIMEImage(_imagedata, _subtype=None, _encoder=email.encoders.encode_base64, *, policy=compat32, **_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" モジュールを見てください。

   Optional *policy* argument defaults to "compat32".

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

   バージョン 3.6 で変更: Added *policy* keyword-only parameter.

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 で変更: Added *policy* keyword-only parameter.

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" インスタンスの両方を受
   け付けます。

   Unless the *_charset* argument 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).

   Optional *policy* argument defaults to "compat32".

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

   バージョン 3.6 で変更: Added *policy* keyword-only parameter.
