"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 コーデックの名前です
   。
