19.1.12. email.charset: 文字集合の表現¶
ソースコード: 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¶ この文字集合が電子メールヘッダに使われる前にエンコードされなければならない場合、この属性は
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__()の別名となっています。
-
また、 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内に保持されています。