
:mod:`codecs` --- codec レジストリと基底クラス
==============================================

.. module:: codecs
   :synopsis: データやストリームのエンコード・デコード。
.. moduleauthor:: Marc-Andre Lemburg <mal@lemburg.com>
.. sectionauthor:: Marc-Andre Lemburg <mal@lemburg.com>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>


.. index::
   single: Unicode
   single: Codecs
   pair: Codecs; encode
   pair: Codecs; decode
   single: streams
   pair: stackable; streams

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

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


.. function:: register(search_function)

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

   :class:`CodecInfo` オブジェクトを返します。

   * ``name`` エンコーディング名

   * ``encode`` 内部状態を持たないエンコード関数

   * ``decode`` 内部状態を持たないデコード関数

   * ``incrementalencoder`` 漸増的エンコーダクラスまたはファクトリ関数

   * ``incrementaldecoder`` 漸増的デコーダクラスまたはファクトリ関数

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

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

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

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

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

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

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

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

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

   ファクトリ関数は、基底クラスの :class:`StreamWriter` や
   :class:`StreamReader` が定義しているインタフェースを提供するオブジェ
   クトを返さねばなりません。ストリーム codecs は内部状態を維持できます。

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

   検索関数は、与えられたエンコーディングを見つけられなかった場合、
   ``None`` を返さねばなりません。

.. function:: lookup(encoding)

   Python codec レジストリから codec 情報を探し、上で定義したような
   :class:`CodecInfo` オブジェクトを返します。

   エンコーディングの検索は、まずレジストリのキャッシュから行います。
   見つからなければ、登録されている検索関数のリストから探します。
   :class:`CodecInfo` オブジェクトが一つも見つからなければ
   :exc:`LookupError` を送出します。見つかったら、その
   :class:`CodecInfo` オブジェクトはキャッシュに保存され、呼び出し側に
   返されます。

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


.. function:: getencoder(encoding)

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

   *encoding* が見つからなければ :exc:`LookupError` を送出します。


.. function:: getdecoder(encoding)

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

   *encoding* が見つからなければ :exc:`LookupError` を送出します。


.. function:: getincrementalencoder(encoding)

   *encoding* に指定した codec を検索し、漸増的エンコーダクラス、また
    はファクトリ関数を返します。

   *encoding* が見つからない、もしくは codec が漸増的エンコーダをサポー
    トしないとき :exc:`LookupError` を送出します。

   .. versionadded:: 2.5


.. function:: getincrementaldecoder(encoding)

   *encoding* に指定した codec を検索し、漸増的デコーダクラス、または
    ファクトリ関数を返します。

   *encoding* が見つからない、もしくは codec が漸増的デコーダをサポー
    トしないとき :exc:`LookupError` を送出します。

   .. versionadded:: 2.5


.. function:: getreader(encoding)

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

   *encoding* が見つからなければ :exc:`LookupError` を送出します。


.. function:: getwriter(encoding)

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

   *encoding* が見つからなければ :exc:`LookupError` を送出します。


.. function:: register_error(name, error_handler)

   エラー処理関数 *error_handler* を名前 *name* で登録します。エンコー
   ド中およびデコード中にエラーが送出された場合、 *errors* パラメタに
   *name* を指定していれば *error_handler* を呼び出すようになります。

   *error_handler* はエラーの場所に関する情報の入った
   :exc:`UnicodeEncodeError` インスタンスとともに呼び出されます。
   エラー処理関数はこの例外を送出するか、別の例外を送出するか、または
   入力のエンコードができなかった部分の代替文字列とエンコードを再開す
   る場所の指定が入ったタプルを返すかしなければなりません。最後の場合、
   エンコーダは代替文字列をエンコードし、元の入力中の指定位置からエン
   コードを再開します。位置を負の値にすると、入力文字列の末端からの相
   対位置として扱われます。境界の外側にある位置を返した場合には
   :exc:`IndexError` が送出されます。

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


.. function:: lookup_error(name)

   名前 *name* で登録済みのエラー処理関数を返します。

   エラー処理関数が見つからなければ :exc:`LookupError` を送出します。


