7.8. コーデック—コーデックレジストリと基本クラス—Pythonドキュメント

7.8。 コーデック —コーデックレジストリと基本クラス

このモジュールは、標準のPythonコーデック（エンコーダーとデコーダー）の基本クラスを定義し、コーデックとエラー処理のルックアッププロセスを管理する内部Pythonコーデックレジストリへのアクセスを提供します。

次の関数を定義します。

codecs.encode(obj[, encoding[, errors]])

encoding に登録されているコーデックを使用して obj をエンコードします。 デフォルトのエンコーディングは'ascii'です。

エラーを指定して、目的のエラー処理スキームを設定できます。 デフォルトのエラーハンドラーは'strict'です。これは、エンコードエラーによってValueError（またはUnicodeEncodeErrorなどのよりコーデック固有のサブクラス）が発生することを意味します。 コーデックエラー処理の詳細については、コーデック基本クラスを参照してください。

バージョン2.4の新機能。

codecs.decode(obj[, encoding[, errors]])

encoding に登録されているコーデックを使用して obj をデコードします。 デフォルトのエンコーディングは'ascii'です。

エラーを指定して、目的のエラー処理スキームを設定できます。 デフォルトのエラーハンドラは'strict'です。これは、デコードエラーによってValueError（またはUnicodeDecodeErrorなどのよりコーデック固有のサブクラス）が発生することを意味します。 コーデックエラー処理の詳細については、コーデック基本クラスを参照してください。

バージョン2.4の新機能。

codecs.register(search_function)

コーデック検索機能を登録します。 検索関数は、1つの引数、すべて小文字のエンコード名を取り、次の属性を持つCodecInfoオブジェクトを返すことが期待されています。

• nameエンコーディングの名前。

• encodeステートレスエンコーディング機能。

• decodeステートレスデコード機能。

• incrementalencoderインクリメンタルエンコーダクラスまたはファクトリ関数。

• incrementaldecoderインクリメンタルデコーダークラスまたはファクトリ関数。

• streamwriterストリームライタークラスまたはファクトリ関数。

• streamreaderストリームリーダークラスまたはファクトリ関数。

さまざまな関数またはクラスは、次の引数を取ります。

encode および decode ：これらは、 encode（） / decode（）メソッドと同じインターフェイスを持つ関数またはメソッドである必要があります。コーデックインスタンス（コーデックインターフェイスを参照）。 関数/メソッドはステートレスモードで動作することが期待されています。

incrementalencoder および incrementaldecoder ：これらは、次のインターフェイスを提供するファクトリ関数である必要があります。

factory(errors='strict')

ファクトリ関数は、基本クラス IncrementalEncoder および IncrementalDecoder によってそれぞれ定義されたインターフェイスを提供するオブジェクトを返す必要があります。 インクリメンタルコーデックは状態を維持できます。

streamreader および streamwriter ：これらは、次のインターフェイスを提供するファクトリ関数である必要があります。

factory(stream, errors='strict')

ファクトリ関数は、基本クラス StreamReader および StreamWriter によってそれぞれ定義されたインターフェイスを提供するオブジェクトを返す必要があります。 ストリームコーデックは状態を維持できます。

エラーの可能な値は次のとおりです。

• 'strict'：エンコードエラーの場合に例外を発生させます

• 'replace'：不正な形式のデータを'?'や'\ufffd'などの適切な置換マーカーに置き換えます

• 'ignore'：不正な形式のデータを無視し、通知なしに続行します

• 'xmlcharrefreplace'：適切なXML文字参照に置き換えます（エンコードのみ）

• 'backslashreplace'：バックスラッシュエスケープシーケンスに置き換えます（エンコードのみ）

register_error（）を介して定義されたその他のエラー処理名。

検索関数が特定のエンコーディングを見つけられない場合は、Noneを返す必要があります。

codecs.lookup(encoding)

Pythonコーデックレジストリでコーデック情報を検索し、上記で定義したCodecInfoオブジェクトを返します。

エンコーディングは、最初にレジストリのキャッシュで検索されます。 見つからない場合は、登録されている検索機能のリストがスキャンされます。 CodecInfoオブジェクトが見つからない場合、LookupErrorが発生します。 それ以外の場合、CodecInfoオブジェクトはキャッシュに格納され、呼び出し元に返されます。

さまざまなコーデックへのアクセスを簡素化するために、モジュールはコーデックルックアップに lookup（）を使用する次の追加関数を提供します。

codecs.getencoder(encoding)

指定されたエンコーディングのコーデックを検索し、そのエンコーダ関数を返します。

エンコーディングが見つからない場合にLookupErrorを発生させます。

codecs.getdecoder(encoding)

指定されたエンコーディングのコーデックを検索し、そのデコーダー関数を返します。

エンコーディングが見つからない場合にLookupErrorを発生させます。

codecs.getincrementalencoder(encoding)

指定されたエンコーディングのコーデックを検索し、そのインクリメンタルエンコーダクラスまたはファクトリ関数を返します。

エンコーディングが見つからない場合、またはコーデックがインクリメンタルエンコーダをサポートしていない場合に、LookupErrorを発生させます。

バージョン2.5の新機能。

codecs.getincrementaldecoder(encoding)

指定されたエンコーディングのコーデックを検索し、そのインクリメンタルデコーダークラスまたはファクトリ関数を返します。

エンコーディングが見つからない場合、またはコーデックがインクリメンタルデコーダーをサポートしていない場合に、LookupErrorを発生させます。

バージョン2.5の新機能。

codecs.getreader(encoding)

指定されたエンコーディングのコーデックを検索し、そのStreamReaderクラスまたはファクトリ関数を返します。

エンコーディングが見つからない場合にLookupErrorを発生させます。

codecs.getwriter(encoding)

指定されたエンコーディングのコーデックを検索し、そのStreamWriterクラスまたはファクトリ関数を返します。

