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

このモジュールは文字セットを表現する "Charset" クラスと電子メールメッ
セージにふくまれる文字セット間の変換、および文字セットのレジストリとこ
のレジストリを操作するためのいくつかの便宜的なメソッドを提供します。
"Charset" インスタンスは "email" パッケージ中にあるほかのいくつかのモ
ジュールで使用されます。

このクラスは "email.charset" モジュールから import してください。

バージョン 2.2.2 で追加.

class email.charset.Charset([input_charset])

   文字セットを email のプロパティに写像する。

   このクラスはある特定の文字セットに対し、電子メールに課される制約の
   情報を提供します。また、与えられた適用可能な codec をつかって、文字
   セット間の変換をおこなう便宜的なルーチンも提供します。またこれは、
   ある文字セットが与えられたときに、その文字セットを電子メールメッセ
   ージのなかでどうやって RFC に準拠したやり方で使用するかに関する、で
   きうるかぎりの情報も提供します。

   文字セットによっては、それらの文字を電子メールのヘッダあるいはメッ
   セージ本体で使う場合は quoted-printable 形式あるいは base64形式でエ
   ンコードする必要があります。またある文字セットはむきだしのまま変換
   する必要があり、電子メールの中では使用できません。

   以下ではオプション引数 *input_charset* について説明します。この値は
   つねに小文字に強制的に変換されます。そして文字セットの別名が正規化
   されたあと、この値は文字セットのレジストリ内を検索し、ヘッダのエン
   コーディングとメッセージ本体のエンコーディング、および出力時の変換
   に使われる codec をみつけるのに使われます。たとえば *input_charset*
   が "iso-8859-1" の場合、ヘッダおよびメッセージ本体は quoted-
   printable でエンコードされ、出力時の変換用 codec は必要ありません。
   もし *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 用 codec 名で
      す。変換用の codec が必要ないときは、この値は "None" になります
      。

   output_codec

      Unicode を *output_charset* に変換するための Python 用 codec 名
      です。変換用の codec が必要ないときは、この値は "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" を返します。

   convert(s)

      文字列 *s* を *input_codec* から *output_codec* に変換します。

   to_splittable(s)

      マルチバイトの可能性がある文字列を、安全に split できる形式に変
      換します。 *s* には split する文字列を渡します。

      これは *input_codec* を使って文字列を Unicode にすることで、文字
      と文字の境界で (たとえそれがマルチバイト文字であっても) 安全に
      split できるようにします。

      *input_charset* の文字列 *s* をどうやって Unicode に変換すればい
      いかが不明な場合、このメソッドは与えられた文字列そのものを返しま
      す。

      Unicode に変換できなかった文字は、Unicode 置換文字 (Unicode
      replacement character) "'U+FFFD'" に置換されます。

   from_splittable(ustr[, to_output])

      split できる文字列をエンコードされた文字列に変換しなおします。
      *ustr* は "unsplit" するための Unicode 文字列です。

      このメソッドでは、文字列を Unicode からエンコード形式に戻すため
      に適切な codec を使用します。与えられた文字列が Unicode ではなか
      った場合、あるいはそれをどうやって Unicode から変換するか不明だ
      った場合は、与えられた文字列そのものが返されます。

      Unicode から正しく変換できなかった文字については、適当な文字 (通
      常は "'?'") に置き換えられます。

      *to_output* が "True" の場合 (デフォルト)、このメソッドは
      *output_codec* をエンコードの形式として使用します。 *to_output*
      が "False" の場合、これは *input_codec* を使用します。

   get_output_charset()

      出力用の文字セットを返します。

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

   encoded_header_len()

      エンコードされたヘッダ文字列の長さを返します。これは quoted-
      printable エンコーディングあるいは base64 エンコーディングに対し
      ても正しく計算されます。

   header_encode(s[, convert])

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

      *convert* が "True" の場合、文字列は入力用文字セットから出力用文
      字セットに自動的に変換されます。これは行の長さ問題のあるマルチバ
      イトの文字セットに対しては役に立ちません (マルチバイト文字はバイ
      ト境界ではなく、文字ごとの境界で split する必要があります)。これ
      らの問題を扱うには、高水準のクラスである "Header" クラスを使って
      ください ("email.header" を参照)。 *convert* の値はデフォルトで
      は "False" です。

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

   body_encode(s[, convert])

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

      *convert* が "True" の場合 (デフォルト)、文字列は入力用文字セッ
      トから出力用文字セットに自動的に変換されます。 "header_encode()"
      とは異なり、メッセージ本体にはふつうバイト境界の問題やマルチバイ
      ト文字セットの問題がないので、これはきわめて安全におこなえます。

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

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

   __str__()

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

   __eq__(other)

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

   __ne__(other)

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

また、 "email.charset" モジュールには、グローバルな文字セット、文字セ
ットの別名(エイリアス) および codec 用のレジストリに新しいエントリを追
加する以下の関数もふくまれています:

email.charset.add_charset(charset[, header_enc[, body_enc[, output_charset]]])

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

   *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* はこのモジュール中の文字セ
   ット-codec 対応表にある Unicode codec エントリである必要があります
   。モジュールがまだ対応していない codec を追加するには、
   "add_codec()" を使ってください。より詳しい情報については "codecs"
   モジュールの文書を参照してください。

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

email.charset.add_alias(alias, canonical)

   文字セットの別名 (エイリアス) を追加します。*alias* はその別名で、
   たとえば "latin-1" のように指定します。*canonical* はその文字セット
   の正式名称で、たとえば "iso-8859-1" のように指定します。

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

email.charset.add_codec(charset, codecname)

   与えられた文字セットの文字と Unicode との変換をおこなう codec を追
   加します。

   *charset* はある文字セットの正式名称、 *codecname* は Python 用
   codec の名前です。後者は組み込み関数 "unicode()" の第 2 引数か、あ
   るいは Unicode 文字列型の "encode()" メソッドに適した形式になってい
   なければなりません。