.. function:: strict_errors(exception)

   ``strict`` エラー処理の実装です。


.. function:: replace_errors(exception)

   ``replace`` エラー処理の実装です。


.. function:: ignore_errors(exception)

   ``ignore`` エラー処理の実装です。


.. function:: xmlcharrefreplace_errors(exception)

   ``xmlcharrefreplace`` エラー処理の実装です。


.. function:: backslashreplace_errors(exception)

   ``backslashreplace`` エラー処理の実装です。

エンコードされたファイルやストリームの処理を簡便化するため、このモジュー
ルは次のようなユーティリティ関数を定義しています。


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

   *mode* でエンコードされたファイルを開き、透過的にエンコード・デコー
    ドを行うようにラップしたファイルオブジェクトを返します。デフォルト
    のファイルモードは ``'r'`` 、つまり、読み出しモードでファイルを開
    きます。

   .. note::

      ラップ版のファイルオブジェクトを操作する関数は、該当する codec
      が定義している形式のオブジェクトだけを受け付けます。多くの組み込
      み codec では Unicode オブジェクトです。関数の戻り値も codec に
      依存し、通常は Unicode オブジェクトです。

   .. note::

      非バイナリモードが指定されても、ファイルは常にバイナリモードで開
      かれます。これは、 8-bit の値を使うエンコーディングでデータが消
      失するのを防ぐためです。つまり、読み出しや書き込み時に、
      ``'\n'`` の自動変換はされないということです。


   *encoding* にはファイルのエンコーディングを指定します。

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

   *buffering* は、組み込み関数 :func:`open` と同じです。デフォルトで
    は行バッファリングです。


.. function:: EncodedFile(file, input[, output[, errors]])

   ラップしたファイルオブジェクトを返します。このオブジェクトは透過な
   エンコード変換を提供します。

   ラップされたファイルに書かれた文字列は、 *input* に指定したエンコー
   ディングに従って変換され、 *output* に指定したエンコーディングを使っ
   て string 型に変換され、ファイルに書き込まれます。中間エンコーディ
   ングは指定された codecs に依存しますが、普通は Unicode です。

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

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


.. function:: iterencode(iterable, encoding[, errors])

   漸増的エンコーダを使って、 *iterable* から供給される入力を反復的に
   エンコードします。この関数は :term:`generator` です。 *errors* は (そして他の
   キーワード引数も同様に) 漸増的エンコーダにそのまま引き渡されます。

   .. versionadded:: 2.5


.. function:: iterdecode(iterable, encoding[, errors])

   漸増的デコーダを使って、 *iterable* から供給される入力を反復的にデ
   コードします。この関数は :term:`generator` です。 *errors* は
   (そして他のキーワード引数も同様に) 漸増的デコーダにそのまま引き渡されます。

   .. versionadded:: 2.5

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


.. data:: 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 として使われます。
   :const:`BOM_UTF16` は :const:`BOM_UTF16_BE` と :const:`BOM_UTF16_LE`
   のいずれかで、プラットフォームのネイティブバイトオーダに依存します。
   :const:`BOM` は :const:`BOM_UTF16` の別名です。同様に
   :const:`BOM_LE` は :const:`BOM_UTF16_LE` の、 :const:`BOM_BE` は
   :const:`BOM_UTF16_BE` の別名です。他は UTF-8 と UTF-32 エンコーディ
   ングの BOM を表します。


.. _codec-base-classes:

Codec 基底クラス
----------------

:mod:`codecs` モジュールでは、 codec のインタフェースを定義する一連の
基底クラスを用意して、 Python 用 codec を簡単に自作できるようにしています。

Python で何らかの codec を使えるようにするには、状態なしエンコーダ、状
態なしデコーダ、ストリームリーダ、ストリームライタの 4 つのインタフェー
スを定義せねばなりません。通常は、状態なしエンコーダとデコーダを再利用
してストリームリーダとライタのファイル・プロトコルを実装します。

:class:`Codec` クラスは、状態なしエンコーダ・デコーダのインタフェース
を定義しています。

エラー処理の簡便化と標準化のため、 :meth:`encode` メソッドと
:meth:`decode` メソッドでは、 *errors* 文字列引数を指定した
場合に別のエラー処理を行うような仕組みを実装してもかまいません。全て
の標準 Python codec では以下の文字列が定義され、実装されています。

+-------------------------+--------------------------------------------------------------------------+
| Value                   | Meaning                                                                  |
+=========================+==========================================================================+
| ``'strict'``            | :exc:`UnicodeError` (または、そのサブクラス) を送出します --             |
|                         | デフォルトの動作です。                                                   |
+-------------------------+--------------------------------------------------------------------------+
| ``'ignore'``            | その文字を無視し、次の文字から変換を再開します。                         |
+-------------------------+--------------------------------------------------------------------------+
| ``'replace'``           | 適当な文字で置換します -- Python の組み込み  Unicode codec               |
|                         | のデコード時には公式の U+FFFD REPLACEMENT CHARACTER を、                 |
|                         | エンコード時には '?' を使います。                                        |
+-------------------------+--------------------------------------------------------------------------+
| ``'xmlcharrefreplace'`` | 適切な XML 文字参照で置換します (エンコードのみ)                         |
+-------------------------+--------------------------------------------------------------------------+
| ``'backslashreplace'``  | バックスラッシュつきのエスケープシーケンスで置換します (エンコードのみ)  |
+-------------------------+--------------------------------------------------------------------------+

codecs がエラーハンドラとして受け入れる値は :meth:`register_error` を使っ
て追加できます。


.. _codec-objects:

Codec オブジェクト
^^^^^^^^^^^^^^^^^^

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


.. method:: Codec.encode(input[, errors])

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

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

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

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


.. method:: Codec.decode(input[, errors])

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

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

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

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

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

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

.. % keep track


.. _incremental-encoder-objects:

IncrementalEncoder オブジェクト
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. versionadded:: 2.5

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


.. class:: IncrementalEncoder([errors])

   :class:`IncrementalEncoder` インスタンスのコンストラクタ。

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

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

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

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

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

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

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

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

   *errors* 引数に許される値の集合は :func:`register_error` で拡張できます。


   .. method:: encode(object[, final])

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


   .. method:: reset()

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


.. _incremental-decoder-objects:

IncrementalDecoder オブジェクト
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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


.. class:: IncrementalDecoder([errors])

   :class:`IncrementalDecoder` インスタンスのコンストラクタ。

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

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

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

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

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

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

   *errors* 引数に許される値の集合は :func:`register_error` で拡張でき
   ます。


   .. method:: decode(object[, final])

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


   .. method:: reset()

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

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


.. _stream-writer-objects:

StreamWriter オブジェクト
^^^^^^^^^^^^^^^^^^^^^^^^^

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


.. class:: StreamWriter(stream[, errors])

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

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

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

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

   * ``'strict'`` :exc:`ValueError` (または、そのサブクラス) 送出します。デフォルトの動作です。

   * ``'ignore'`` 文字を無視して、次の文字から続けます。

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

   * ``'xmlcharrefreplace'`` 適切な XML 文字参照で置換します。

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

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

   *errors* 引数が取り得る値の種類は :func:`register_error` で拡張できます。


   .. method:: write(object)

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


   .. method:: writelines(list)

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


   .. method:: reset()

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

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

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


.. _stream-reader-objects:

StreamReader オブジェクト
^^^^^^^^^^^^^^^^^^^^^^^^^

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


.. class:: StreamReader(stream[, errors])

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

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

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

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

   * ``'strict'`` :exc:`ValueError` (または、そのサブクラス) を送出します。デフォルトの処理です。

   * ``'ignore'`` 文字を無視して、次の文字から続けます。

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

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

   *errors* 引数が取り得る値の種類は :func:`register_error` で拡張でき
   ます。


   .. method:: read([size[, chars, [firstline]]])

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

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

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

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

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

      .. versionchanged:: 2.4
         引数 *chars* が追加されました。

      .. versionchanged:: 2.4.2
         引数*firstline* が追加されました。


   .. method:: readline([size[, keepends]])

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

      *size* が与えられた場合、ストリームにおける :meth:`readline` の
      size 引数に渡されます。

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

      .. versionchanged:: 2.4
         引数 *keepends* が追加されました。


   .. method:: readlines([sizehint[, keepends]])

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

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

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


   .. method:: reset()

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

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

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

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