エンコーディングが見つからない場合にLookupErrorを発生させます。

codecs.register_error(name, error_handler)

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

エンコードの場合、 error_handler は、エラーの場所に関する情報を含むUnicodeEncodeErrorインスタンスで呼び出されます。 エラーハンドラは、この例外または別の例外を発生させるか、入力のエンコードできない部分とエンコードを続行する位置を置き換えるタプルを返す必要があります。 エンコーダーは置換をエンコードし、指定された位置で元の入力のエンコードを続行します。 負の位置の値は、入力文字列の末尾を基準として扱われます。 結果の位置が範囲外の場合、IndexErrorが発生します。

UnicodeDecodeErrorまたはUnicodeTranslateErrorがハンドラーに渡され、エラーハンドラーからの置換が直接出力に入れられることを除いて、デコードと変換は同様に機能します。

codecs.lookup_error(name)

以前に name という名前で登録されたエラーハンドラーを返します。

ハンドラーが見つからない場合にLookupErrorを発生させます。

codecs.strict_errors(exception)

strictエラー処理を実装します。エンコードまたはデコードエラーが発生するたびに、UnicodeErrorが発生します。

codecs.replace_errors(exception)

replaceエラー処理を実装します。不正な形式のデータは、バイト文字列の'?'やUnicode文字列の'\ufffd'などの適切な置換文字に置き換えられます。

codecs.ignore_errors(exception)

ignoreエラー処理を実装します。不正な形式のデータは無視され、エンコードまたはデコードは通知なしに続行されます。

codecs.xmlcharrefreplace_errors(exception)

xmlcharrefreplaceエラー処理を実装します（エンコードのみ）。エンコードできない文字は、適切なXML文字参照に置き換えられます。

codecs.backslashreplace_errors(exception)

backslashreplaceエラー処理を実装します（エンコードのみ）。エンコードできない文字は、バックスラッシュのエスケープシーケンスに置き換えられます。

エンコードされたファイルまたはストリームの操作を簡素化するために、モジュールは次のユーティリティ関数も定義します。

codecs.open(filename, mode[, encoding[, errors[, buffering]]])

指定されたモードを使用してエンコードされたファイルを開き、透過的なエンコード/デコードを提供するラップされたバージョンを返します。 デフォルトのファイルモードは'r'で、ファイルを読み取りモードで開くことを意味します。

ノート

ラップされたバージョンは、コーデックで定義されたオブジェクト形式のみを受け入れます。 ほとんどの組み込みコーデック用のUnicodeオブジェクト。 出力もコーデックに依存し、通常はUnicodeにもなります。

ノート

バイナリモードが指定されていない場合でも、ファイルは常にバイナリモードで開かれます。 これは、8ビット値を使用したエンコードによるデータ損失を回避するために行われます。 これは、読み取りと書き込みで'\n'の自動変換が行われないことを意味します。

encoding は、ファイルに使用されるエンコーディングを指定します。

エラーは、エラー処理を定義するために指定される場合があります。 デフォルトは'strict'で、エンコードエラーが発生した場合にValueErrorが発生します。

バッファリングは、組み込みの open（）関数と同じ意味です。 デフォルトでは、行バッファリングされています。

codecs.EncodedFile(file, input[, output[, errors]])

透過的なエンコーディング変換を提供するラップされたバージョンのファイルを返します。

ラップされたファイルに書き込まれた文字列は、指定された入力エンコーディングに従って解釈され、出力エンコーディングを使用して文字列として元のファイルに書き込まれます。 中間エンコーディングは通常Unicodeですが、指定されたコーデックによって異なります。

output が指定されていない場合、デフォルトで input になります。

エラーは、エラー処理を定義するために指定される場合があります。 デフォルトは'strict'で、エンコードエラーが発生した場合にValueErrorが発生します。

codecs.iterencode(iterable, encoding[, errors])

インクリメンタルエンコーダを使用して、 iterable によって提供される入力を繰り返しエンコードします。 この関数はジェネレーターです。 エラー（およびその他のキーワード引数）は、インクリメンタルエンコーダに渡されます。

バージョン2.5の新機能。

codecs.iterdecode(iterable, encoding[, errors])

インクリメンタルデコーダーを使用して、 iterable によって提供される入力を繰り返しデコードします。 この関数はジェネレーターです。 エラー（およびその他のキーワード引数）は、インクリメンタルデコーダーに渡されます。

バージョン2.5の新機能。

このモジュールは、プラットフォームに依存するファイルの読み取りと書き込みに役立つ次の定数も提供します。

codecs.BOM

codecs.BOM_BE
codecs.BOM_LE
codecs.BOM_UTF8
codecs.BOM_UTF16
codecs.BOM_UTF16_BE
codecs.BOM_UTF16_LE
codecs.BOM_UTF32
codecs.BOM_UTF32_BE
codecs.BOM_UTF32_LE

これらの定数は、UTF-16およびUTF-32データストリームで使用されるUnicodeバイト順序マーク（BOM）のさまざまなエンコーディングを定義して、ストリームまたはファイル、およびUTF-8でUnicode署名として使用されるバイト順序を示します。 BOM_UTF16 は、プラットフォームのネイティブバイト順序に応じて BOM_UTF16_BE または BOM_UTF16_LE のいずれかであり、 BOM は BOM_UTF16 のエイリアスです。 、 BOM_UTF16_LE の場合は BOM_LE 、 BOM_UTF16_BE の場合は BOM_BE 。 その他は、UTF-8およびUTF-32エンコーディングのBOMを表します。

7.8.1。 コーデック基本クラス

codecs モジュールは、インターフェイスを定義する基本クラスのセットを定義し、Pythonで使用する独自のコーデックを簡単に作成するためにも使用できます。

各コーデックは、Pythonでコーデックとして使用できるように、ステートレスエンコーダー、ステートレスデコーダー、ストリームリーダー、ストリームライターの4つのインターフェイスを定義する必要があります。 ストリームリーダーとライターは通常、ステートレスエンコーダー/デコーダーを再利用してファイルプロトコルを実装します。

