# 8 `codecs` -- codec レジストリと基底クラス

このモジュールでは、内部的な Python codec レジストリに対するアクセス手 段を提供しています。codec レジストリは、標準の Python codec(エンコー ダとデコーダ)の基底クラスを定義し、codec およびエラー処理の検索手順を 管理しています。

`codecs` では以下の関数を定義しています:

`register`( | search_function)

  codec 検索関数を登録します。検索関数は第 1 引数にアルファベットの小文字 から成るエンコーディング名を取り、 以下の属性を持つ `CodecInfo` オブジェクトを返します。

  - `name` エンコーディング名
  - `encoder` 内部状態を持たないエンコード関数
  - `decoder` 内部状態を持たないデコード関数
  - `incrementalencoder` 漸増的エンコーダクラスまたはファクトリ関数
  - `incrementaldecoder` 漸増的デコーダクラスまたはファクトリ関数
  - `streamwriter` ストリームライタクラスまたはファクトリ関数
  - `streamreader` ストリームリーダクラスまたはファクトリ関数

  種々の関数やクラスが以下の引数をとります。

  encoder と decoder: これらの引数は、Codec インスタンスの `encode()`と`decode()` (Codec Interface 参照) と同じ インタフェースを持つ関数、またはメソッドでなければなりません。これらの関 数・メソッドは内部状態を持たずに動作する (stateless mode) と想定されて います。

  incrementalencoder と incrementaldecoder: これらは 以下のインタフェースを持つファクトリ関数でなければなりません。

  `factory(errors='strict')`

  ファクトリ関数は、それぞれ基底クラスの `IncrementalEncoder` や `IncrementalDecoder` が定義しているインタフェースを提供する オブジェクトを返さねばなりません。漸増的 codecs は内部状態を維持できます。

  streamreader と streamwriter: これらの引数は、次のような インタフェースを持つファクトリ関数でなければなりません:

  `factory(stream, errors='strict')`

  ファクトリ関数は、基底クラスの `StreamWriter` や `StreamReader` が定義しているインタフェースを提供する オブジェクトを返さねばなりません。ストリーム codecs は内部状態を維持で きます。

  errors が取り得る値は、 `'strict'` (エンコーディングエラーの際に例外を発生)、 `'replace'` (奇形データを "`?`"等の適切な文字で置換)、 `'ignore'` (奇形データを無視し何も通知せずに処理を継続)、 `'xmlcharrefreplace''` (適切な XML 文字参照で置換 (エンコーディングのみ))、 および `'backslashreplace'` (バックスラッシュによるエスケープシーケンス (エンコーディングのみ)) と、`register_error()` で定義されたその他の エラー処理名になります。

  検索関数は、与えられたエンコーディングを見つけられなかった場合、 `None` を返さねばなりません。

`lookup`( | encoding)

  Python codec レジストリから codec 情報を探し、上で定義したような `CodecInfo` オブジェクトを返します。

  エンコーディングの検索は、まずレジストリのキャッシュから行います。 見つからなければ、登録されている検索関数のリストから探します。 `CodecInfo` オブジェクトが一つも見つからなければ `LookupError` を送出します。 見つかったら、その `CodecInfo` オブジェクトはキャッシュに保存され、 呼び出し側に返されます。

さまざまな codec へのアクセスを簡便化するために、このモジュールは以下 のような関数を提供しています。これらの関数は、 codec の検索に `lookup()` を使います。

`getencoder`( | encoding)

  encoding に指定した codec を検索し、エンコーダ関数を返します。

  encoding が見つからなければ `LookupError` を送出します。

`getdecoder`( | encoding)

  encoding に指定した codec を検索し、デコーダ関数を返します。

  encoding が見つからなければ `LookupError` を送出します。

`getincrementalencoder`( | encoding)

  encoding に指定した codec を検索し、漸増的エンコーダクラス、またはファク トリ関数を返します。

  encoding が見つからない、もしくは codec が漸増的エンコーダをサポートしないとき `LookupError` を送出します。 バージョン 2.5 で 新たに追加 された仕様です。

`getincrementaldecoder`( | encoding)

  encoding に指定した codec を検索し、漸増的デコーダクラス、またはファク トリ関数を返します。

  encoding が見つからない、もしくは codec が漸増的デコーダをサポートしないとき `LookupError` を送出します。 バージョン 2.5 で 新たに追加 された仕様です。

`getreader`( | encoding)

  encoding に指定した codec を検索し、StreamReader クラス、またはファク トリ関数を返します。

  encoding が見つからなければ `LookupError` を送出します。

`getwriter`( | encoding)

  encoding に指定した codec を検索し、StreamWriter クラス、またはファク トリ関数を返します。

  encoding が見つからなければ `LookupError` を送出します。