.. _stream-reader-writer:

StreamReaderWriter オブジェクト
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

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


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

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

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


.. _stream-recoder-objects:

StreamRecoder オブジェクト
^^^^^^^^^^^^^^^^^^^^^^^^^^

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

:func:`lookup` 関数が返すファクトリ関数を使って、インスタンスを生成す
るという設計になっています。


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

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

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

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

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

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

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

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


.. _encodings-overview:

エンコーディングと Unicode
--------------------------

Unicode 文字列は内部的にはコードポイントのシーケンスとして格納されます
(正確に言えば :ctype:`Py_UNICODE` 配列です)。
Python がどのようにコンパイルされたか (デフォルトである
:option:`--enable-unicode=ucs2` かまたは
:option:`--enable-unicode=ucs4` のどちらか) によって、
:ctype:`Py_UNICODE` は16ビットまたは32ビットのデータ型です。 Unicode
オブジェクトが CPU とメモリの外で使われることになると、 CPU のエンディ
アンやこれらの配列がバイト列としてどのように格納されるかが問題になって
きます。 Unicode オブジェクトをバイト列に変換することをエンコーディン
グと呼び、バイト列から Unicode オブジェクトを再生することをデコーディ
ングと呼びます。どのようにこの変換を行うかには多くの異なった方法があり
ます (これらの方法のこともエンコーディングと言います) 。最も単純な方法
はコードポイント 0-255 をバイト ``0x0``-``0xff`` に写すことです。これ
は ``U+00FF`` より上のコードポイントを持つ Unicode オブジェクトはこの
方法ではエンコードできないということを意味します (この方法を
``'latin-1'`` とか ``'iso-8859-1'`` と呼びます)。
:func:`unicode.encode` は次のような :exc:`UnicodeEncodeError` を送出す
ることになります:
``UnicodeEncodeError: 'latin-1' codec can't encode character u'\u1234'
in position 3: ordinal not in range(256)``

他のエンコーディングの一群 (charmap エンコーディングと呼ばれます)があ
りますが、 Unicode コードポイントの別の部分集合とこれらがどのように
``0x0``-``0xff`` のバイトに写されるかを選んだものです。これがどのよう
に行なわれるかを知るには、単にたとえば :file:`encodings/cp1252.py` (主
に Windows で使われるエンコーディングです) を開いてみてください。256
文字のひとつの文字列定数がありどの文字がどのバイト値に写されるかを示し
ています。

上に挙げた全てのエンコーディングは Unicode に定義された65536(あるいは
1114111) あるコードポイント中256文字しかエンコードできません。全ての
Unicode コードポイントを収める単純明快な方法は、それぞれのコードポイン
トを二つの引き続くバイトに収めるものです。二つの可能性があります。すな
わちビッグエンディアンかリトルエンディアンか。これら二つのエンコーディ
ングはそれぞれ UTF-16-BE あるいは UTF-16-LE と呼ばれます。欠点は、たと
えば UTF-16-BE をリトルエンディアンの機械で使うときに、エンコーディン
グでもデコーディングでも常に二つのバイトを交換しなければならないことで
す。 UTF-16 はこの問題を解消します。バイトはいつでも自然なエンディアン
に従います。これらのバイトが異なるエンディアンの CPU で読まれる時は、
結局交換しない訳にはいきません。 UTF-16 のバイト列のエンディアンを検知
できるようにするために、いわゆる BOM ("Byte Order Mark") があります。
Unicode 文字で言うと ``U+FEFF`` です。この文字は全ての UTF-16 バイト列
の先頭に付加されます。この文字のバイト位置を交換したもの (``0xFFFE``)
は Unicode テキストに出現しないはずの違法な文字です。そこで、 UTF-16
バイト列の一文字目が ``U+FFFE`` に見えたなら、デコーディングの際にバイ
トを交換しなければなりません。不幸なことに、 Unicode 4.0 までは文字
``U+FEFF`` には第二の目的 ``ZERO WIDTH NO-BREAK SPACE`` (幅を持たず単
語が分割されるのを許さない文字) がありました。たとえばリガチャ(合字)ア
ルゴリズムに対するヒントを与えるために使われることがあり得ます。
Unicode 4.0 になって ``U+FEFF`` の ``ZERO WIDTH NO-BREAK SPACE`` とし
ての使用法は撤廃されました (``U+2060`` (``WORD JOINER``) にこの役割を
譲りました)。しかしながら、 Unicode ソフトウェアは依然として
``U+FEFF`` の二つの役割を扱えなければなりません。一つは BOM として、エ
ンコードされたバイトの記憶装置上のレイアウトを決め、バイト列が Unicode
文字列にデコードされた暁には消え去るものという役割。もう一つは ``ZERO
WIDTH NO-BREAK SPACE`` として、通常の文字と同じようにデコードされる文
字という役割です。