Codecクラスは、ステートレスエンコーダー/デコーダーのインターフェイスを定義します。

エラー処理を簡素化および標準化するために、 encode（）および decode（）メソッドは、 errors 文字列引数を提供することにより、異なるエラー処理スキームを実装できます。 次の文字列値は、すべての標準Pythonコーデックによって定義および実装されています。

価値	意味
'strict'	UnicodeError（またはサブクラス）を発生させます。 これがデフォルトです。
'ignore'	キャラクターを無視して、次のキャラクターに進みます。
'replace'	適切な置換文字に置き換えます。 Pythonは、デコードおよび「？」の組み込みUnicodeコーデックに公式のU + FFFD REPLACEMENTCHARACTERを使用します。 エンコーディングについて。
'xmlcharrefreplace'	適切なXML文字参照に置き換えます（エンコードのみ）。
'backslashreplace'	バックスラッシュされたエスケープシーケンスに置き換えます（エンコードのみ）。

許可される値のセットは、 register_error（）を介して拡張できます。

7.8.1.1。 コーデックオブジェクト

Codecクラスは、ステートレスエンコーダーとデコーダーの関数インターフェイスも定義するこれらのメソッドを定義します。

Codec.encode(input[, errors])

オブジェクト input をエンコードし、タプル（出力オブジェクト、消費された長さ）を返します。 コーデックはUnicodeでの使用に制限されていませんが、Unicodeコンテキストでは、エンコーディングは特定の文字セットエンコーディング（cp1252またはiso-8859-1など）を使用してUnicodeオブジェクトをプレーン文字列に変換します。

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

このメソッドは、Codecインスタンスに状態を格納しない場合があります。 エンコーディングを効率的にするために状態を維持する必要があるコーデックには、 StreamWriter を使用します。

この状況では、エンコーダーは長さゼロの入力を処理し、出力オブジェクトタイプの空のオブジェクトを返すことができる必要があります。

Codec.decode(input[, errors])

オブジェクト input をデコードし、タプル（出力オブジェクト、消費された長さ）を返します。 Unicodeコンテキストでは、デコードは、特定の文字セットエンコーディングを使用してエンコードされたプレーン文字列をUnicodeオブジェクトに変換します。

input は、bf_getreadbufバッファスロットを提供するオブジェクトである必要があります。 Python文字列、バッファオブジェクト、メモリマップファイルは、このスロットを提供するオブジェクトの例です。

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

このメソッドは、Codecインスタンスに状態を格納しない場合があります。 デコードを効率的にするために状態を保持する必要があるコーデックには、 StreamReader を使用します。

この状況では、デコーダーは長さゼロの入力を処理し、出力オブジェクトタイプの空のオブジェクトを返すことができる必要があります。

InitialEncoder クラスと IncrementalDecoder クラスは、インクリメンタルエンコーディングとデコーディングの基本的なインターフェイスを提供します。 入力のエンコード/デコードは、ステートレスエンコーダー/デコーダー関数の1回の呼び出しではなく、インクリメンタルエンコーダーの encode（） / decode（）メソッドの複数回の呼び出しで行われます。 /デコーダ。 インクリメンタルエンコーダー/デコーダーは、メソッド呼び出し中にエンコード/デコードプロセスを追跡します。

encode（） / decode（）メソッドへの呼び出しの結合された出力は、すべての単一入力が1つに結合された場合と同じであり、この入力はでエンコード/デコードされました。ステートレスエンコーダ/デコーダ。

7.8.1.2。 IncrementalEncoderオブジェクト

バージョン2.5の新機能。

IncrementalEncoder クラスは、複数のステップで入力をエンコードするために使用されます。 これは、Pythonコーデックレジストリと互換性を持たせるためにすべてのインクリメンタルエンコーダが定義する必要がある次のメソッドを定義します。

class codecs.IncrementalEncoder([errors])

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

すべてのインクリメンタルエンコーダは、このコンストラクタインターフェイスを提供する必要があります。 キーワード引数は自由に追加できますが、Pythonコーデックレジストリで使用されるのはここで定義されているものだけです。

IncrementalEncoder は、 errors キーワード引数を提供することにより、さまざまなエラー処理スキームを実装できます。 これらのパラメーターは事前定義されています。

• 'strict' ValueError（またはサブクラス）を上げます。 これがデフォルトです。

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

• 'replace'適切な置換文字に置き換えます

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

• 'backslashreplace'バックスラッシュされたエスケープシーケンスに置き換えます。

errors 引数は、同じ名前の属性に割り当てられます。 この属性を割り当てると、 IncrementalEncoder オブジェクトの存続期間中にさまざまなエラー処理戦略を切り替えることができます。

errors 引数に許可される値のセットは、 register_error（）で拡張できます。

encode(object[, final])

object をエンコードし（エンコーダーの現在の状態を考慮に入れて）、結果のエンコードされたオブジェクトを返します。 これが encode（） final の最後の呼び出しである場合、trueである必要があります（デフォルトはfalseです）。

reset()

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

7.8.1.3。 IncrementalDecoderオブジェクト

IncrementalDecoder クラスは、複数のステップで入力をデコードするために使用されます。 これは、Pythonコーデックレジストリと互換性を持たせるためにすべてのインクリメンタルデコーダーが定義する必要がある次のメソッドを定義します。

class codecs.IncrementalDecoder([errors])

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

すべてのインクリメンタルデコーダーは、このコンストラクターインターフェイスを提供する必要があります。 キーワード引数は自由に追加できますが、Pythonコーデックレジストリで使用されるのはここで定義されているものだけです。

IncrementalDecoder は、 errors キーワード引数を提供することにより、さまざまなエラー処理スキームを実装できます。 これらのパラメーターは事前定義されています。

