このモジュールでは、標準のPython codec(エンコーダとデコーダ)の基底クラスを定義し、 codec およびエラー処理の検索手順を管理している、 内部的な Python codec レジストリ に対するアクセス手段を提供しています。
codecs では以下の関数を定義しています:
search_function) |
(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
を返すべきです。
encoding) |
最初に、レジストリのキャッシュから encoding を探します。見つからなければ、 登録されている検索関数のリストから探します。見つからなければ、 LookupError が発生し、見つかれば codec のタプルがキャッシュ に保存され、それを呼び出し側に返します。
さまざまな codec へのアクセスを簡便化するために、このモジュールは次に挙 げるような関数を提供します。これらは codec の検索に lookup() を使います。
encoding) |
encoding が見つからなければ LookupError が発生します。
encoding) |
encoding が見つからなければ LookupError が発生します。
encoding) |
encoding が見つからなければ LookupError が発生します。
encoding) |
encoding が見つからなければ LookupError が発生します。
name, error_handler) |
error_handler はエラーの場所に関する情報の入った UnicodeEncodeError インスタンスとともに呼び出されます。 エラー処理関数はこの例外を送出するか、別の例外を送出するか、または 入力のエンコードができなかった部分の代替文字列、およびどこからエンコードを 再開するかを指定するタプルを返さなければなりません。 エンコーダは代替文字列をエンコードし、元の入力の指定された場所から エンコードを再開します。負の位置は入力文字列の末端からの相対位置と して扱われます。返された位置が境界の外側にある場合には IndexError が送出されます。
デコードと翻訳は同様に働きますが、UnicodeDecodeError または UnicodeTranslateError がハンドラに渡される点が 異なります。また、エラーハンドラから得られた置換文字列が出力に直接 置かれる点も異なります。
name) |
エラー処理関数が見つからなければ LookupError が発生します。
exception) |
strict
エラー処理を実装しています。
exception) |
replace
エラー処理を実装しています。
exception) |
ignore
エラー処理を実装しています。
exception) |
xmlcharrefreplace
エラー処理を実装しています。
exception) |
backslashreplace
エラー処理を実装しています。
エンコードされたファイルやストリームの処理を簡便化するため、, このモジュ ールは次のようなユーティリティ関数を定義しています。
filename, mode[, encoding[, errors[, buffering]]]) |
注意: ラップされた版は、その codec で定義されたフォーマットのオブジェク トのみ受け付けます。多くの組み込み codec において Unicode オブジェクト です。出力も codec に依存し、通常は Unicode オブジェクトです。
encoding は、ファイルに使われるエンコーディングを指定します。
errors を指定して、エラー処理を定義することもできます。デフォルト
では 'strict'
で、エンコード時にエラーがあれば
ValueError が発生します。
buffering は、組み込み関数 open() と同じです。デフォル トでは、ラインバッファです。
file, input[, output[, errors]]) |
ラップされたファイルに書かれた文字列は、与えられた input エンコー ディングに従って変換され、output エンコーディングを使ってファイル に文字列として書き込まれます。中間エンコーディングは、通常 Unicode ですが、指 定された codecs に依存します。
output が与えられなければ、input がデフォルトになります。
errors を与えて、エラー処理を定義することもできます。デフォルト
では 'strict'
で、エンコード時にエラーがあれば
ValueError が発生します。
このモジュールは以下のような定数を定義します。プラットフォーム依存なファ イルを読み書きするのに役立ちます。
参考資料: