4.8 codecs -- codec レジストリと基底クラス

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

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

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

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

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

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

factory(errors='strict')

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

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

factory(stream, errors='strict')

ファクトリ関数は、基底クラスの StreamWriterStreamReader が定義しているインタフェースを提供する オブジェクトを返さねばなりません。ストリーム 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 が送出されます。

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

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_UTF16BOM_UTF16_BEBOM_UTF16_LE のいずれかで、プラットフォームの ネイティブバイトオーダに依存します。BOMBOM_UTF16 の別名です。同様に BOM_LEBOM_UTF16_LEの、BOM_BEBOM_UTF16_BE の別名です。他は UTF-8 と UTF-32 エンコーディングの BOM を表します。



ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。