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