# `email.charset`: Representing character sets

ソースコード: Lib/email/charset.py

このモジュールは、レガシーな (`Compat32`) email API の一部分です。 新しい API では別名の表のみ使われています。

この節の以降のテキストはモジュールの元々のドキュメントです。

このモジュールは文字集合の表現および電子メールメッセージの文字集合の変換を行う `Charset` クラスに加え、文字集合のレジストリとそれを操作する簡易メソッドを提供しています。 `Charset` インスタンスは `email` パッケージ中にある他のいくつかのモジュールで使用されます。

このクラスは `email.charset` モジュールからインポートしてください。

class email.charset.Charset(input_charset=DEFAULT_CHARSET)

  文字集合を電子メールのプロパティに写像します。

  このクラスは、ある特定の文字集合に対し電子メールに課される条件についての情報を提供します。 また、適用可能なコーデックスが利用出来れば、文字集合間の変換を行う簡易ルーチンを提供します。 文字集合について、この関数は電子メールメッセージ内での RFC に準拠した文字集合の使い方に関する情報を提供するのに最善を尽くします。

  文字集合によっては、電子メールのヘッダや本体で使う場合に quoted-printable や base64 形式でエンコードされなければなりません。 また、文字集合によっては完全に変換する必要があり、電子メールの中では使用できません。

  以下ではオプション引数 input_charset について説明します。この値は常に小文字に強制的に変換されます。そして文字集合の別名が正規化されたあと、この値は文字集合のレジストリ内を検索し、ヘッダのエンコーディングとメッセージ本体のエンコーディング、および出力時の変換に使われるコーデックを見付けるのに使われます。たとえば input_charset が `iso-8859-1` の場合、ヘッダおよびメッセージ本体は quoted-printable でエンコードされ、出力時の変換用コーデックは必要ありません。もし input_charset が `euc-jp` ならば、ヘッダは base64 でエンコードされ、メッセージ本体はエンコードされませんが、出力されるテキストは `euc-jp` 文字集合から `iso-2022-jp` 文字集合に変換されます。

  `Charset` インスタンスは以下のようなデータ属性をもっています:

  input_charset

    最初に指定される文字集合です。一般的な別名は、正式な 電子メール用の名前に変換されます (たとえば、`latin_1` は `iso-8859-1` に変換されます)。デフォルトは 7-bit の `us-ascii` です。

  header_encoding

    If the character set must be encoded before it can be used in an email header, this attribute will be set to `Charset.QP` (for quoted-printable), `Charset.BASE64` (for base64 encoding), or `Charset.SHORTEST` for the shortest of QP or BASE64 encoding. Otherwise, it will be `None`.

  body_encoding

    Same as header_encoding, but describes the encoding for the mail message's body, which indeed may be different than the header encoding. `Charset.SHORTEST` is not allowed for body_encoding.

  output_charset

    文字集合によっては、電子メールのヘッダあるいはメッセージ本体に使う前に変換しなければなりません。もし input_charset がそれらの文字集合のどれかをさしていたら、この output_charset 属性はそれが出力時に変換される文字集合の名前を表しています。それ以外の場合、この値は `None` になります。

  input_codec

    input_charset を Unicode に変換するための Python 用コーデック名です。変換用のコーデックが必要ないときは、この値は `None` になります。

  output_codec

    Unicode を output_charset に変換するための Python 用コーデック名です。変換用のコーデックが必要ないときは、この値は `None` になります。この属性は input_codec と同じ値を持つことになるでしょう。

  `Charset` インスタンスは、以下のメソッドも持っています:

  get_body_encoding()

    メッセージ本体のエンコードに使われる content-transfer-encoding の値を返します。

    この値は使用しているエンコーディングの文字列 `quoted-printable` または `base64` か、あるいは関数のいずれかです。後者の場合、これはエンコードされる Message オブジェクトを単一の引数として取るような関数である必要があります。この関数は変換後 Content-Transfer-Encoding ヘッダ自体を、なんであれ適切な値に設定する必要があります。

    このメソッドは body_encoding が `QP` の場合 `quoted-printable` を返し、body_encoding が `BASE64` の場合 `base64` を返します。それ以外の場合は文字列 `7bit` を返します。

  get_output_charset()

    出力用の文字集合を返します。

    これは output_charset 属性が `None` でなければその値になります。それ以外の場合、この値は input_charset と同じです。

  header_encode(string)

    文字列 string をヘッダ用にエンコードします。

    エンコーディングの形式 (base64 または quoted-printable) は、header_encoding 属性に基づきます。

  header_encode_lines(string, maxlengths)

    string を最初にバイト列に変換し、ヘッダ用にエンコードします。

    これは `header_encode()` と似ていますが、与えられた引数 maxlengths に従って、行の最大長に合うように文字列が調整されるところが異なります。 maxlengths はイテレータでなければなりません: このイテレータが返す要素は次の行の最大長を表します。

  body_encode(string)

    文字列 string をメッセージ本体用にエンコードします。

    エンコーディングの形式 (base64 または quoted-printable) は、body_encoding 属性に基づきます。

  `Charset` クラスには、標準的な演算と組み込み関数をサポートするいくつかのメソッドがあります。

  __str__()

    input_charset を小文字に変換された文字列型として返します。 `__repr__()` は、 `__str__()` の別名となっています。

  __eq__(other)

    このメソッドは、2つの `Charset` インスタンスが同じかどうかをチェックするのに使います。

  __ne__(other)

    このメソッドは、2つの `Charset` インスタンスが異なるかどうかをチェックするのに使います。

また、 `email.charset` モジュールには、グローバルな文字集合、文字集合の別名およびコーデック用のレジストリに新しいエントリを追加する以下の関数も含まれています:

email.charset.add_charset(charset, header_enc=None, body_enc=None, output_charset=None)

  文字の属性をグローバルなレジストリに追加します。

  charset は入力用の文字集合で、その文字集合の正式名称を指定する必要があります。

  Optional header_enc and body_enc is either `Charset.QP` for quoted-printable, `Charset.BASE64` for base64 encoding, `Charset.SHORTEST` for the shortest of quoted-printable or base64 encoding, or `None` for no encoding. `SHORTEST` is only valid for header_enc. The default is `None` for no encoding.

  オプション引数 output_charset には出力用の文字集合が入ります。 `Charset.convert()` が呼ばれたときの変換はまず入力用の文字集合を Unicode に変換し、それから出力用の文字集合に変換されます。デフォルトでは、出力は入力と同じ文字集合になっています。

  input_charset および output_charset はこのモジュール中の文字集合-コーデック対応表にある Unicode コーデックエントリである必要があります。モジュールがまだ対応していないコーデックを追加するには、 `add_codec()` を使ってください。より詳しい情報については `codecs` モジュールの文書を参照してください。

  グローバルな文字集合用のレジストリは、モジュールのグローバル辞書 `CHARSETS` 内に保持されています。

email.charset.add_alias(alias, canonical)

  文字集合の別名を追加します。alias はその別名で、たとえば `latin-1` のように指定します。canonical はその文字集合の正式名称で、たとえば `iso-8859-1` のように指定します。

  文字集合のグローバルな別名用レジストリは、モジュールのグローバル辞書 `ALIASES` 内に保持されています。

email.charset.add_codec(charset, codecname)

  与えられた文字集合の文字と Unicode との変換を行うコーデックを追加します。

  charset は文字集合の正式な名前です。 codecname は、 `str` の `encode()` メソッドの第 2 引数で使える Python コーデックの名前です。