7.8.1.1.Codec オブジェクト¶

Codec クラスは以下のメソッドを定義します。これらのメソッドは、内部状態を持たないエンコーダ／デコーダ関数のインタフェースを定義します:

Codec.encode(input[,errors])¶

オブジェクトinput エンコードし、(出力オブジェクト, 消費した長さ) のタプルを返します。 codecs は Unicode 専用ではありませんが、 Unicode の文脈では、エンコーディングは Unicode オブジェクトを特定の文字集合エンコーディング(たとえばcp1252 やiso-8859-1) を使ってバイト文字列オブジェクトに変換します。

errors は適用するエラー処理を定義します。'strict' 処理がデフォルトです。

このメソッドはCodec に内部状態を保存してはなりません。効率よくエンコードするために状態を保持しなければならないような codecs にはStreamWriter を使ってください。

エンコーダは長さが 0 の入力を処理できなければなりません。この場合、空のオブジェクトを出力オブジェクトとして返さなければなりません。

Codec.decode(input[,errors])¶

オブジェクトinput をデコードし、(出力オブジェクト, 消費した長さ) のタプルを返します。 Unicode の文脈では、デコードは特定の文字集合エンコーディングでエンコードされた文字列を Unicode オブジェクトに変換します。

input はbf_getreadbuf バッファスロットを提供するオブジェクトでなければなりません。バッファスロットを提供しているオブジェクトには Python 文字列オブジェクト、バッファオブジェクト、メモリマップファイルがあります。

errors は適用するエラー処理を定義します。'strict' 処理がデフォルトです。

このメソッドは、Codec インスタンスに内部状態を保存してはなりません。効率よくエンコード／デコードするために状態を保持しなければならないような codecs にはStreamReader を使ってください。

デコーダは長さが 0 の入力を処理できなければなりません。この場合、空のオブジェクトを出力オブジェクトとして返さなければなりません。

IncrementalEncoder クラスおよびIncrementalDecoder クラスはそれぞれ漸増的エンコーディングおよびデコーディングのための基本的なインタフェースを提供します。エンコーディング／デコーディングは内部状態を持たないエンコーダ／デコーダを一度呼び出すことで行なわれるのではなく、漸増的エンコーダ／デコーダのencode()/decode() メソッドを複数回呼び出すことで行なわれます。漸増的エンコーダ／デコーダはメソッド呼び出しの間エンコーディング／デコーディング処理の進行を管理します。

encode()/decode() メソッド呼び出しの出力結果をまとめたものは、入力をひとまとめにして内部状態を持たないエンコーダ／デコーダでエンコード／デコードしたものと同じになります。

7.8.1.2.IncrementalEncoder オブジェクト¶

IncrementalEncoder クラスは入力を複数ステップでエンコードするのに使われます。全ての漸増的エンコーダが Python codec レジストリと互換性を持つために定義すべきメソッドとして、このクラスには以下のメソッドが定義されています。

classcodecs.IncrementalEncoder([errors])¶

IncrementalEncoder インスタンスのコンストラクタ。

全ての漸増的エンコーダはこのコンストラクタインタフェースを提供しなければなりません。さらにキーワード引数を付け加えるのは構いませんが、Python codec レジストリで利用されるのはここで定義されているものだけです。

IncrementalEncoder はerrors キーワード引数を提供して異なったエラー取扱方法を実装することもできます。あらかじめ定義されているパラメータは以下の通りです:

• 'strict'ValueError (またはそのサブクラス) を送出します。これがデフォルトです。

• 'ignore' 一文字無視して次に進みます。

• 'replace' 適当な代替文字で置き換えます。

• 'xmlcharrefreplace' 適切な XML 文字参照に置き換えます。

• 'backslashreplace' バックスラッシュ付きのエスケープシーケンスで置き換えます。

引数errors は同名の属性に割り当てられます。属性に割り当てることでIncrementalEncoder オブジェクトが生きている間にエラー取扱戦略を違うものに切り替えることができるようになります。

errors 引数に許される値の集合はregister_error() で拡張できます。

encode(object[,final])¶

object を(エンコーダの現在の状態を考慮に入れて)エンコードし、得られたエンコードされたオブジェクトを返します。encode() 呼び出しがこれで最後という時にはfinal は真でなければなりません(デフォルトは偽です)。

reset()¶

エンコーダを初期状態にリセットします。

7.8.1.3.IncrementalDecoder オブジェクト¶

IncrementalDecoder クラスは入力を複数ステップでデコードするのに使われます。全ての漸増的デコーダが Python codec レジストリと互換性を持つために定義すべきメソッドとして、このクラスには以下のメソッドが定義されています。

classcodecs.IncrementalDecoder([errors])¶

IncrementalDecoder インスタンスのコンストラクタ。

全ての漸増的デコーダはこのコンストラクタインタフェースを提供しなければなりません。さらにキーワード引数を付け加えるのは構いませんが、Python codec レジストリで利用されるのはここで定義されているものだけです。

IncrementalDecoder はerrors キーワード引数を提供して異なったエラー取扱方法を実装することもできます。あらかじめ定義されているパラメータは以下の通りです:

• 'strict'ValueError (またはそのサブクラス) を送出します。これがデフォルトです。

• 'ignore' 一文字無視して次に進みます。

• 'replace' 適切な置換文字で置換します。

引数errors は同名の属性に割り当てられます。属性に割り当てることでIncrementalDecoder オブジェクトが生きている間にエラー取扱戦略を違うものに切り替えることができるようになります。

errors 引数に許される値の集合はregister_error() で拡張できます。

decode(object[,final])¶

object を(デコーダの現在の状態を考慮に入れて)デコードし、得られたデコードされたオブジェクトを返します。decode() 呼び出しがこれで最後という時にはfinal は真でなければなりません(デフォルトは偽です)。もしfinal が真ならばデコーダは入力をデコードし切り全てのバッファをフラッシュしなければなりません。そうできない場合(たとえば入力の最後に不完全なバイト列があるから)、デコーダは内部状態を持たない場合と同じようにエラーの取り扱いを開始しなければなりません(例外を送出するかもしれません)。

reset()¶

デコーダを初期状態にリセットします。

StreamWriter とStreamReader クラスは、新しいエンコーディングモジュールを、非常に簡単に実装するのに使用できる、一般的なインターフェイス提供します。実装例はencodings.utf_8 をご覧ください。

7.8.1.4.StreamWriter オブジェクト¶

StreamWriter クラスはCodec のサブクラスで、以下のメソッドを定義しています。全てのストリームライタは、 Python の codec レジストリとの互換性を保つために、これらのメソッドを定義する必要があります。

classcodecs.StreamWriter(stream[,errors])¶

StreamWriter インスタンスのコンストラクタです。

全てのストリームライタはコンストラクタとしてこのインタフェースを提供しなければなりません。キーワード引数を追加しても構いませんが、Python の codec レジストリはここで定義されている引数だけを使います。

stream は、(バイナリで) 書き込み可能なファイル類似のオブジェクトでなくてはなりません。

StreamWriter は、errors キーワード引数を受けて、異なったエラー処理の仕組みを実装しても構いません。定義済みのパラメタを以下に示します:

• 'strict'ValueError (またはそのサブクラス) を送出します。これがデフォルトです。

• 'ignore' 一文字無視して次に進みます。

• 'replace' 適当な代替文字で置き換えます。

• 'xmlcharrefreplace' 適切な XML 文字参照に置き換えます。

• 'backslashreplace' バックスラッシュ付きのエスケープシーケンスで置き換えます。

errors 引数は、同名の属性に代入されます。この属性を変更すると、StreamWriter オブジェクトが生きている間に、異なるエラー処理に変更できます。

errors 引数に許される値の集合はregister_error() で拡張できます。

write(object)¶

object の内容をエンコードしてストリームに書き出します。

writelines(list)¶

文字列からなるリストを連結して、(必要に応じてwrite() を何度も使って) ストリームに書き出します。

reset()¶

状態保持に使われていた codec のバッファを強制的に出力してリセットします。

このメソッドが呼び出された場合、出力先データをきれいな状態にし、わざわざストリーム全体を再スキャンして状態を元に戻さなくても新しくデータを追加できるようにしなければなりません。

ここまでで挙げたメソッドの他にも、StreamWriter では背後にあるストリームの他の全てのメソッドや属性を継承しなければなりません。

7.8.1.5.StreamReader オブジェクト¶

StreamReader クラスはCodec のサブクラスで、以下のメソッドを定義しています。全てのストリームリーダは、 Python の codec レジストリとの互換性を保つために、これらのメソッドを定義する必要があります。

classcodecs.StreamReader(stream[,errors])¶

StreamReader インスタンスのコンストラクタです。

全てのストリームリーダはコンストラクタとしてこのインタフェースを提供しなければなりません。キーワード引数を追加しても構いませんが、Python の codec レジストリはここで定義されている引数だけを使います。

stream は、(バイナリで) 読み出し可能なファイル類似のオブジェクトでなくてはなりません。

StreamReader は、errors キーワード引数を受けて、異なったエラー処理の仕組みを実装しても構いません。定義済みのパラメタを以下に示します:

• 'strict'ValueError (またはそのサブクラス) を送出します。これがデフォルトです。

• 'ignore' 一文字無視して次に進みます。

• 'replace' 適切な置換文字で置換します。

errors 引数は、同名の属性に代入されます。この属性を変更すると、StreamReader オブジェクトが生きている間に、異なるエラー処理に変更できます。