`register_error`( | name, error_handler)

  エラー処理関数 error_handler を名前 name で登録します。 エンコード中およびデコード中にエラーが送出された場合、 errors パラメタにname を指定していれば error_handler を呼び出すようになります。

  error_handler はエラーの場所に関する情報の入った `UnicodeEncodeError` インスタンスとともに呼び出されます。 エラー処理関数はこの例外を送出するか、別の例外を送出するか、または 入力のエンコードができなかった部分の代替文字列とエンコードを再開する 場所の指定が入ったタプルを返すかしなければなりません。最後の場合、 エンコーダは代替文字列をエンコードし、元の入力中の指定位置から エンコードを再開します。位置を負の値にすると、入力文字列の末端からの 相対位置として扱われます。境界の外側にある位置を返した場合には `IndexError` が送出されます。

  デコードと翻訳は同様に働きますが、エラー処理関数に渡されるのが `UnicodeDecodeError` か`UnicodeTranslateError` である点と、エラー処理関数の置換した内容が直接出力になる点が異なります。

`lookup_error`( | name)

  名前name で登録済みのエラー処理関数を返します。

  エラー処理関数が見つからなければ `LookupError` を送出します。

`strict_errors`( | exception)

  `strict` エラー処理の実装です。

`replace_errors`( | exception)

  `replace` エラー処理の実装です。

`ignore_errors`( | exception)

  `ignore` エラー処理の実装です。

`xmlcharrefreplace_errors_errors`( | exception)

  `xmlcharrefreplace` エラー処理の実装です。

`backslashreplace_errors_errors`( | exception)

  `backslashreplace` エラー処理の実装です。

エンコードされたファイルやストリームの処理を簡便化するため、, このモジュ ールは次のようなユーティリティ関数を定義しています。

`open`( | filename, mode[, encoding[, errors[, buffering]]])

  mode でエンコードされたファイルを開き、 透過的にエンコード・デコードを行うようにラップしたファイルオブジェクト を返します。

  注意: ラップ版のファイルオブジェクトを操作する関数は、該当する codec が定義している形式のオブジェクトだけを受け付けます。 多くの組み込み codec では Unicode オブジェクトです。 関数の戻り値も codec に依存し、通常は Unicode オブジェクトです。

  encoding にはファイルのエンコーディングを指定します。

  errors を指定して、エラー処理を定義することもできます。デフォルト では `'strict'` で、エンコード時にエラーがあれば `ValueError` を送出します。

  buffering は、組み込み関数 `open()` と同じです。デフォル トでは行バッファリングです。

`EncodedFile`( | file, input[, output[, errors]])

  ラップしたファイルオブジェクトを返します。このオブジェクトは透過な エンコード変換を提供します。

  ラップされたファイルに書かれた文字列は、input に指定したエンコー ディングに従って変換され、output に指定したエンコーディングを使っ て string 型に変換され、ファイルに書き込まれます。中間エンコーディング は指定された codecs に依存しますが、普通は Unicode です。

  output が与えられなければ、input がデフォルトになります。

  errors を与えて、エラー処理を定義することもできます。デフォルト では `'strict'` で、エンコード時にエラーがあれば `ValueError` を送出します。

`iterencode`( | iterable, encoding[, errors])

  漸増的エンコーダを使って、iterable から供給される入力を反復的に エンコードします。この関数はジェネレータです。errors は (そして他のキーワード引数も同様に)漸増的エンコーダにそのまま引き渡されます。 バージョン 2.5 で 新たに追加 された仕様です。

`iterdecode`( | iterable, encoding[, errors])

  漸増的デコーダを使って、iterable から供給される入力を反復的に デコードします。この関数はジェネレータです。errors は (そして他のキーワード引数も同様に)漸増的デコーダにそのまま引き渡されます。 バージョン 2.5 で 新たに追加 された仕様です。

このモジュールは以下のような定数も定義しています。プラットフォーム依存なファ イルを読み書きするのに役立ちます。

`BOM`
`BOM_BE`
`BOM_LE`
`BOM_UTF8`
`BOM_UTF16`
`BOM_UTF16_BE`
`BOM_UTF16_LE`
`BOM_UTF32`
`BOM_UTF32_BE`
`BOM_UTF32_LE`
  ここで定義された定数は、様々なエンコーディングの Unicode の バイトオーダマーカ (BOM) で、UTF-16 と UTF-32 における データストリームやファイルストリームのバイトオーダを指定したり、 UTF-8 における Unicode signature として使われます。 `BOM_UTF16` は `BOM_UTF16_BE` と `BOM_UTF16_LE` のいずれかで、プラットフォームの ネイティブバイトオーダに依存します。`BOM` は `BOM_UTF16` の別名です。同様に `BOM_LE`は `BOM_UTF16_LE`の、`BOM_BE` は `BOM_UTF16_BE` の別名です。他は UTF-8 と UTF-32 エンコーディングの BOM を表します。