\declaremodule{standard}{email.charset}
\modulesynopsis{文字セット}

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

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

\versionadded{2.2.2}

\begin{classdesc}{Charset}{\optional{input_charset}}
文字セットを email のプロパティに写像する。
Map character sets to their email properties.

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

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

以下ではオプション引数 \var{input_charset} について説明します。
この値はつねに小文字に強制的に変換されます。
そして文字セットの別名が正規化されたあと、この値は文字セットの
レジストリ内を検索し、ヘッダのエンコーディングと
メッセージ本体のエンコーディング、および出力時の変換に使われる codec をみつけるのに使われます。
たとえば \var{input_charset} が \code{iso-8859-1} の場合、ヘッダおよびメッセージ本体は
quoted-printable でエンコードされ、出力時の変換用 codec は必要ありません。
もし \var{input_charset} が \code{euc-jp} ならば、ヘッダは base64 でエンコードされ、
メッセージ本体はエンコードされませんが、出力されるテキストは \code{euc-jp} 文字セットから
\code{iso-2022-jp} 文字セットに変換されます。
\end{classdesc}

\class{Charset} インスタンスは以下のようなデータ属性をもっています:

\begin{datadesc}{input_charset}
最初に指定される文字セットです。
一般に通用している別名は、\emph{正式な} 電子メール用の名前に変換されます
(たとえば、\code{latin_1} は \code{iso-8859-1} に変換されます)。
デフォルトは 7-bit の \code{us-ascii} です。
\end{datadesc}

\begin{datadesc}{header_encoding}
この文字セットが電子メールヘッダに使われる前にエンコードされる必要がある場合、
この属性は \code{Charset.QP} (quoted-printable エンコーディング)、
\code{Charset.BASE64} (base64 エンコーディング)、あるいは
最短の QP または BASE64 エンコーディングである \code{Charset.SHORTEST} に
設定されます。そうでない場合、この値は \code{None} になります。
\end{datadesc}

\begin{datadesc}{body_encoding}
\var{header_encoding} と同じですが、この値はメッセージ本体のための
エンコーディングを記述します。これはヘッダ用のエンコーディングとは
違うかもしれません。\var{body_encoding} では、\code{Charset.SHORTEST} を
使うことはできません。
\end{datadesc}

\begin{datadesc}{output_charset}
文字セットによっては、電子メールのヘッダあるいはメッセージ本体に
使う前にそれを変換する必要があります。もし \var{input_charset} が
それらの文字セットのどれかをさしていたら、この \var{output_charset} 属性は
それが出力時に変換される文字セットの名前をあらわしています。
それ以外の場合、この値は \code{None} になります。
\end{datadesc}

\begin{datadesc}{input_codec}
\var{input_charset} を Unicode に変換するための Python 用 codec 名です。
変換用の codec が必要ないときは、この値は \code{None} になります。
\end{datadesc}

\begin{datadesc}{output_codec}
Unicode を \var{output_charset} に変換するための Python 用 codec 名です。
変換用の codec が必要ないときは、この値は \code{None} になります。
この属性は \var{input_codec} と同じ値をもつことになるでしょう。
\end{datadesc}

\class{Charset} インスタンスは、以下のメソッドも持っています:

\begin{methoddesc}[Charset]{get_body_encoding}{}
メッセージ本体のエンコードに使われる
content-transfer-encoding の値を返します。

この値は使用しているエンコーディングの文字列 \samp{quoted-printable} または \samp{base64} か、
あるいは関数のどちらかです。後者の場合、これはエンコードされる Message オブジェクトを
単一の引数として取るような関数である必要があります。この関数は変換後
\mailheader{Content-Transfer-Encoding} ヘッダ自体を、なんであれ適切な値に設定する必要があります。

このメソッドは \var{body_encoding} が \code{QP} の場合
\samp{quoted-printable} を返し、\var{body_encoding} が \code{BASE64} の場合
\samp{base64} を返します。それ以外の場合は文字列 \samp{7bit} を返します。
\end{methoddesc}

\begin{methoddesc}{convert}{s}
文字列 \var{s} を \var{input_codec} から \var{output_codec} に変換します。
\end{methoddesc}

\begin{methoddesc}{to_splittable}{s}
おそらくマルチバイトの文字列を、安全に split できる形式に変換します。
\var{s} には split する文字列を渡します。

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

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

Unicode に変換できなかった文字は、Unicode 置換文字
(Unicode replacement character) \character{U+FFFD} に置換されます。
\end{methoddesc}

\begin{methoddesc}{from_splittable}{ustr\optional{, to_output}}
split できる文字列をエンコードされた文字列に変換しなおします。
\var{ustr} は ``逆split'' するための Unicode 文字列です。

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

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

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

\begin{methoddesc}{get_output_charset}{}
出力用の文字セットを返します。

これは \var{output_charset} 属性が \code{None} でなければその値になります。
それ以外の場合、この値は \var{input_charset} と同じです。
\end{methoddesc}

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

\begin{methoddesc}{header_encode}{s\optional{, convert}}
文字列 \var{s} をヘッダ用にエンコードします。

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

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

\begin{methoddesc}{body_encode}{s\optional{, convert}}
文字列 \var{s} をメッセージ本体用にエンコードします。

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

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

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

\begin{methoddesc}[Charset]{__str__}{}
\var{input_charset} を小文字に変換された文字列型として返します。
\method{__repr__()} は、\method{__str__()} の別名となっています。
\end{methoddesc}

\begin{methoddesc}[Charset]{__eq__}{other}
このメソッドは、2つの \class{Charset} インスタンスが同じかどうかをチェックするのに使います。
\end{methoddesc}

\begin{methoddesc}[Header]{__ne__}{other}
このメソッドは、2つの \class{Charset} インスタンスが異なるかどうかをチェックするのに使います。
\end{methoddesc}

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

\begin{funcdesc}{add_charset}{charset\optional{, header_enc\optional{,
    body_enc\optional{, output_charset}}}}
文字の属性をグローバルなレジストリに追加します。

\var{charset} は入力用の文字セットで、その文字セットの正式名称を指定する必要があります。

オプション引数 \var{header_enc} および \var{body_enc} は
quoted-printable エンコーディングをあらわす \code{Charset.QP} か、
base64 エンコーディングをあらわす \code{Charset.BASE64}、
最短の quoted-printable または base64 エンコーディングをあらわす
\code{Charset.SHORTEST}、あるいはエンコーディングなしの \code{None} の
どれかになります。\code{SHORTEST} が使えるのは \var{header_enc} だけです。
デフォルトの値はエンコーディングなしの \code{None} になっています。

オプション引数 \var{output_charset} には出力用の文字セットが入ります。
\method{Charset.convert()} が呼ばれたときの変換は
まず入力用の文字セットを Unicode に変換し、それから出力用の文字セットに
変換されます。デフォルトでは、出力は入力と同じ文字セットになっています。

\var{input_charset} および \var{output_charset} は
このモジュール中の文字セット-codec 対応表にある Unicode codec エントリである
必要があります。モジュールがまだ対応していない codec を追加するには、
\function{add_codec()} を使ってください。より詳しい情報については
\refmodule{codecs} モジュールの文書を参照してください。

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

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

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

\begin{funcdesc}{add_codec}{charset, codecname}
与えられた文字セットの文字と Unicode との変換をおこなう codec を追加します。

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