• 'strict' ValueError（またはサブクラス）を上げます。 これがデフォルトです。

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

• 'replace'適切な置換文字に置き換えます。

errors 引数は、同じ名前の属性に割り当てられます。 この属性を割り当てると、 IncrementalDecoder オブジェクトの存続期間中にさまざまなエラー処理戦略を切り替えることができます。

errors 引数に許可される値のセットは、 register_error（）で拡張できます。

decode(object[, final])

オブジェクトをデコードし（デコーダーの現在の状態を考慮に入れて）、結果のデコードされたオブジェクトを返します。 これが decode（） final の最後の呼び出しである場合、trueである必要があります（デフォルトはfalseです）。 final がtrueの場合、デコーダーは入力を完全にデコードし、すべてのバッファーをフラッシュする必要があります。 これが不可能な場合（例： 入力の最後のバイトシーケンスが不完全なため）ステートレスの場合と同じようにエラー処理を開始する必要があります（例外が発生する可能性があります）。

reset()

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

StreamWriter および StreamReader クラスは、新しいエンコーディングサブモジュールを非常に簡単に実装するために使用できる汎用の作業インターフェイスを提供します。 これがどのように行われるかの例については、encodings.utf_8を参照してください。

7.8.1.4。 StreamWriterオブジェクト

StreamWriter クラスはCodecのサブクラスであり、Pythonコーデックレジストリと互換性を持たせるためにすべてのストリームライターが定義する必要がある次のメソッドを定義します。

class codecs.StreamWriter(stream[, errors])

StreamWriter インスタンスのコンストラクター。

すべてのストリームライターは、このコンストラクターインターフェイスを提供する必要があります。 キーワード引数は自由に追加できますが、Pythonコーデックレジストリで使用されるのはここで定義されているものだけです。

stream は、バイナリデータを書き込むために開いているファイルのようなオブジェクトである必要があります。

StreamWriter は、 errors キーワード引数を提供することにより、さまざまなエラー処理スキームを実装できます。 これらのパラメーターは事前定義されています。

• 'strict' ValueError（またはサブクラス）を上げます。 これがデフォルトです。

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

• 'replace'適切な置換文字に置き換えます

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

• 'backslashreplace'バックスラッシュされたエスケープシーケンスに置き換えます。

errors 引数は、同じ名前の属性に割り当てられます。 この属性を割り当てると、 StreamWriter オブジェクトの存続期間中にさまざまなエラー処理戦略を切り替えることができます。

errors 引数に許可される値のセットは、 register_error（）で拡張できます。

write(object)

エンコードされたオブジェクトのコンテンツをストリームに書き込みます。

writelines(list)

文字列の連結リストをストリームに書き込みます（おそらく write（）メソッドを再利用することによって）。

reset()

状態を維持するために使用されるコーデックバッファをフラッシュしてリセットします。

このメソッドを呼び出すと、出力のデータがクリーンな状態になり、状態を回復するためにストリーム全体を再スキャンしなくても、新しい新しいデータを追加できるようになります。

上記のメソッドに加えて、 StreamWriter は、基になるストリームから他のすべてのメソッドと属性も継承する必要があります。

7.8.1.5。 StreamReaderオブジェクト

StreamReader クラスはCodecのサブクラスであり、Pythonコーデックレジストリと互換性を持たせるためにすべてのストリームリーダーが定義する必要がある次のメソッドを定義します。

class codecs.StreamReader(stream[, errors])

StreamReader インスタンスのコンストラクター。

すべてのストリームリーダーは、このコンストラクターインターフェイスを提供する必要があります。 キーワード引数は自由に追加できますが、Pythonコーデックレジストリで使用されるのはここで定義されているものだけです。

stream は、（バイナリ）データを読み取るために開いているファイルのようなオブジェクトである必要があります。

StreamReader は、 errors キーワード引数を提供することにより、さまざまなエラー処理スキームを実装できます。 これらのパラメーターは次のように定義されています。

• 'strict' ValueError（またはサブクラス）を上げます。 これがデフォルトです。

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

• 'replace'適切な置換文字に置き換えます。

errors 引数は、同じ名前の属性に割り当てられます。 この属性を割り当てると、 StreamReader オブジェクトの存続期間中にさまざまなエラー処理戦略を切り替えることができます。

errors 引数に許可される値のセットは、 register_error（）で拡張できます。

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

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

chars は、ストリームから読み取る文字数を示します。 read（）は、 chars 文字を超えることはありませんが、使用可能な文字が十分でない場合は、返される文字が少なくなる可能性があります。

size は、デコードの目的でストリームから読み取るおおよその最大バイト数を示します。 デコーダーは、この設定を必要に応じて変更できます。 デフォルト値-1は、可能な限り読み取りとデコードを行うことを示します。 size は、巨大なファイルを1つのステップでデコードする必要がないようにすることを目的としています。

firstline は、後の行でデコードエラーが発生した場合、最初の行のみを返すだけで十分であることを示します。

このメソッドは、貪欲な読み取り戦略を使用する必要があります。つまり、エンコーディングの定義と指定されたサイズ内で許可されている限り多くのデータを読み取る必要があります。 オプションのエンコーディング終了または状態マーカーがストリームで使用可能な場合は、これらも読み取る必要があります。

バージョン2.4で変更： chars 引数が追加されました。

バージョン2.4.2で変更： firstline 引数が追加されました。

readline([size[, keepends]])

入力ストリームから1行を読み取り、デコードされたデータを返します。

size は、指定されている場合、サイズ引数としてストリームの read（）メソッドに渡されます。

keepends がfalseの場合、返される行から行末が削除されます。

バージョン2.4で変更： keepends 引数が追加されました。

readlines([sizehint[, keepends]])

入力ストリームで使用可能なすべての行を読み取り、それらを行のリストとして返します。

行末はコーデックのデコーダ方式を使用して実装され、 keepends がtrueの場合にリストエントリに含まれます。

