###
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` を返します。