"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* が追加されました
   。