sizehint は、指定されている場合、 size 引数としてストリームの read（）メソッドに渡されます。

reset()

状態を維持するために使用されるコーデックバッファをリセットします。

ストリームの再配置は行わないでください。 この方法は、主にデコードエラーから回復できるようにすることを目的としています。

上記のメソッドに加えて、 StreamReader は、基になるストリームから他のすべてのメソッドと属性も継承する必要があります。

次の2つの基本クラスは、便宜上含まれています。 これらはコーデックレジストリでは必要ありませんが、実際には役立つ場合があります。

7.8.1.6。 StreamReaderWriterオブジェクト

StreamReaderWriter を使用すると、読み取りモードと書き込みモードの両方で機能するストリームをラップできます。

lookup（）関数によって返されるファクトリ関数を使用してインスタンスを構築できるように設計されています。

class codecs.StreamReaderWriter(stream, Reader, Writer, errors)

StreamReaderWriter インスタンスを作成します。 stream はファイルのようなオブジェクトである必要があります。 Reader および Writer は、 StreamReader および StreamWriter インターフェイスを提供するファクトリ関数またはクラスである必要があります。 エラー処理は、ストリームのリーダーとライターで定義されているのと同じ方法で行われます。

StreamReaderWriter インスタンスは、 StreamReader クラスと StreamWriter クラスの組み合わせインターフェースを定義します。 それらは、基礎となるストリームから他のすべてのメソッドと属性を継承します。

7.8.1.7。 StreamRecoderオブジェクト

StreamRecoder は、エンコードデータのフロントエンド-バックエンドビューを提供します。これは、さまざまなエンコード環境を処理するときに役立つ場合があります。

lookup（）関数によって返されるファクトリ関数を使用してインスタンスを構築できるように設計されています。

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors)

双方向変換を実装する StreamRecoder インスタンスを作成します。 encode および decode はフロントエンドで機能します（read()への入力とwrite()）、 Reader および Writer はバックエンド（ストリームの読み取りと書き込み）で動作します。

これらのオブジェクトを使用して、たとえばから透過的な直接再コーディングを行うことができます。 Latin-1からUTF-8およびその逆。

stream はファイルのようなオブジェクトである必要があります。

エンコード、デコードはCodecインターフェースに準拠する必要があります。 Reader 、 Writer は、それぞれ StreamReader および StreamWriter インターフェイスのオブジェクトを提供するファクトリ関数またはクラスである必要があります。

フロントエンド変換には encode と decode が必要であり、バックエンド変換には Reader と Writer が必要です。 使用される中間フォーマットは、2セットのコーデックによって決定されます。 Unicodeコーデックは、中間エンコーディングとしてUnicodeを使用します。

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

StreamRecoder インスタンスは、 StreamReader クラスと StreamWriter クラスの組み合わせインターフェースを定義します。 それらは、基礎となるストリームから他のすべてのメソッドと属性を継承します。

7.8.2。 エンコーディングとUnicode

Unicode文字列は、コードポイントのシーケンスとして内部的に格納されます（正確には Py_UNICODE 配列として）。 Pythonのコンパイル方法に応じて（--enable-unicode=ucs2または--enable-unicode=ucs4を介して、前者がデフォルトです） Py_UNICODE は16ビットまたは32ビットのデータ型です。 。 UnicodeオブジェクトがCPUとメモリの外部で使用されると、CPUのエンディアンと、これらの配列がバイトとしてどのように格納されるかが問題になります。 Unicodeオブジェクトをバイトシーケンスに変換することをエンコードと呼び、バイトシーケンスからUnicodeオブジェクトを再作成することをデコードと呼びます。 この変換を実行する方法にはさまざまな方法があります（これらの方法はエンコーディングとも呼ばれます）。 最も簡単な方法は、コードポイント0〜255をバイト0x0〜0xffにマップすることです。 つまり、U+00FFより上のコードポイントを含むUnicodeオブジェクトは、このメソッド（'latin-1'または'iso-8859-1'と呼ばれます）ではエンコードできません。 unicode.encode()は、UnicodeEncodeError: 'latin-1' codec can't encode character u'\u1234' in position 3: ordinal not in range(256)のようなUnicodeEncodeErrorを発生させます。

すべてのユニコードコードポイントの異なるサブセットを選択するエンコーディングの別のグループ（いわゆるcharmapエンコーディング）と、これらのコードポイントがバイト0x0 – 0xffにマップされる方法があります。 これがどのように行われるかを確認するには、たとえば encodings/cp1252.py（これは主にWindowsで使用されるエンコーディングです）。 どの文字がどのバイト値にマップされているかを示す256文字の文字列定数があります。

これらのエンコーディングはすべて、Unicodeで定義された1114112コードポイントのうち256個しかエンコードできません。 各Unicodeコードポイントを格納できる簡単で簡単な方法は、各コードポイントを4つの連続したバイトとして格納することです。 2つの可能性があります。バイトをビッグエンディアンまたはリトルエンディアンの順序で格納します。 これらの2つのエンコーディングは、それぞれUTF-32-BEおよびUTF-32-LEと呼ばれます。 彼らの不利な点は、例えば リトルエンディアンのマシンでUTF-32-BEを使用する場合は、エンコードとデコードで常にバイトを交換する必要があります。 UTF-32は、この問題を回避します。バイトは常に自然なエンディアンになります。 ただし、これらのバイトが異なるエンディアンのCPUによって読み取られる場合は、バイトを交換する必要があります。 UTF-16またはUTF-32バイトシーケンスのエンディアンを検出できるようにするために、いわゆるBOM（「バイトオーダーマーク」）があります。 これはUnicode文字U+FEFFです。 この文字は、すべてのUTF-16またはUTF-32バイトシーケンスの前に付けることができます。 この文字のバイトスワップバージョン（0xFFFE）は、Unicodeテキストに表示されない可能性のある不正な文字です。 したがって、UTF-16またはUTF-32バイトシーケンスの最初の文字がU+FFFEであるように見える場合は、デコード時にバイトを交換する必要があります。 残念ながら、文字U+FEFFには、ZERO WIDTH NO-BREAK SPACEとしての2番目の目的がありました。幅がなく、単語を分割できない文字です。 それは例えばすることができます 合字アルゴリズムにヒントを与えるために使用されます。 U+FEFFをZERO WIDTH NO-BREAK SPACEとして使用するUnicode4.0では、非推奨になりました（U+2060（WORD JOINER）がこの役割を引き受けます）。 それでも、Unicodeソフトウェアは両方の役割でU+FEFFを処理できる必要があります。BOMとして、エンコードされたバイトのストレージレイアウトを決定するデバイスであり、バイトシーケンスがUnicode文字列にデコードされると消えます。 ZERO WIDTH NO-BREAK SPACEとして、他の文字と同じようにデコードされる通常の文字です。

