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

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

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

`register`( | search_function)

  codec 検索関数を登録します。検索関数は第 1 引数にアルファベットの小文字 から成るエンコーディング名を取り、関数のタプル `(encoder, decoder, stream_reader,stream_writer)` を返すことに なっています。戻り値の関数が取る引数は以下の通りです。

  encoder と decoder: これらは、Codec インスタンスの `encode()`と`decode()` (Codec Interface 参照) と同じインターフェイスを 持つ関数、またはメソッドでなければなりません。 これらの関数・メソッドは状態なし (stateless) モードで動作しなければなりません。

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

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

  これらのファクトリ関数は、それぞれの基底クラスである `StreamWriter` と `StreamReader` で定義されているインターフェイスを 提供するオブジェクトを返さなければいけません。ストリーム codecs は状態を保持することができます。

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

  検索関数が与えられたエンコーディングを見つけられなかった場合には、 `None`を返すべきです。

`lookup`( | encoding)

  Python codec レジストリから codec タプルを探し、上の項目で定義された関数 のタプルを返します。

  最初に、レジストリのキャッシュから encoding を探します。見つからなければ、 登録されている検索関数のリストから探します。見つからなければ、 `LookupError` が発生し、見つかれば codec のタプルがキャッシュ に保存され、それを呼び出し側に返します。

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

`getencoder`( | encoding)

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

  encoding が見つからなければ `LookupError` が発生します。

`getdecoder`( | encoding)

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

  encoding が見つからなければ `LookupError` が発生します。

`getreader`( | encoding)

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

  encoding が見つからなければ `LookupError` が発生します。

`getwriter`( | encoding)

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

  encoding が見つからなければ `LookupError` が発生します。

`register_error`( | name, error_handler)

  エラー処理関数 error_handler を名前 name で登録します。 エンコード中およびデコード中にエラーが発生した場合、 name が errors パラメタとして指定されていれば 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 エンコーディングを使ってファイル に文字列として書き込まれます。中間エンコーディングは、通常 Unicode ですが、指 定された codecs に依存します。

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

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

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

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

参考資料:

http://sourceforge.net/projects/python-codecs/
  Python で使う、 アジア文字用の codec のサポートに取り組む SourceForge のプロジェクト。 この文書の執筆時点では開発の初期段階です。 -- ダウンロード可能なファイ ルについては、プロジェクトの FTP エリア を見てください。