このモジュールは文字セットを表現する Charset クラスと 電子メールメッセージにふくまれる文字セット間の変換、および 文字セットのレジストリとこのレジストリを操作するための いくつかの便宜的なメソッドを提供します。Charset インスタンスは email パッケージ中にあるほかのいくつかのモジュールで使用されます。
このクラスは email.charset モジュールからimportしてください。
バージョン 2.2.2 で 新たに追加 された仕様です。
[input_charset]) |
このクラスはある特定の文字セットに対し、電子メールに課される制約の情報を提供します。 また、与えられた適用可能な 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 インスタンスは以下のようなデータ属性をもっています:
latin_1
は iso-8859-1
に変換されます)。
デフォルトは 7-bit の us-ascii
です。
Charset.QP
(quoted-printable エンコーディング)、
Charset.BASE64
(base64 エンコーディング)、あるいは
最短の QP または BASE64 エンコーディングである Charset.SHORTEST
に
設定されます。そうでない場合、この値は None
になります。
Charset.SHORTEST
を
使うことはできません。
None
になります。
None
になります。
None
になります。
この属性は input_codec と同じ値をもつことになるでしょう。
Charset インスタンスは、以下のメソッドも持っています:
) |
この値は使用しているエンコーディングの文字列 "quoted-printable" または "base64" か、 あるいは関数のどちらかです。後者の場合、これはエンコードされる Message オブジェクトを 単一の引数として取るような関数である必要があります。この関数は変換後 Content-Transfer-Encoding: ヘッダ自体を、なんであれ適切な値に設定する必要があります。
このメソッドは body_encoding が QP
の場合
"quoted-printable" を返し、body_encoding が BASE64
の場合
"base64" を返します。それ以外の場合は文字列 "7bit" を返します。
s) |
s) |
これは input_codec を使って文字列を Unicode にすることで、 文字と文字の境界で (たとえそれがマルチバイト文字であっても) 安全に split できるようにします。
input_charset の文字列 s をどうやって Unicode に変換すればいいかが 不明な場合、このメソッドは与えられた文字列そのものを返します。
Unicode に変換できなかった文字は、Unicode 置換文字 (Unicode replacement character) "U+FFFD" に置換されます。
ustr[, to_output]) |
このメソッドでは、文字列を Unicode からべつのエンコード形式に変換するために 適切な codec を使用します。与えられた文字列が Unicode ではなかった場合、 あるいはそれをどうやって Unicode から変換するか不明だった場合は、 与えられた文字列そのものが返されます。
Unicode から正しく変換できなかった文字については、 適当な文字 (通常は "?") に置き換えられます。
to_output が True
の場合 (デフォルト)、
このメソッドは output_codec をエンコードの形式として
使用します。to_output が False
の場合、これは
input_codec を使用します。
) |
これは output_charset 属性が None
でなければその値になります。
それ以外の場合、この値は input_charset と同じです。
) |
s[, convert]) |
convert が True
の場合、
文字列は入力用文字セットから出力用文字セットに自動的に変換されます。
これは行の長さ問題のあるマルチバイトの文字セットに対しては役に立ちません
(マルチバイト文字はバイト境界ではなく、文字ごとの境界で split する必要があります)。
これらの問題を扱うには、高水準のクラスである Header クラスを
使ってください (email.header を参照)。
convert の値はデフォルトでは False
です。
エンコーディングの形式 (base64 または quoted-printable) は、 header_encoding 属性に基づきます。
s[, convert]) |
convert が True
の場合 (デフォルト)、
文字列は入力用文字セットから出力用文字セットに自動的に変換されます。
header_encode() とは異なり、メッセージ本体にはふつう
バイト境界の問題やマルチバイト文字セットの問題がないので、
これはきわめて安全におこなえます。
エンコーディングの形式 (base64 または quoted-printable) は、 body_encoding 属性に基づきます。
Charset クラスには、 標準的な演算と組み込み関数をサポートする いくつかのメソッドがあります。
) |
other) |
other) |
また、email.charset モジュールには、 グローバルな文字セット、文字セットの別名(エイリアス) および codec 用のレジストリに 新しいエントリを追加する以下の関数もふくまれています:
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
内に保持されています。
alias, canonical) |
latin-1
のように指定します。
canonical はその文字セットの正式名称で、たとえば iso-8859-1
のように指定します。
文字セットのグローバルな別名用レジストリは、モジュールの global 辞書
ALIASES
内に保持されています。
charset, codecname) |
charset はある文字セットの正式名称で、 codecname は Python 用 codec の名前です。 これは組み込み関数 unicode() の第2引数か、 あるいは Unicode 文字列型の encode() メソッドに 適した形式になっていなければなりません。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。