Python/C API リファレンスマニュアル

Previous: 7.3.2 Unicode オブジェクト (Unicode Up: 7.3.2 Unicode オブジェクト (Unicode Next: 7.3.2.2 メソッドおよびスロット関数 (slot function)

---

7.3.2.1 組み込み codec (built-in codec)

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 です:

PyObject* PyUnicode_Decode(

const char *s, Py_ssize_t size, const char *encoding, const char *errors)

戻り値: 新たな参照.

何らかのエンコード方式でエンコードされた、 size バイトの 文字列 s をデコードして Unicode オブジェクトを生成します。 encoding と errors は、組み込み関数 unicode() の同名の パラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_Encode(

const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)

戻り値: 新たな参照.

size で指定されたサイズの Py_UNICODE バッファを エンコードした Python 文字列オブジェクトを返します。 encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsEncodedString(

PyObject *unicode, const char *encoding, const char *errors)

戻り値: 新たな参照.

Unicode オブジェクトをエンコードし、その結果を Python 文字列 オブジェクトとして返します。encoding および errors は Unicode 型の encode() メソッドに与える同名のパラメタと 同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。

以下は UTF-8 codec の APIです:

PyObject* PyUnicode_DecodeUTF8(

const char *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

UTF-8 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_DecodeUTF8Stateful(

const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

戻り値: 新たな参照.

consumed が NULL の場合、PyUnicode_DecodeUTF8() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF8Stateful() は末尾の不完全な UTF-8 バイト列 をエラーとみなしません。これらのバイト列はデコードされず、デコードされた バイト数を consumed に返します。 バージョン 2.4 で 新たに追加 された仕様です。

PyObject* PyUnicode_EncodeUTF8(

const Py_UNICODE *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを UTF-8 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsUTF8String(

PyObject *unicode)

戻り値: 新たな参照.

UTF-8 で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は UTF-16 codec の APIです:

PyObject* PyUnicode_DecodeUTF16(

const char *s, Py_ssize_t size, const char *errors, int *byteorder)

戻り値: 新たな参照.

UTF-16 でエンコードされたバッファ s から size バイト デコードして、結果を Unicode オブジェクトで返します。 errors は (NULL でない場合) エラー処理方法を定義します。 デフォルト値は ``strict'' です。

byteorder が NULL でない場合、デコード機構は以下の ように指定されたバイト整列 (byte order) に従ってデコードを開始 します:

   *byteorder == -1: リトルエンディアン
   *byteorder == 0:  ネイティブ
   *byteorder == 1:  ビッグエンディアン

その後、入力データ中に見つかった全てのバイト整列マーカ (byte order mark, BOM) に従って、バイト整列を切り替えます。 BOM はデコード結果の Unicode 文字列中にはコピーされません。 デコードを完結した後、*byteorder は入力データの終点現在に おけるバイト整列に設定されます。

byteorder が NULL の場合、 codec はネイティブバイト整列の モードで開始します。

codec が例外を送出した場合にはNULL を返します。

PyObject* PyUnicode_DecodeUTF16Stateful(

const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

戻り値: 新たな参照.

consumed が NULL の場合、PyUnicode_DecodeUTF16() と同じように動作します。 consumed が NULL でない場合、 PyUnicode_DecodeUTF16Stateful() は末尾の不完全な UTF-16 バイト列 (奇数長のバイト列や分割されたサロゲートペア) をエラーとみなしません。 これらのバイト列はデコードされず、デコードされたバイト数を consumed に返します。 バージョン 2.4 で 新たに追加 された仕様です。

PyObject* PyUnicode_EncodeUTF16(

const Py_UNICODE *s, Py_ssize_t 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* PyUnicode_AsUTF16String(

PyObject *unicode)

戻り値: 新たな参照.

ネイティブバイトオーダの UTF-16 でエンコードされた Python 文字列を返します。 文字列は常に BOM マーカから始まります。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は ``Unicode Escape'' codec の APIです:

PyObject* PyUnicode_DecodeUnicodeEscape(

const char *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeUnicodeEscape(

const Py_UNICODE *s, Py_ssize_t size)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsUnicodeEscapeString(

PyObject *unicode)

戻り値: 新たな参照.

Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は ``Raw Unicode Escape'' codec の APIです:

PyObject* PyUnicode_DecodeRawUnicodeEscape(

const char *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

Raw-Unicode-Escape でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeRawUnicodeEscape(

const Py_UNICODE *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを Raw-Unicode-Escape でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsRawUnicodeEscapeString(

PyObject *unicode)

戻り値: 新たな参照.

Raw-Unicode-Escape で Unicode オブジェクトをエンコードし、結果を Python 文字列オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は Latin-1 codec の APIです: Latin-1 は、 Unicode 序数の最初の 256 個に対応し、 エンコード時にはこの 256 個だけを受理します。

PyObject* PyUnicode_DecodeLatin1(

const char *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

Latin-1 でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeLatin1(

const Py_UNICODE *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを Latin-1 でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsLatin1String(

PyObject *unicode)

戻り値: 新たな参照.

Latin-1 で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は ASCII codec の APIです: 7 ビットの ASCII データだけを受理します。その他のコードは エラーになります。

PyObject* PyUnicode_DecodeASCII(

const char *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

ASCII でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_EncodeASCII(

const Py_UNICODE *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを ASCII でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsASCIIString(

PyObject *unicode)

戻り値: 新たな参照.

ASCII で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下は 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 を 実現するマップ型に入れる必要がある対応付け関係は、ある文字を別の コード点に対応付けるものだけです。

PyObject* PyUnicode_DecodeCharmap(

const char *s, Py_ssize_t size, PyObject *mapping, const char *errors)

戻り値: 新たな参照.

エンコードされた size バイトの文字列 s から mapping に指定されたオブジェクトを使って Unicode オブジェクトを 生成します。codec が例外を送出した場合にはNULL を返します。 もし、mappingがNULLだった場合、latin-1でデコーディングされます。 それ以外の場合では、mappingはbyteに対する辞書マップ (訳注: sに含まれる文字のunsignedな値をint型でキーとして、値として変換対象の Unicode文字を表すUnicode文字列になっているような辞書) か、ルックアップテーブルと して扱われるunicode文字列です。

文字列(訳注: mappingがunicode文字列として渡された場合)の長さより大きい byte値や、(訳注: mappingにしたがって変換した結果が) U+FFFE "characters" になる Byte値は、"undefined mapping" として扱われます。 バージョン 2.4 で 変更 された仕様: mapping引数としてunicodeが使えるようになりました

PyObject* PyUnicode_EncodeCharmap(

const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを mapping に指定されたオブジェクトを使ってエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsCharmapString(

PyObject *unicode, PyObject *mapping)

戻り値: 新たな参照.

Unicode オブジェクトを mapping に指定されたオブジェクトを使って エンコードし、結果を Python 文字列オブジェクトとして返します。 エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

以下の codec API は Unicode から Unicode への対応付けを行う 特殊なものです。

PyObject* PyUnicode_TranslateCharmap(

const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors)

戻り値: 新たな参照.

で 指定された長さを持つ Py_UNICODE バッファを、 文字変換マップ table を適用して変換し、変換結果を Unicode オブジェクトで返します。codec が例外を発行した場合には NULL を返します。

対応付けを行う table は、 Unicode 序数を表す整数を Unicode 序数を表す整数または None に対応付けます。 (None の場合にはその文字を削除します)

対応付けテーブルが提供する必要があるメソッドは __getitem__() インタフェースだけです; 従って、辞書や シーケンス型を使ってもうまく動作します。対応付けを行っていない (LookupError を起こすような) 文字序数に対しては、 変換は行わず、そのままコピーします。

以下は MBCS codec の API です。この codec は現在のところ、 Windows 上だけで利用でき、変換の実装には Win32 MBCS 変換機構 (Win32 MBCS converter) を使っています。 MBCS (または DBCS) はエンコード方式の種類 (class) を表す言葉で、単一の エンコード方式を表すわけでなないので注意してください。 利用されるエンコード方式 (target encoding) は、 codec を動作 させているマシン上のユーザ設定で定義されています。

PyObject* PyUnicode_DecodeMBCS(

const char *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

MBCS でエンコードされた size バイトの文字列 s から Unicode オブジェクトを生成します。codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_DecodeMBCSStateful(

const char *s, int size, const char *errors, int *consumed)

consumedがNULLのとき、PyUnicode_DecodeMBCS()と同じ動作をします。 consumedがNULLでないとき、PyUnicode_DecodeMBCSStateful()は 文字列の最後にあるマルチバイト文字の前半バイトをデコードせず、 consumedにデコードしたバイト数を格納します。 バージョン 2.5 で 新たに追加 された仕様です。

PyObject* PyUnicode_EncodeMBCS(

const Py_UNICODE *s, Py_ssize_t size, const char *errors)

戻り値: 新たな参照.

size で指定された長さを持つ Py_UNICODE 型バッファを MBCS でエンコードし、 Python 文字列オブジェクトにして返します。 codec が例外を送出した場合には NULL を返します。

PyObject* PyUnicode_AsMBCSString(

PyObject *unicode)

戻り値: 新たな参照.

MBCS で Unicode オブジェクトをエンコードし、結果を Python 文字列 オブジェクトとして返します。エラー処理は ``strict'' です。 codec が例外を送出した場合にはNULL を返します。

---

Python/C API リファレンスマニュアル

Previous: 7.3.2 Unicode オブジェクト (Unicode Up: 7.3.2 Unicode オブジェクト (Unicode Next: 7.3.2.2 メソッドおよびスロット関数 (slot function)

---

リリース 2.5 ，19th September, 2006 更新