errors 引数に許される値の集合はregister_error() で拡張できます。

read([size[,chars[,firstline]]])¶

ストリームからのデータをデコードし、デコード済のオブジェクトを返します。

chars はストリームから読み込む文字数です。read() はchars 以上の文字を返しませんが、それより少ない文字しか取得できない場合にはchars 以下の文字を返します。

size は、デコードするためにストリームから読み込む、およその最大バイト数を意味します。デコーダはこの値を適切な値に変更できます。デフォルト値 -1 にすると可能な限りたくさんのデータを読み込みます。size の目的は、巨大なファイルの一括デコードを防ぐことにあります。

firstline は、1行目さえ返せばその後の行でデコードエラーがあっても無視して十分だ、ということを示します。

このメソッドは貪欲な読み込み戦略を取るべきです。すなわち、エンコーディング定義と size の値が許す範囲で、できるだけ多くのデータを読むべきだということです。たとえば、ストリーム上にエンコーディングの終端や状態の目印があれば、それも読み込みます。

バージョン 2.4 で変更:chars 引数を追加しました.

バージョン 2.4.2 で変更:firstline 引数を追加しました.

readline([size[,keepends]])¶

入力ストリームから1行読み込み、デコード済みのデータを返します。

size が与えられた場合、ストリームのread() メソッドに size 引数として渡されます。

keepends が偽の場合には行末の改行が削除された行が返ります。

バージョン 2.4 で変更:keepends 引数を追加しました.

readlines([sizehint[,keepends]])¶

入力ストリームから全ての行を読み込み、行のリストとして返します。

keepends が真なら、改行は、codec のデコーダメソッドを使って実装され、リスト要素の中に含まれます。

sizehint が与えられた場合、ストリームのread() メソッドにsize 引数として渡されます。

reset()¶

状態保持に使われた codec のバッファをリセットします。

ストリームの読み位置を再設定してはならないので注意してください。このメソッドはデコードの際にエラーから復帰できるようにするためのものです。

ここまでで挙げたメソッドの他にも、StreamReader では背後にあるストリームの他の全てのメソッドや属性を継承しなければなりません。

次に挙げる2つの基底クラスは、利便性のために含まれています。codec レジストリは、これらを必要としませんが、実際のところ、あると有用なものでしょう。

7.8.1.6.StreamReaderWriter オブジェクト¶

StreamReaderWriter を使って、読み書き両方に使えるストリームをラップできます。

lookup() 関数が返すファクトリ関数を使って、インスタンスを生成するという設計です。

classcodecs.StreamReaderWriter(stream,Reader,Writer,errors)¶

StreamReaderWriter インスタンスを生成します。stream はファイル類似のオブジェクトです。Reader とWriter は、それぞれStreamReader とStreamWriter インタフェースを提供するファクトリ関数かファクトリクラスでなければなりません。エラー処理は、ストリームリーダとライタで定義したものと同じように行われます。

StreamReaderWriter インスタンスは、StreamReader クラスとStreamWriter クラスを合わせたインタフェースを継承します。元になるストリームからは、他のメソッドや属性を継承します。

7.8.1.7.StreamRecoder オブジェクト¶

StreamRecoder はエンコーディングデータの、フロントエンド-バックエンドを観察する機能を提供します。異なるエンコーディング環境を扱うとき、便利な場合があります。

lookup() 関数が返すファクトリ関数を使って、インスタンスを生成するという設計です。

classcodecs.StreamRecoder(stream,encode,decode,Reader,Writer,errors)¶

双方向変換を実装するStreamRecoder インスタンスを生成します。encode とdecode はフロントエンド (read() への入力とwrite() からの出力) を処理し、Reader とWriter はバックエンド (ストリームに対する読み書き) を処理します。

これらのオブジェクトを使って、たとえば、 Latin-1 から UTF-8 、あるいは逆向きの変換を、透過に記録できます。

stream はファイル的オブジェクトでなくてはなりません。

encode とdecode はCodec のインタフェースに忠実でなくてはならず、Reader とWriter は、それぞれStreamReader とStreamWriter のインタフェースを提供するオブジェクトのファクトリ関数かクラスでなくてはなりません。

encode とdecode はフロントエンドの変換に必要で、Reader とWriter はバックエンドの変換に必要です。中間のフォーマットはコデックの組み合わせによって決定されます。たとえば、 Unicode コデックは中間エンコーディングに Unicode を使います。

エラー処理はストリーム・リーダやライタで定義されている方法と同じように行われます。

StreamRecoder インスタンスは、StreamReader とStreamWriter クラスを合わせたインタフェースを定義します。また、元のストリームのメソッドと属性も継承します。

バージョン 2.3 で追加:idna,punycode エンコーディングの追加。

バージョン 2.3 で追加.

バージョン 2.5 で追加.