さらにもう一つ Unicode 文字全てをエンコードできるエンコーディングがあ
り、 UTF-8 と呼ばれています。UTF-8 は8ビットエンコーディングで、したがっ
て UTF-8 にはバイト順の問題はありません。UTF-8 バイト列の各バイトは二
つのパートから成ります。
二つはマーカ(上位数ビット)とペイロードです。マーカは0ビットから6ビット
の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-001FFFFF`` | 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx          |
+-----------------------------------+----------------------------------------------+
| ``U-00200000`` ... ``U-03FFFFFF`` | 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |
+-----------------------------------+----------------------------------------------+
| ``U-04000000`` ... ``U-7FFFFFFF`` | 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx |
|                                   | 10xxxxxx                                     |
+-----------------------------------+----------------------------------------------+

Unicode 文字の最下位ビットとは最も右にある x のビットです。

UTF-8 は8ビットエンコーディングなので BOM は必要とせず、デコードされた
Unicode 文字列中の ``U+FEFF`` は(たとえ最初の文字であったとしても)
``ZERO WIDTH NO-BREAK SPACE`` として扱われます。

外部からの情報無しには、 Unicode 文字列のエンコーディングにどのエンコー
ディングが使われたのか信頼できる形で決定することは不可能です。どの
charmap エンコーディングもどんなランダムなバイト列でもデコードできます。
しかし UTF-8 では、任意のバイト列が許される訳ではないような構造を持っ
ているので、そのようなことは可能ではありません。 UTF-8 エンコーディン
グであることを検知する信頼性を向上させるために、 Microsoft は Notepad
プログラム用に UTF-8 の変種 (Python 2.5 はで ``"utf-8-sig"`` と呼んで
います) を考案しました。まだ Unicode 文字がファイルに書き込まれない前
に UTF-8 でエンコードした BOM (バイト列では ``0xef``, ``0xbb``,
``0xbf`` のように見えます) を書き込んでしまいます。このようなバイト値
で charmap エンコードされたファイルが始まることはほとんどあり得ない(た
とえば iso-8859-1 では

   | LATIN SMALL LETTER I WITH DIAERESIS
   | RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK
   | INVERTED QUESTION MARK

のようになる)ので、 utf-8-sig エンコーディングがバイト列から正しく推測
される確率を高めます。つまりここでは BOM はバイト列を生成する際のバイ
ト順を決定できるように使われているのではなく、エンコーディングを推測す
る助けになる印として使われているのです。 utf-8-sig codec はエンコーディ
ングの際ファイルに最初の3文字として ``0xef``, ``0xbb``, ``0xbf`` を書
き込みます。
デコーディングの際はファイルの先頭に現れたこれら3バイトはスキップします。


.. _standard-encodings:

標準エンコーディング
--------------------

Python には数多くの codec が組み込みで付属します。これらは C 言語の関
数、対応付けを行うテーブルの両方で提供されています。以下のテーブルで
は codec と、いくつかの良く知られている別名と、エンコーディングが使わ
れる言語を列挙します。別名のリスト、言語のリストともしらみつぶしに網羅
されているわけではありません。大文字と小文字、またはアンダースコアの代
りにハイフンにしただけの綴りも有効な別名です。