Unicode文字の全範囲をエンコードできる別のエンコードがあります：UTF-8。 UTF-8は8ビットエンコーディングです。つまり、UTF-8のバイト順序に問題はありません。 UTF-8バイトシーケンスの各バイトは、マーカービット（最上位ビット）とペイロードビットの2つの部分で構成されます。 マーカービットは、0〜4個の1ビットとそれに続く0ビットのシーケンスです。 Unicode文字は次のようにエンコードされます（xはペイロードビットであり、連結するとUnicode文字になります）。

範囲	エンコーディング
U-00000000…U-0000007F	0xxxxxxx
U-00000080…U-000007FF	110xxxxx 10xxxxxx
U-00000800…U-0000FFFF	1110xxxx 10xxxxxx 10xxxxxx
U-00010000…U-0010FFFF	11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

Unicode文字の最下位ビットは、右端のxビットです。

UTF-8は8ビットエンコーディングであるため、BOMは不要であり、デコードされたUnicode文字列のU+FEFF文字は（最初の文字であっても）ZERO WIDTH NO-BREAK SPACEとして扱われます。

外部情報がないと、Unicode文字列のエンコードに使用されたエンコードを確実に判別することはできません。 各charmapエンコーディングは、任意のランダムなバイトシーケンスをデコードできます。 ただし、UTF-8のバイトシーケンスは任意のバイトシーケンスを許可しない構造を持っているため、UTF-8ではそれは不可能です。 UTF-8エンコーディングを検出できる信頼性を高めるために、Microsoftはメモ帳プログラム用にUTF-8のバリアント（Python2.5が"utf-8-sig"を呼び出す）を発明しました。Unicode文字が書き込まれる前にファイルには、UTF-8でエンコードされたBOM（バイトシーケンスとして次のようになります：0xef、0xbb、0xbf）が書き込まれます。 チャーマップでエンコードされたファイルがこれらのバイト値で始まる可能性はかなり低いため（たとえば、 にマップ

分音記号付きラテン語の小さな文字I

右向きのダブルアングル見積もりマーク

逆疑問符

iso-8859-1）では、これにより、utf-8-sigエンコーディングがバイトシーケンスから正しく推測できる可能性が高くなります。 したがって、ここでは、BOMを使用して、バイトシーケンスの生成に使用されるバイト順序を決定することはできませんが、エンコーディングを推測するのに役立つ署名として使用されます。 utf-8-sigコーデックをエンコードすると、ファイルの最初の3バイトとして0xef、0xbb、0xbfが書き込まれます。 デコード時に、utf-8-sigは、ファイルの最初の3バイトとして表示される場合、それらの3バイトをスキップします。 UTF-8では、BOMの使用は推奨されておらず、通常は避ける必要があります。

7.8.3。 標準エンコーディング

Pythonには、C関数として実装されているか、マッピングテーブルとして辞書が実装されている、多数のコーデックが組み込まれています。 次の表に、名前別のコーデック、いくつかの一般的なエイリアス、およびエンコーディングが使用される可能性のある言語を示します。 エイリアスのリストも言語のリストも網羅的であることを意図していません。 大文字と小文字のみが異なる、またはアンダースコアの代わりにハイフンを使用する代替スペルも有効なエイリアスであることに注意してください。 したがって、例えば 'utf-8'は、'utf_8'コーデックの有効なエイリアスです。

文字セットの多くは同じ言語をサポートしています。 それらは個々のキャラクターによって異なります（例： EURO SIGNがサポートされているかどうか）、およびコード位置への文字の割り当て。 特にヨーロッパ言語の場合、通常、次のバリアントが存在します。

• ISO8859コードセット
• Microsoft Windowsコードページ。通常は8859コードセットから派生しますが、制御文字を追加のグラフィック文字に置き換えます。
• IBMEBCDICコードページ
• ASCII互換のIBMPCコードページ

