19.1.12. "email.charset": 文字集合の表現
****************************************

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

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

This module is part of the legacy ("Compat32") email API.  In the new
API only the aliases table is used.

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

このモジュールは文字集合の表現および電子メールメッセージの文字集合の変
換を行う "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

      この文字集合が電子メールヘッダに使われる前にエンコードされなけれ
      ばならない場合、この属性は "Charset.QP" (quoted-printable エンコ
      ーディング)、"Charset.BASE64" (base64 エンコーディング)、あるい
      は最短の QP または BASE64 エンコーディングである
      "Charset.SHORTEST" に設定されます。そうでない場合、この値は
      "None" になります。

   body_encoding

      *header_encoding* と同じですが、この値はメッセージ本体のためのエ
      ンコーディングを記述します。これはヘッダ用のエンコーディングとは
      違うかもしれません。*body_encoding* では、"Charset.SHORTEST" を
      使うことはできません。

   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* は入力用の文字集合で、その文字集合の正式名称を指定する必
   要があります。

   オプション引数 *header_enc* および *body_enc* は quoted-printable
   エンコーディングを表す "Charset.QP" か、base64 エンコーディングを表
   す "Charset.BASE64"、最短の quoted-printable または base64 エンコー
   ディングを表す "Charset.SHORTEST"、あるいはエンコーディングなしの
   "None" のいずれかになります。"SHORTEST" が使えるのは *header_enc*
   だけです。デフォルトの値はエンコーディングなしの "None" になってい
   ます。

   オプション引数 *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 コーデックの名前です
   。