多くの文字セットは同じ言語をサポートしています。これらの文字セットは個々
の文字 (例えば、 EURO SIGN がサポートされているかどうか) や、文字のコー
ド部分への割り付けが異なります。特に欧州言語では、典型的に以下の変種が
存在します:

* ISO 8859 コードセット

* Microsoft Windows コードページで、 8859 コード形式から導出されている
  が、制御文字を追加のグラフィック文字と置き換えたもの

* IBM EBCDIC コードページ

* ASCII 互換の IBM PC コードページ

+-----------------+--------------------------------+------------------------------------------------------+
| Codec           | 別名                           | 言語                                                 |
+=================+================================+======================================================+
| ascii           | 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                         |                                                      |
+-----------------+--------------------------------+------------------------------------------------------+
| cp737           |                                | ギリシャ語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| cp775           | IBM775                         | バルト沿岸国                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| cp850           | 850, IBM850                    | 西ヨーロッパ                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| cp852           | 852, IBM852                    | 中央および東ヨーロッパ                               |
+-----------------+--------------------------------+------------------------------------------------------+
| cp855           | 855, IBM855                    | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア |
+-----------------+--------------------------------+------------------------------------------------------+
| cp856           |                                | ヘブライ語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| cp857           | 857, IBM857                    | トルコ語                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| 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          |                                | Urdu                                                 |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1026          | ibm1026                        | トルコ語                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1140          | ibm1140                        | 西ヨーロッパ                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1250          | windows-1250                   | 中央および東ヨーロッパ                               |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1251          | windows-1251                   | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1252          | windows-1252                   | 西ヨーロッパ                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1253          | windows-1253                   | ギリシャ                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1254          | windows-1254                   | トルコ                                               |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1255          | windows-1255                   | ヘブライ                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1256          | windows1256                    | アラビア                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1257          | windows-1257                   | バルト沿岸国                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| cp1258          | windows-1258                   | ベトナム                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| euc_jp          | eucjp, ujis, u-jis             | 日本語                                               |
+-----------------+--------------------------------+------------------------------------------------------+
| euc_jis_2004    | jisx0213, eucjis2004           | 日本語                                               |
+-----------------+--------------------------------+------------------------------------------------------+
| euc_jisx0213    | eucjisx0213                    | 日本語                                               |
+-----------------+--------------------------------+------------------------------------------------------+
| euc_kr          | euckr, korean, ksc5601,        | 韓国語                                               |
|                 | ks_c-5601, ks_c-5601-1987,     |                                                      |
|                 | ksx1001, ks_x-1001             |                                                      |
+-----------------+--------------------------------+------------------------------------------------------+
| gb2312          | chinese, 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, cyrillic           | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_6       | iso-8859-6, arabic             | アラビア語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_7       | iso-8859-7, greek, greek8      | ギリシャ語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_8       | iso-8859-8, hebrew             | ヘブライ語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_9       | iso-8859-9, latin5, L5         | トルコ語                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_10      | iso-8859-10, latin6, L6        | 北欧                                                 |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_13      | iso-8859-13                    | バルト沿岸国                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_14      | iso-8859-14, latin8, L8        | ケルト                                               |
+-----------------+--------------------------------+------------------------------------------------------+
| iso8859_15      | iso-8859-15                    | 西ヨーロッパ                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| johab           | cp1361, ms1361                 | 韓国語                                               |
+-----------------+--------------------------------+------------------------------------------------------+
| koi8_r          |                                | ロシア語                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| koi8_u          |                                | ウクライナ                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| mac_cyrillic    | maccyrillic                    | ブルガリア、ベラルーシ、マケドニア、ロシア、セルビア |
+-----------------+--------------------------------+------------------------------------------------------+
| mac_greek       | macgreek                       | ギリシャ                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| mac_iceland     | maciceland                     | アイスランド                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| mac_latin2      | maclatin2, maccentraleurope    | 中央および東ヨーロッパ                               |
+-----------------+--------------------------------+------------------------------------------------------+
| mac_roman       | macroman                       | 西ヨーロッパ                                         |
+-----------------+--------------------------------+------------------------------------------------------+
| mac_turkish     | macturkish                     | トルコ語                                             |
+-----------------+--------------------------------+------------------------------------------------------+
| ptcp154         | csptcp154, pt154, cp154,       | カザフ                                               |
|                 | cyrillic-asian                 |                                                      |
+-----------------+--------------------------------+------------------------------------------------------+
| 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 only)                                |
+-----------------+--------------------------------+------------------------------------------------------+
| utf_16_le       | UTF-16LE                       | 全ての言語 (BMP only)                                |
+-----------------+--------------------------------+------------------------------------------------------+
| utf_7           | U7, unicode-1-1-utf-7          | 全ての言語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| utf_8           | U8, UTF, utf8                  | 全ての言語                                           |
+-----------------+--------------------------------+------------------------------------------------------+
| utf_8_sig       |                                | 全ての言語                                           |
+-----------------+--------------------------------+------------------------------------------------------+

