# `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 で変更: キーワード専用引数 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`

  `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 で変更: キーワード専用引数 policy が追加されました。

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 で変更: キーワード専用引数 policy が追加されました。

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 で変更: キーワード専用引数 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 が追加されました。