Python では、処理速度を高めるために C で書かれた一そろいの codec を提供しています。これらの codec は全て以下の関数を介して 直接利用できます。
以下の API の多くが、 encoding と errors という二つの 引数をとります。これらのパラメタは、組み込みの Unicode オブジェクト コンストラクタである unicode() における同名のパラメタと同じ セマンティクスになっています。
encoding を NULL にすると、デフォルトエンコーディング である ASCIIを使います。ファイルシステムに関する関数の呼び出し では、ファイル名に対するエンコーディングとして Py_FileSystemDefaultEncoding を使わねばなりません。 この変数は読み出し専用の変数として扱わねばなりません: この変数は、あるシステムによっては静的な文字列に対するポインタで あったり、また別のシステムでは、(アプリケーションが setlocale を読んだときなどに) 変わったりもします。
errors で指定するエラー処理もまた、 NULL を指定できます。 NULL を指定すると、codec で定義されているデフォルト処理の使用を 意味します。全ての組み込み codec で、デフォルトのエラー処理は ``strict'' (ValueError を送出する) になっています。
個々の codec は全て同様のインタフェースを使っています。個別の codec の説明では、説明を簡単にするために以下の汎用のインタフェースとの 違いだけを説明しています。
以下は汎用 codec の API です:
const char *s, int size, const char *encoding, const char *errors) |
const Py_UNICODE *s, int size, const char *encoding, const char *errors) |
PyObject *unicode, const char *encoding, const char *errors) |
以下は UTF-8 codec の APIです:
const char *s, int size, const char *errors) |
const char *s, int size, const char *errors, int *consumed) |
consumed が NULL の場合、PyUnicode_DecodeUTF8() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF8Stateful() は末尾の不完全な UTF-8 バイト列 をエラーとみなしません。これらのバイト列はデコードされず、デコードされた バイト数を consumed に返します。 バージョン 2.4 で 新たに追加 された仕様です。
const Py_UNICODE *s, int size, const char *errors) |
PyObject *unicode) |
以下は UTF-16 codec の APIです:
const char *s, int size, const char *errors, int *byteorder) |
byteorder が NULL でない場合、デコード機構は以下の ように指定されたバイト整列 (byte order) に従ってデコードを開始 します:
*byteorder == -1: リトルエンディアン *byteorder == 0: ネイティブ *byteorder == 1: ビッグエンディアン
その後、入力データ中に見つかった全てのバイト整列マーカ (byte order mark, BOM) に従って、バイト整列を切り替えます。 BOM はデコード結果の Unicode 文字列中にはコピーされません。 デコードを完結した後、*byteorder は入力データの終点現在に おけるバイト整列に設定されます。
byteorder が NULL の場合、 codec はネイティブバイト整列の モードで開始します。
codec が例外を送出した場合にはNULL を返します。
const char *s, int size, const char *errors, int *byteorder, int *consumed) |
const Py_UNICODE *s, int size, const char *errors, int byteorder) |
s 中の Unicode データを UTF-16 でエンコードした結果が入っている
Python 文字列オブジェクトを返します。
byteorder が 0
でない場合、出力は以下のバイト整列
指定に従って書き出されます:
byteorder == -1: リトルエンディアン byteorder == 0: ネイティブ (BOM マーカを書き出します) byteorder == 1: ビッグエンディアン
バイトオーダが 0
の場合、出力結果となる文字列は常に
Unicode BOM マーカ (U+FEFF) で始まります。それ以外のモードでは、
BOM マーカを頭につけません。
Py_UNICODE_WIDE が定義されている場合、単一のPy_UNICODE 値はサロゲートペアとして表現されることがあります。 Py_UNICODE_WIDE が定義されていなければ、各Py_UNICODE 値 は UCS-2 文字として表現されます。
codec が例外を送出した場合にはNULL を返します。
PyObject *unicode) |
以下は ``Unicode Escape'' codec の APIです:
const char *s, int size, const char *errors) |
const Py_UNICODE *s, int size, const char *errors) |
PyObject *unicode) |
以下は ``Raw Unicode Escape'' codec の APIです:
const char *s, int size, const char *errors) |
const Py_UNICODE *s, int size, const char *errors) |
PyObject *unicode) |
以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、 エンコード時にはこの 256 個だけを受理します。
const char *s, int size, const char *errors) |
const Py_UNICODE *s, int size, const char *errors) |
PyObject *unicode) |
以下は ASCII codec の APIです: 7 ビットの ASCII データだけを受理します。その他のコードは エラーになります。
const char *s, int size, const char *errors) |
const Py_UNICODE *s, int size, const char *errors) |
PyObject *unicode) |
以下は mapping codec の APIです:
この codec は、多くの様々な codec を実装する際に使われるという点で 特殊な codec です (実際、encodings パッケージに入っている 標準 codecs のほとんどは、この codec を使っています)。 この codec は、文字のエンコードやデコードにマップ型 (mapping) を使います。
デコード用のマップ型は、文字列型の字列一組みを、 Unicode 型の字列一組、
整数 (Unicode 序数として解釈されます) または None
("定義されていない
対応付け(undefined mapping)" を意味し、エラーを引き起こします) の
いずれかに対応付けなければなりません。
デコード用のマップ型は、Unicode 型の字列一組みを、 string 型の字列一組、
整数 (Latin-1 序数として解釈されます) または None
("定義されていない
対応付け(undefined mapping)" を意味し、エラーを引き起こします) の
いずれかに対応付けなければなりません。
マップ型オブジェクトは、 __getitem__ マップ型インタフェース をサポートしなければなりません。
ある文字の検索が LookupError によって失敗すると、その文字は そのままコピーされます。すなわち、その文字の序数値がそれぞれ Unicode または Latin-1 として解釈されます。このため、codec を 実現するマップ型に入れる必要がある対応付け関係は、ある文字を別の コード点に対応付けるものだけです。
const char *s, int size, PyObject *mapping, const char *errors) |
エンコードされた size バイトの文字列 s から mapping に指定されたオブジェクトを使って Unicode オブジェクトを 生成します。codec が例外を送出した場合にはNULL を返します。
const Py_UNICODE *s, int size, PyObject *mapping, const char *errors) |
PyObject *unicode, PyObject *mapping) |
以下の codec API は Unicode から Unicode への対応付けを行う 特殊なものです。
const Py_UNICODE *s, int size, PyObject *table, const char *errors) |
対応付けを行う table は、 Unicode 序数を表す整数を
Unicode 序数を表す整数または None
に対応付けます。
(None
の場合にはその文字を削除します)
対応付けテーブルが提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書や シーケンス型を使ってもうまく動作します。対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、 変換は行わず、そのままコピーします。
以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一の エンコード方式を表すわけでなないので注意してください。 利用されるエンコード方式 (target encoding) は、 codec を動作 させているマシン上のユーザ設定で定義されています。
const char *s, int size, const char *errors) |
const Py_UNICODE *s, int size, const char *errors) |
PyObject *unicode) |
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。