codec のいくつかは Python 特有のものなので、それらの codec 名は Python の外では無意味なものとなります。これらの codec
の中には Unicode 文字列からバイト文字列への変換を行わず、むしろ単一の引数をもつ全写像関数はエンコーディングとみなせるという Python codec
の性質を利用したものもあります。

以下に列挙した codec では、"エンコード" 方向の結果は常にバイト文字列方向です。"デコード" 方向の結果はテーブル内の被演算子型として列挙
されています。

+--------------------+---------------------------+----------------+--------------------------------------------------------+
| Codec              | 別名                      | 被演算子の型   | 目的                                                   |
+====================+===========================+================+========================================================+
| base64_codec       | base64, base-64           | byte string    | 被演算子を MIME base64 に変換します。                  |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| bz2_codec          | bz2                       | byte string    | 被演算子をbz2を使って圧縮します。                      |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| hex_codec          | hex                       | byte string    | 被演算子をバイトあたり 2 桁の 16                       |
|                    |                           |                | 進数の表現に変換します。                               |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| idna               |                           | Unicode string | :rfc:`3490` の実装です。                               |
|                    |                           |                | :mod:`encodings.idna`                                  |
|                    |                           |                | も参照してください。                                   |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| mbcs               | dbcs                      | Unicode string | Windows のみ: 被演算子を ANSI                          |
|                    |                           |                | コードページ (CP_ACP) に従って                         |
|                    |                           |                | エンコードします。                                     |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| palmos             |                           | Unicode string | PalmOS 3.5 のエンコーディングです。                    |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| punycode           |                           | Unicode string | :rfc:`3492` を実装しています。                         |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| quopri_codec       | quopri, quoted-printable, | byte string    | 被演算子を MIME quoted                                 |
|                    | quotedprintable           |                | printable 形式に変換します。                           |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| raw_unicode_escape |                           | Unicode string | Python ソースコードにおける raw                        |
|                    |                           |                | Unicode リテラルとして                                 |
|                    |                           |                | 適切な文字列を生成します。                             |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| rot_13             | rot13                     | Unicode string | 被演算子のシーザー暗号 (Caesar-                        |
|                    |                           |                | cypher) を返します。                                   |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| string_escape      |                           | byte string    | Python                                                 |
|                    |                           |                | ソースコードにおける文字列リテラルとして適切な         |
|                    |                           |                | 文字列を生成します。                                   |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| undefined          |                           | any            | 全ての変換に対して例外を送出します。バイト列と         |
|                    |                           |                | Unicode 文字列との間で                                 |
|                    |                           |                | :term:`coercion` (強制型変換) をおこないたくない       |
|                    |                           |                | 時にシステムエンコーディングとして使うことができます。 |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| unicode_escape     |                           | Unicode string | Python ソースコードにおける Unicode                    |
|                    |                           |                | リテラルとして適切な文字列を生成します。               |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| unicode_internal   |                           | Unicode string | 被演算子の内部表現を返します。                         |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| uu_codec           | uu                        | byte string    | 被演算子を uuencode を用いて変換します。               |
+--------------------+---------------------------+----------------+--------------------------------------------------------+
| zlib_codec         | zip, zlib                 | byte string    | 被演算子を gzip を用いて圧縮します。                   |
+--------------------+---------------------------+----------------+--------------------------------------------------------+