コーデック	エイリアス	言語
アスキー	646、us-ascii	英語
big5	big5-tw、csbig5	繁体字中国語
big5hkscs	big5-hkscs、hkscs	繁体字中国語
cp037	IBM037、IBM039	英語
cp424	EBCDIC-CP-HE、IBM424	ヘブライ語
cp437	437、IBM437	英語
cp500	EBCDIC-CP-BE、EBCDIC-CP-CH、IBM500	西ヨーロッパ
cp720		アラビア語
cp737		ギリシャ語
cp775	IBM775	バルト語
cp850	850、IBM850	西ヨーロッパ
cp852	852、IBM852	中央および東ヨーロッパ
cp855	855、IBM855	ブルガリア語、ベラルーシ語、マケドニア語、ロシア語、セルビア語
cp856		ヘブライ語
cp857	857、IBM857	トルコ語
cp858	858、IBM858	西ヨーロッパ
cp860	860、IBM860	ポルトガル語
cp861	861、CP-IS、IBM861	アイスランド語
cp862	862、IBM862	ヘブライ語
cp863	863、IBM863	カナダ人
cp864	IBM864	アラビア語
cp865	865、IBM865	デンマーク語、ノルウェー語
cp866	866、IBM866	ロシア
cp869	869、CP-GR、IBM869	ギリシャ語
cp874		タイ語
cp875		ギリシャ語
cp932	932、ms932、mskanji、ms-kanji	日本
cp949	949、ms949、uhc	韓国語
cp950	950、ms950	繁体字中国語
cp1006		ウルドゥー語
cp1026	ibm1026	トルコ語
cp1140	ibm1140	西ヨーロッパ
cp1250	Windows-1250	中央および東ヨーロッパ
cp1251	窓-1251	ブルガリア語、ベラルーシ語、マケドニア語、ロシア語、セルビア語
cp1252	windows-1252	西ヨーロッパ
cp1253	windows-1253	ギリシャ語
cp1254	windows-1254	トルコ語
cp1255	windows-1255	ヘブライ語
cp1256	windows-1256	アラビア語
cp1257	windows-1257	バルト語
cp1258	windows-1258	ベトナム語
euc_jp	eucjp、ujis、u-jis	日本
euc_jis_2004	jisx0213、eucjis2004	日本
euc_jisx0213	eucjisx0213	日本
euc_kr	euckr、韓国語、ksc5601、ks_c-5601、ks_c-5601-1987、ksx1001、ks_x-1001	韓国語
gb2312	中国語、csiso58gb231280、euc- cn、euccn、eucgb2312-cn、gb2312-1980、gb2312-80、iso-ir-58	簡体字中国語
gbk	936、cp936、ms936	統一された中国語
gb18030	gb18030-2000	統一された中国語
hz	hzgb、hz-gb、hz-gb-2312	簡体字中国語
iso2022_jp	csiso2022jp、iso2022jp、iso-2022-jp	日本
iso2022_jp_1	iso2022jp-1、iso-2022-jp-1	日本
iso2022_jp_2	iso2022jp-2、iso-2022-jp-2	日本語、韓国語、簡体字中国語、西ヨーロッパ、ギリシャ語
iso2022_jp_2004	iso2022jp-2004、iso-2022-jp-2004	日本
iso2022_jp_3	iso2022jp-3、iso-2022-jp-3	日本
iso2022_jp_ext	iso2022jp-ext、iso-2022-jp-ext	日本
iso2022_kr	csiso2022kr、iso2022kr、iso-2022-kr	韓国語
latin_1	iso-8859-1、iso8859-1、8859、cp819、latin、latin1、L1	西ヨーロッパ
iso8859_2	iso-8859-2、latin2、L2	中央および東ヨーロッパ
iso8859_3	iso-8859-3、latin3、L3	エスペラント語、マルタ語
iso8859_4	iso-8859-4、latin4、L4	バルト語
iso8859_5	iso-8859-5、キリル文字	ブルガリア語、ベラルーシ語、マケドニア語、ロシア語、セルビア語
iso8859_6	iso-8859-6、アラビア語	アラビア語
iso8859_7	iso-8859-7、ギリシャ語、ギリシャ語8	ギリシャ語
iso8859_8	iso-8859-8、ヘブライ語	ヘブライ語
iso8859_9	iso-8859-9、latin5、L5	トルコ語
iso8859_10	iso-8859-10、latin6、L6	北欧言語
iso8859_11	iso-8859-11、タイ	タイ語
iso8859_13	iso-8859-13、latin7、L7	バルト語
iso8859_14	iso-8859-14、latin8、L8	ケルト語
iso8859_15	iso-8859-15、latin9、L9	西ヨーロッパ
iso8859_16	iso-8859-16、latin10、L10	南東ヨーロッパ
ジョハブ	cp1361、ms1361	韓国語
koi8_r		ロシア
koi8_u		ウクライナ語
mac_cyrillic	maccyrillic	ブルガリア語、ベラルーシ語、マケドニア語、ロシア語、セルビア語
mac_greek	マックグリーク	ギリシャ語
mac_iceland	maciceland	アイスランド語
mac_latin2	maclatin2、maccentraleurope	中央および東ヨーロッパ
mac_roman	マクロマン	西ヨーロッパ
mac_turkish	macturkish	トルコ語
ptcp154	csptcp154、pt154、cp154、キリル文字-アジア	カザフ
shift_jis	csshiftjis、shiftjis、sjis、s_jis	日本
shift_jis_2004	shiftjis2004、sjis_2004、sjis2004	日本
shift_jisx0213	shiftjisx0213、sjisx0213、s_jisx0213	日本
utf_32	U32、utf32	すべての言語
utf_32_be	UTF-32BE	すべての言語
utf_32_le	UTF-32LE	すべての言語
utf_16	U16、utf16	すべての言語
utf_16_be	UTF-16BE	すべての言語（BMPのみ）
utf_16_le	UTF-16LE	すべての言語（BMPのみ）
utf_7	U7、unicode-1-1-utf-7	すべての言語
utf_8	U8、UTF、utf8	すべての言語
utf_8_sig		すべての言語

7.8.4。 Python固有のエンコーディング

事前定義されたコーデックの多くはPythonに固有であるため、それらのコーデック名はPython以外では意味がありません。 これらは、予想される入力タイプと出力タイプに基づいて以下の表にリストされています（テキストエンコーディングはコーデックの最も一般的なユースケースですが、基盤となるコーデックインフラストラクチャは、テキストエンコーディングだけでなく、任意のデータ変換をサポートします）。 非対称コーデックの場合、記載されている目的はエンコードの方向を説明します。

次のコーデックは、Unicodeテキストエンコーディングと同様に、Unicodeからstrへのエンコーディング 1 およびstrからunicodeへのデコード 2 を提供します。

コーデック	エイリアス	目的
idna		RFC 3490 を実装します。 encodings.idna も参照してください。
mbcs	dbcs	Windowsのみ：ANSIコードページ（CP_ACP）に従ってオペランドをエンコードします
パルモス		PalmOS3.5のエンコーディング
punycode		RFC 3492 を実装します
raw_unicode_escape		Pythonソースコードで生のUnicodeリテラルとして適切な文字列を生成します
rot_13	rot13	オペランドのシーザー暗号暗号化を返します
未定義		すべての変換に対して例外を発生させます。 バイト文字列とUnicode文字列の間の自動強制が必要ない場合は、システムエンコーディングとして使用できます。
unicode_escape		PythonソースコードでUnicodeリテラルとして適切な文字列を生成します
unicode_internal		オペランドの内部表現を返します

バージョン2.3の新機能： idnaおよびpunycodeエンコーディング。

次のコーデックは、str-to-strエンコーディングおよびデコーディング 2 を提供します。

コーデック	エイリアス	目的	エンコーダー/デコーダー
base64_codec	base64、base-64	オペランドを複数行のMIMEbase64に変換します（結果には常に末尾の'\n'が含まれます）	base64.encodestring（）、 base64.decodestring（）
bz2_codec	bz2	bz2を使用してオペランドを圧縮します	bz2.compress（）、 bz2.decompress（）
hex_codec	ヘックス	オペランドを1バイトあたり2桁の16進表現に変換します	binascii.b2a_hex（）、 binascii.a2b_hex（）
quopri_codec	quopri、quoted-printable、quotedprintable	オペランドをMIMEquotedprintableに変換します	quopri.encode（）とquotetabs=True、 quopri.decode（）
string_escape		Pythonソースコードで文字列リテラルとして適切な文字列を生成します
uu_codec	uu	uuencodeを使用してオペランドを変換します	uu.encode（）、 uu.decode（）
zlib_codec	zip、zlib	gzipを使用してオペランドを圧縮します	zlib.compress（）、 zlib.decompress（）

1

strオブジェクトは、Unicodeオブジェクトの代わりに入力としても受け入れられます。 これらは、デフォルトのエンコーディングを使用してデコードすることにより、暗黙的にユニコードに変換されます。 この変換が失敗すると、エンコード操作でUnicodeDecodeErrorが発生する可能性があります。

2（ 1 、 2 ）

strオブジェクトの代わりに、Unicodeオブジェクトも入力として受け入れられます。 これらは、デフォルトのエンコーディングを使用してエンコードすることにより、暗黙的にstrに変換されます。 この変換が失敗すると、デコード操作でUnicodeEncodeErrorが発生する可能性があります。

7.8.5。 encodings.idna —アプリケーションの国際化ドメイン名

バージョン2.3の新機能。

このモジュールは、 RFC 3490 （アプリケーションの国際化ドメイン名）および RFC 3492 （Nameprep：国際化ドメイン名のStringprepプロファイル（ IDN））。 punycodeエンコーディングと stringprep に基づいて構築されています。

これらのRFCは一緒に、ドメイン名で非ASCII文字をサポートするプロトコルを定義します。 非ASCII文字（www.Alliancefrançaise.nuなど）を含むドメイン名は、ASCII互換のエンコーディング（www.xn--alliancefranaise-npb.nuなどのACE）に変換されます。 ドメイン名のACE形式は、DNSクエリ、HTTP Host フィールドなど、プロトコルで任意の文字が許可されていないすべての場所で使用されます。 この変換はアプリケーションで実行されます。 可能であれば、ユーザーには見えない：アプリケーションは、Unicodeドメインラベルをネットワーク上で透過的にIDNAに変換し、ACEラベルをUnicodeに変換してから、ユーザーに提示する必要があります。

Pythonは、この変換をいくつかの方法でサポートしています。idnaコーデックは、UnicodeとACEの間の変換を実行し、のセクション3.1 （1）で定義されている区切り文字に基づいて入力文字列をラベルに分離します。 ] RFC 3490 および必要に応じて各ラベルをACEに変換し、逆に.区切り文字に基づいて入力バイト文字列をラベルに分離し、見つかったACEラベルをUnicodeに変換します。 さらに、 socket モジュールはUnicodeホスト名をACEに透過的に変換するため、アプリケーションはホスト名をソケットモジュールに渡すときにホスト名自体を変換する必要はありません。 さらに、 httplib や ftplib など、関数パラメーターとしてホスト名を持つモジュールは、Unicodeホスト名を受け入れ（ httplib ）、IDNAも透過的に送信します。 Host フィールドを送信する場合は、そのフィールドのホスト名）。

ワイヤーからホスト名を受信する場合（逆の名前検索など）、Unicodeへの自動変換は実行されません。そのようなホスト名をユーザーに提示したいアプリケーションは、それらをUnicodeにデコードする必要があります。

モジュール encodings.idna は、ホスト名に対して特定の正規化を実行し、国際ドメイン名の大文字と小文字を区別せず、類似した文字を統合するnameprepプロシージャも実装します。 nameprep関数は、必要に応じて直接使用できます。

encodings.idna.nameprep(label)

ラベルの名前が準備されたバージョンを返します。 実装は現在クエリ文字列を想定しているため、AllowUnassignedはtrueです。

encodings.idna.ToASCII(label)

RFC 3490 で指定されているように、ラベルをASCIIに変換します。 UseSTD3ASCIIRulesはfalseと見なされます。

encodings.idna.ToUnicode(label)

RFC 3490 で指定されているように、ラベルをUnicodeに変換します。

7.8.6。 encodings.utf_8_sig —BOM署名付きのUTF-8コーデック

バージョン2.5の新機能。

このモジュールは、UTF-8コーデックのバリアントを実装します。UTF-8でエンコードされたBOMは、エンコード時にUTF-8でエンコードされたバイトの前に付加されます。 ステートフルエンコーダの場合、これは1回だけ実行されます（バイトストリームへの最初の書き込み時）。 オプションのUTF-8エンコードBOMをデコードする場合、データの開始時にスキップされます。