.. versionadded:: 2.3
   The ``idna`` and ``punycode`` encodings.


:mod:`encodings.idna` --- アプリケーションにおける国際化ドメイン名 (IDNA)
-------------------------------------------------------------------------

.. module:: encodings.idna
   :synopsis: 国際化ドメイン名実装


.. moduleauthor:: Martin v. Löwis

.. versionadded:: 2.3

このモジュールでは :rfc:`3490` (アプリケーションにおける国際化ドメイン
名、 IDNA: Internationalized Domain Names in Applications) および
:rfc:`3492` (Nameprep: 国際化ドメイン名 (IDN) のための stringprep プロ
ファイル) を実装しています。このモジュールは ``punycode`` エンコーディ
ングおよび :mod:`stringprep` の上に構築されています。

これらの RFC はともに、非 ASCII 文字の入ったドメイン名をサポートするた
めのプロトコルを定義しています。 (''www.Alliancefrançaise.nu'' のよう
な) 非 ASCII 文字を含むドメイン名は、 ASCII と互換性のあるエンコーディ
ング (ACE、 ''www.xn--alliancefranaise-npb.nu'' のような形式) に変換さ
れます。ドメイン名の ACE 形式は、 DNS クエリ、 HTTP :mailheader:`Host`
フィールドなどといった、プロトコル中で任意の文字を使えないような全ての
局面で用いられます。この変換はアプリケーション内で行われます; 可能なら
ユーザからは不可視となります: アプリケーションは Unicode ドメインラベ
ルをワイヤ上に載せる際に IDNA に、 ACE ドメインラベルをユーザに提供す
る前に Unicode に、それぞれ透過的に変換しなければなりません。

Python ではこの変換をいくつかの方法でサポートします: ``idna`` codec は
Unicode と ACE 間の変換を行います。さらに、 :mod:`socket` モジュールは Unicode ホスト名を ACE に透過的に変換するため、アプリケーションはホスト名を :mod:`socket`
モジュールに渡す際にホスト名の変換に煩わされることがありません。その上
で、ホスト名を関数パラメタとして持つ、 :mod:`httplib` や :mod:`ftplib`
のようなモジュールでは Unicode ホスト名を受理します (:mod:`httplib` で
もまた、 ``Host:`` フィールドにある IDNA ホスト名を、フィールド全体を
送信する場合に透過的に送信します)。

(逆引きなどによって) ワイヤ越しにホスト名を受信する際、 Unicode への自
動変換は行われません: こうしたホスト名をユーザに提供したいアプリケーショ
ンでは、 Unicode にデコードしてやる必要があります。

:mod:`encodings.idna` ではまた、 nameprep 手続きを実装しています。
nameprep はホスト名に対してある正規化を行って、国際化ドメイン名で大小
文字を区別しないようにするとともに、類似の文字を一元化します。
nameprep 関数は必要なら直接使うこともできます。


.. function:: nameprep(label)

   *label* を nameprep したバージョンを返します。現在の実装ではクエリ文字列を仮定しているので、 ``AllowUnassigned``
   は真です。


.. function:: ToASCII(label)

   :rfc:`3490` 仕様に従ってラベルを ASCIIに変換します。 ``UseSTD3ASCIIRules`` は偽であると仮定します。


.. function:: ToUnicode(label)

   :rfc:`3490` 仕様に従ってラベルを Unicode に変換します。


:mod:`encodings.utf_8_sig` --- BOM 印付き UTF-8
-----------------------------------------------

.. module:: encodings.utf_8_sig
   :synopsis: UTF-8 codec with BOM signature
.. moduleauthor:: Walter Dörwald

.. versionadded:: 2.5

このモジュールは UTF-8 codec の変種を実装します。この変種はエンコーディング時に UTF-8 でエンコードされた BOM を UTF-8
でエンコードされたバイト列の前に追加します。内部状態を持つエンコーダにとって、これは一度だけ(バイトストリームの最初の書き込み時)
行なわれます。デコーディングに際してはデータ開始の UTF-8 でエンコードされた BOM がもしあったらスキップします。

