:mod:`io` --- ストリームを扱うコアツール
=================================================

.. module:: io
   :synopsis: Core tools for working with streams.
.. moduleauthor:: Guido van Rossum <guido@python.org>
.. moduleauthor:: Mike Verdone <mike.verdone@gmail.com>
.. moduleauthor:: Mark Russell <mark.russell@zen.co.uk>
.. sectionauthor:: Benjamin Peterson
.. versionadded:: 2.6

:mod:`io` モジュールはストリーム処理をする Python インタフェースを提供します。
組み込み関数 :func:`open` はこのモジュールで定義されています。

I/O 階層の最上位には抽象基底クラスの :class:`IOBase` があります。
:class:`IOBase` ではストリームに対して基本的なインタフェースを定義しています。
しかしながら、ストリームの読みと書きの間に違いがないことに留意してください。
実装においては与えられた操作をサポートしない場合は :exc:`IOError` を投げることが許されています。

:class:`IOBase` の拡張は生のバイト列の読み書きをしてストリームに落とす処理を単純に扱う :class:`RawIOBase` です。
:class:`FileIO` は :class:`RawIOBase` を継承してマシンのファイルシステム中のファイルへのインタフェースを提供します。

:class:`BufferedIOBase` では生のバイトストリーム (:class:`RawIOBase`) の上にバッファ処理を追加します。
そのサブクラスの :class:`BufferedWriter`, :class:`BufferedReader`, :class:`BufferedRWPair` ではそれぞれ読み込み専用、書き込み専用、読み書き可能なストリームをバッファします。
:class:`BufferedRandom` ではランダムアクセスストリームに対してバッファされたインタフェースを提供します。
:class:`BytesIO` はインメモリバイトへのシンプルなストリームです。

もう一つの :class:`IOBase` のサブクラスである、 :class:`TextIOBase` は文字列を表すバイトストリームやその文字列に対するエンコーディングやデコーディングといった処理を行います。
:class:`TextIOWrapper` はその拡張で、バッファされた生ストリーム (:class:`BufferedIOBase`) へのバッファされた文字列インタフェースです。
最後に :class:`StringIO` は文字列に対するインメモリストリームです。

引数名は規約に含まれていません。
また :func:`open` の引数はキーワード引数として用いられることが意図されています。


モジュールインタフェース
------------------------

.. data:: DEFAULT_BUFFER_SIZE

   モジュールのバッファ I/O クラスに使用されるデフォルトのバッファサイズを指定する整数値です。
   :func:`open` は可能であればファイル全体のサイズを使用します。（ファイル全体のサイズは :func:`os.stat` で取得されます)

.. function:: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd=True]]]]]])

   *file* を開きストリームを返します。
   もしファイルを開くことが出来なかった場合、 :exc:`IOError` が発生します。

   *file* は開きたいファイルの名前(とカレントディレクトリにない場合はそのパス)を示す文字列であるか、開きたいファイルのファイルディスクリプタです。
   (たとえば :func:`os.fdopen` から得られるようなファイルディスクリプタが与えられた場合、 *closefd* が ``False`` に設定されていなければ、返されたI/Oオブジェクトが閉じられたときにそのファイルディスクリプタは閉じられます)

   *mode* はオプションの文字列です。これによってファイルをどのようなモードで開くか明示することができます。
   デフォルトは ``'r'`` でテキストモードで読み取り専用で開くことを指します。
   他にも ``'w'`` は書き込み専用(もしファイルが存在していた場合は上書きになります)となり、 ``'a'`` では追記モードとなります。
   (``'a'`` は *いくつかの* Unixシステムでは *すべての* 書き込みがシーク位置がどこにあろうともファイルの末尾に追記されることを意味します)
   テキストモードではもし *encoding* が指定されていなかった場合、エンコーディングはプラットフォーム依存となります。
   (生のバイトデータの読み込みと書き込みはバイナリモードを用いて、 *encoding* は未指定のままとします)
   指定可能なモードは次の表の通りです。

   ========= ===============================================================
   文字       意味
   --------- ---------------------------------------------------------------
   ``'r'``   読み込み専用で開く(デフォルト)
   ``'w'``   書き込み専用で開く。ファイルの内容をまず初期化する。
   ``'a'``   書き込み専用で開く。ファイルが存在する場合は末尾に追記する。
   ``'b'``   バイナリモード
   ``'t'``   テキストモード(デフォルト)
   ``'+'``     ファイルを更新用に開く(読み込み／書き込み)
   ``'U'``   ユニバーサルニューラインモード
             (後方互換性のためのモードであり、新規コードでは使用すべきではありません)
   ========= ===============================================================


   デフォルトモードは ``'rt'`` です。(テキストを読み込み専用で開ます)
   バイナリのランダムアクセスでは ``'w+b'`` でファイルを開き、0バイトに初期化します。
   一方で ``'r+b'`` でファイルを開くと初期化は行われません。

   Pythonではバイナリモードで開かれたファイルとテキストモードで開かれたファイルを区別します。
   オペレーティングシステムが区別しない場合でもそれは適用されます。
   バイナリモードで開かれたファイル(つまり *mode* 引数に ``'b'`` が含まれるとき)では中身を ``bytes`` オブジェクトとして返し、一切のデコードを行いません。
   テキストモード(デフォルトか *mode* 引数に ``'t'`` が含まれている場合)ではファイルの中身は文字列として返され、バイト列はプラットフォーム依存のエンコーディングをされるか、 *encoding* が指定された場合は指定されたエンコーディングを行います。

   オプションである *buffering* はバッファ用の設定を行う整数値です。
   デフォルトではフルバッファがオンに設定されています。
   0を設定することでバッファがオフになります。(バイナリモードでのみ有効です)
   1の場合は１行ごとのバッファリングを行い、1より大きい場合はフルバッファが行われます。

   *encoding* はファイルをエンコードあるいはデコードするために使われるエンコーディング名です。
   このオプションはテキストモードでのみ使用されるべきです。
   デフォルトエンコーディングはプラットフォーム依存ですが、Pythonでサポートされているエンコーディングはどれでも使えます。
   詳しくは :mod:`codecs` モジュール内のサポートしているエンコーディングのリストを参照してください。

   *errors* はエンコードやデコードの際のエラーをどのように扱うかを指定する文字列です。
   ``'strict'`` を指定するとエンコードエラーがあった場合 :exc:`ValueError` 例外を発生させます。
   (デフォルトである ``None`` は同様の処理を行います)
   ``'ignore'`` を指定した場合はエラーを無視します。 ``'replace'`` を指定した場合は正常に変換されなかった文字の代わりにマーカ(例えば ``'?'`` のような文字)を挿入します。
   書き込みの際に ``'xmlcharrefreplace'`` (適切なXML文字参照に置き換える)か ``'backslashreplace'`` (バックスラッシュによるエスケープシーケンスに置き換える)のどちらかが使用出来ます。
   :func:`codecs.register_error` に登録されている他のエラー処理名も指定出来ます。

   *newline* ではユニバーサルニューラインの挙動を制御しています。(テキストモードのみ有効です)
   ``None``, ``''``, ``'\n'``, ``'\r'``, ``'\r\n'`` が指定出来ます。
   以下のように動作します：

   * 入力時、 *newline* が ``None`` の場合はユニバーサルニューラインモードが有効になります。
     入力行は ``'\n'``, ``'\r'``, ``'\r\n'`` のどれかで終わると思いますが、それらは呼び出し元に戻される前に ``'\n'`` に変換されます。
     もし ``''`` だった場合はユニバーサルニューラインモードは有効になりますが、行末は変換されずに呼び出し元に戻されます。
     もし他の適切な値が指定された場合は、入力行は与えられた文字列で中断され、行末は変換されずに呼び出し元に戻されます。

   * 出力時、 *newline* が ``None`` の場合は、すべての ``'\n'`` 文字はシステムのデフォルト行区切り文字 :data:`os.linesep` に変換されます。
     もし *newline* が ``''`` の場合、変換は起きません。
     もし *newline* に他の適切な値が指定された場合は、 ``'\n'`` 文字は与えられた文字に変換されます。

   もし *closefd* が ``False`` で、ファイル名ではなくてファイルディスクリプタが与えられていた場合、処理中のファイルディスクリプタはファイルが閉じられた後も開いたままとなります。
   もしファイル名が与えられていた場合は、 *closefd* は関係ありません。しかし ``True`` でなければいけません。(デフォルト値)

   :func:`open` によって返されるファイルオブジェクトのタイプの話をすると、 :func:`open` がテキストモードでファイルを開くときに使われた場合( ``'w'``, ``'r'``, ``'wt'``, ``'rt'`` など)、 :class:`TextIOWrapper` が返されます。
   バイナリモードでファイルを開くときに使われた場合、返される値は変わってきます。もし読み取り専用のバイナリモードだった場合は :class:`BufferedReader` が返されます。
   書き込み専用のバイナリモードだった場合は :class:`BufferedWriter` が返されます。
   読み書き可能なバイナリモードの場合は :class:`BufferedRandom` が返されます。

   もし文字列やバイト列をファイルとして読み書きすることも可能です。
   文字列では :class:`StringIO` を使えばテキストモードで開いたファイルのように扱えます。
   バイト列では :class:`BytesIO` を使えばバイナリモードで開いたファイルのように扱えます。


.. exception:: BlockingIOError

   非ブロッキングストリームでブロック処理が起きた場合に発生するエラーです。
   :exc:`IOError` を継承しています。

   :exc:`IOError` で持っている属性以外に :exc:`BlockingIOError` では次の属性を持っています。

   .. attribute:: characters_written

      ブロック前にストリームに書き込まれる文字数を保持する整数値です。


.. exception:: UnsupportedOperation

   :exc:`IOError` と :exc:`ValueError` を継承した例外でストリームに予想外の操作が行われた場合に発生します。


I/O ベースクラス
----------------

.. class:: IOBase

   すべてのI/Oクラスの抽象ベースクラスです。バイトストリームへの操作を行います。
   パブリックなコンストラクタはありません。

   このクラスでは継承先のクラスがオーバライドするかの選択の余地を残すためにたくさんの
   空の抽象実装を持っています。デフォルトの実装では読み込み、書き込み、シークができない
   ファイルとなっています。

   :class:`IOBase` がそのシグナチャーが変化するため :meth:`read`, :meth:`readinto`,
   :meth:`write` を宣言していなくても、実装やクライアントはインタフェースの一部として
   これらのメソッドを考慮するべきです。
   また実装はサポートしていない操作を呼び出されたときは :exc:`IOError` を発生させるかもしれません。


   ファイル等への読み書きに用いられるバイナリデータに使われるバイナリ型は :class:`bytes` です。
   :class:`bytearray` も許可されています。ほかにもいくつかのクラス(たとえば :class:`readinto`)
   が必要です。文字列のI/Oクラスは :class:`str` のデータを扱っています。

   閉じたストリームでメソッドを呼び出し(問い合わせでさえ)は定義されていません。
   この場合実装は :exc:`IOError` を発生させます。

   IOBase(とそのサブクラス)はイテレータプロトコルをサポートします。
   それはつまり :class:`IOBase` オブジェクトはストリーム内の行をyieldを使って
   イテレートすることが出来ます。

   IOBaseはコンテキストマネージャでもあります。そのため :keyword:`with` 構文を
   サポートします。次の例では *file* は :keyword:`with` 構文が終わった後、
   閉じられます。--それがたとえ例外が発生したあとでさえです。

      with open('spam.txt', 'w') as file:
          file.write('Spam and eggs!')

   :class:`IOBase` データ属性とメソッドを提供します:

   .. method:: close()

      このストリームをフラッシュして閉じます。このメソッドはファイルが既に閉じられていた場合
      特になにも影響を与えません。

   .. attribute:: closed

      ストリームが閉じられていた場合Trueになります。

   .. method:: fileno()

      ストリームが保持しているファイルディスクリプタ(整数値)が存在する場合はそれを返します。
      もしIOオブジェクトがファイルディスクリプタを使っていない場合は :exc:`IOError` が発生します。

   .. method:: flush()

      適用可能であればストリームの書き込みバッファをフラッシュします。
      読み込み専用や非ブロッキングストリームには影響を与えません。

   .. method:: isatty()

      ストリームが相互作用的であれば(つまりターミナルやttyデバイスにつながっている場合)
      ``True`` を返します。

   .. method:: readable()

      ストリームが読み込める場合 ``True`` を返します。
      Falseの場合は :meth:`read` は :exc:`IOError` を発生させます。

   .. method:: readline([limit])

      ストリームから1行読み込んで返します。
      もし *limit* が指定された場合、最大で *limit* バイトが読み込まれます。

      バイナリファイルでは行末文字は常に ``b'\n'`` となります。テキストファイルでは
      :func:`open` への *newlines* 引数は行末文字が認識されたときに使われます。

   .. method:: readlines([hint])

      ストリームから行のリストを読み込んで返します。
      *hint* を指定することで、何行読み込むかを指定出来ます。
      もし読み込んだすべての行のサイズ(バイト数、もしくは文字数)が
      *hint* の値を超えた場合読み込みをそこで終了します。

   .. method:: seek(offset[, whence])

      ストリーム位置を指定された *offset* バイトに変更します。
      *offset* は *whence* で指定された位置からの相対位置として解釈されます。
      *whence* に入力できる値は：

      * ``0`` -- ストリームの最初(デフォルト)です。 *offset* はゼロもしくは正の値です。
      * ``1`` -- 現在のストリーム位置です。 *offset* は負の値です。
      * ``2`` -- ストリームの最後です。 *offset* は通常負の値です。

      新しい絶対位置を返します。

   .. method:: seekable()

      もしストリームがランダムアクセスをサポートしていた場合 ``True`` を返します。
      ``False`` の場合は :meth:`seek`, :meth:`tell`, :meth:`truncate` は :exc:`IOError` を発生させます。

   .. method:: tell()

      現在のストリーム位置を返します。

   .. method:: truncate([size])

      高々 *size* バイトまでファイルを切り詰めます。
      *size* のデフォルト値は現在のファイルの位置で、 :meth:`tell` が返す値と同値です。

   .. method:: writable()

      ストリームが書き込みをサポートしていた場合 ``True`` を返します。
      ``False`` の場合は :meth:`write`, :meth:`truncate` は :exc:`IOError` を返します。

   .. method:: writelines(lines)

      ストリームに複数行書き込みます。
      行区切り文字は付与されないので、書き込む各行の行末には行区切り文字があります。


.. class:: RawIOBase

   生バイナリI/Oへのベースクラスです。 :class:`IOBase` を継承しています。
   パブリックコンストラクタはありません。

   :class:`IOBase` の属性やメソッドに加えて、 RawIOBase は次のメソッドを提供します：

   .. method:: read([n])

      EOF まで、あるいは *n* が指定された場合 *n* バイトまでストリームから\
      すべてのバイトを読み込んで返します。たった1つのシステムコールが呼ばれます。
      既に EOF に達していたら空のバイトオブジェクトが返されます。
      もしオブジェクトがブロックされず読み込むべきデータがない場合は ``None`` が返されます。

   .. method:: readall()

      EOF までストリームからすべてのバイトを読み込みます。
      必要な場合はストリームに対して複数の呼び出しをします。

   .. method:: readinto(b)

      バイト列 *b* に len(b) バイト分読み込み、読み込んだバイト数を返します。

   .. method:: write(b)

      与えられたバイトあるいはバイト列オブジェクト *b* を生のストリームに書き込んで、
      書き込んだバイト数を返します。
      (決して ``len(b)`` よりも小さくなることはありません。
      なぜならはもし書き込みに失敗した場合は :exc:`IOError` が発生するからです)


生ファイルI/O
--------------

.. class:: FileIO(name[, mode])

   :class:`FileIO` はバイトデータを含むファイルを表します。
   :class:`RawIOBase` インタフェースを (そしてしたがって
   :class:`IOBase` インタフェースも) 実装しています。

   *mode* はそれぞれ読み込み(デフォルト)、書き込み、追記を表す
   ``'r'``, ``'w'``, ``'a'`` にすることができます。
   ファイルは書き込みまたは追記モードで開かれたときに存在しなければ作成されます。
   書き込みモードでは存在したファイル内容は消されます。
   読み込みと書き込みを同時に行いたければ ``'+'`` をモードに加えて下さい。

   :class:`IOBase` および :class:`RawIOBase` から継承した属性とメソッドに加えて、
   :class:`FileIO` は以下のデータ属性とメソッドを提供しています:

   .. attribute:: mode

      コンストラクタに渡されたモードです。

   .. attribute:: name

      ファイル名。
      コンストラクタに名前が渡されなかったときはファイルディスクリプタになります。

   .. method:: read([n])

      最大で *n* バイト読み込み、返します。
      システムコールを一度呼び出すだけなので、要求されたより少ないデータが返されることもあります。
      実際に返されたバイト数を得たければ :func:`len` を返されたバイトオブジェクトに対して使って下さい。
      (非ブロッキングモードでは、データが取れなければ ``None`` が返されます。)

   .. method:: readall()

      ファイルの全内容を読み込み、単一のバイトオブジェクトに入れて返します。
      非ブロッキングモードでは直ちに取得できる限りのものが返されます。
      EOF に到達すると、 ``b''`` が返されます。

   .. method:: write(b)

      与えられたバイトあるいはバイト列オブジェクト *b* をファイルに書き込み、
      実際に書き込まれた(バイト)数を返します。
      システムコールを一度呼び出すだけなので、データの一部だけが書き込まれることもあり得ます。

   :class:`FileIO` オブジェクトでは継承された ``readinto()`` メソッドを使うべきではないということを忘れないで下さい。


バッファ付きストリーム
----------------------

.. class:: BufferedIOBase

   バッファリングをサポートするストリームの基底クラスです。
   :class:`IOBase` を継承します。
   パブリックなコンストラクタはありません。

   :class:`RawIOBase` との主な違いは :meth:`read` メソッドが *size*
   引数の省略を許し、 :meth:`readinto` と異なるデフォルト実装を持たないことです。

   さらに、 :meth:`read`, :meth:`readinto`, :meth:`write` が、
   元になる生ストリームが非ブロッキングモードでかつ準備ができていない場合に、
   :exc:`BlockingIOError` を送出するかもしれません。
   対応する"生"バージョンと違って、 ``None`` を返すことはありません。

   通常の実装では :class:`RawIOBase` 実装を継承して実装せず、
   :class:`BufferedWriter` と :class:`BufferedReader` のようにラップすべきです。

   :class:`BufferedIOBase` は :class:`IOBase` からのメソッドに加えて、
   以下のメソッドを提供するかもしくはオーバーライドします:

   .. method:: read([n])

      最大で *n* バイト読み込み、返します。
      引数が省略されるか、 ``None`` か、または負の値であった場合、
      データは EOF に到達するまで読み込まれます。
      ストリームが既に EOF に到達していた場合空の bytes オブジェクトが返されます。

      引数が正で、元になる生ストリームが対話的でなければ、
      複数回の生 read が必要なバイト数を満たすように発行されるかもしれません
      (先に EOF に到達しない限りは)。
      対話的である場合には、最大で一回の raw read しか発行されず、
      短い結果でも EOF に達したことを意味しません。

      元になる生ストリームが呼び出された時点でデータを持っていなければ、
      :exc:`BlockingIOError` が送出されます。

   .. method:: readinto(b)

      len(b) バイトを上限に bytearray *b* に読み込み、何バイト読んだかを返します。

      :meth:`read` と同様、元になる生ストリームに、それが対話的でない限り、
      複数回の read が発行されるかもしれません。

      元になる生ストリームが呼び出された時点でデータを持っていなければ、
      :exc:`BlockingIOError` が送出されます。

   .. method:: write(b)

      与えられた bytes または bytearray オブジェクト *b* を、
      元になる生ストリームに書き込み、書き込まれたバイト数を返します
      (決して ``len(b)`` よりも小さくなることはありません。
      なぜならはもし書き込みに失敗した場合は :exc:`IOError` が発生するからです)

      バッファが満杯で元になる生ストリームが書き込み時点でさらなるデータを受け付けられない場合
      :exc:`BlockingIOError` が送出されます。


.. class:: BytesIO([initial_bytes])

   インメモリの bytes バッファを利用したストリームの実装。
   :class:`BufferedIOBase` を継承します。

   引数 *initial_bytes* は省略可能な bytearray の初期値です。

   :class:`BytesIO` は :class:`BufferedIOBase` または :class:`IOBase`
   からのメソッドに加えて、以下のメソッドを提供するかもしくはオーバーライドします:

   .. method:: getvalue()

      バッファの全内容を保持した ``bytes`` を返します。

   .. method:: read1()

      :class:`BytesIO` においては、このメソッドは :meth:`read` と同じです。

   .. method:: truncate([size])

      高々 *size* バイトまでバッファを切り詰めます。
      *size* のデフォルトは :meth:`tell` で返される現在のストリーム位置です。


.. class:: BufferedReader(raw[, buffer_size])

   読み込み可能でシーケンシャルな :class:`RawIOBase` オブジェクトのバッファです。
   :class:`BufferedIOBase` を継承します。

   このコンストラクタは与えられた *raw* ストリームと *buffer_size* に対し
   :class:`BufferedReader` を生成します。
   *buffer_size* が省略された場合 :data:`DEFAULT_BUFFER_SIZE` が代わりに使われます。

   :class:`BufferedReader` は :class:`BufferedIOBase` または :class:`IOBase`
   からのメソッドに加えて、以下のメソッドを提供するかもしくはオーバーライドします:

   .. method:: peek([n])

      1 (または指定されれば *n*) バイトをバッファから位置を変更せずに読んで返します。
      これを果たすために生ストリームに対して行われる read はただ一度だけです。
      返されるバイト数は、
      最大でもバッファの現在の位置から最後までのバイト列なので、
      要求されたより少なくなるかもしれません。

   .. method:: read([n])

      *n* バイトを読み込んで返します。
      *n* が与えられないかまたは負の値ならば、EOF まで、
      または非ブロッキングモード中で read 呼び出しがブロックされるまでを返します。

   .. method:: read1(n)

      生ストリームに対しただ一度の呼び出しで最大 *n* バイトを読み込んで返します。
      少なくとも 1 バイトがバッファされていれば、バッファされているバイト列だけが返されます。
      それ以外の場合にはちょうど一回生ストリームに read 呼び出しが行われます。


.. class:: BufferedWriter(raw[, buffer_size[, max_buffer_size]])

   書き込み可能でシーケンシャルな :class:`RawIOBase` オブジェクトのバッファです。
   :class:`BufferedIOBase` を継承します。

   このコンストラクタは与えられた書き込み可能な *raw* ストリームに対し
   :class:`BufferedWriter` を生成します。
   *buffer_size* が省略された場合 :data:`DEFAULT_BUFFER_SIZE` がデフォルトになります。
   *max_buffer_size* が省略された場合、バッファサイズの 2 倍がデフォルトになります。

   :class:`BufferedWriter` は :class:`BufferedIOBase` または :class:`IOBase`
   からのメソッドに加えて、以下のメソッドを提供するかもしくはオーバーライドします:

   .. method:: flush()

      バッファに保持されたバイト列を生ストリームに流し込みます。
      生ストリームがブロックした場合 :exc:`BlockingIOError` が送出されます。

   .. method:: write(b)

      bytes または bytearray オブジェクト *b* を生ストリームに書き込み、
      書き込んだバイト数を返します。
      生ストリームがブロックした場合 :exc:`BlockingIOError` が送出されます。


.. class:: BufferedRWPair(reader, writer[, buffer_size[, max_buffer_size]])

   読み書きできる生ストリームのための組み合わされたバッファ付きライターとリーダーです。
   :meth:`read` 系、 :meth:`write` 系メソッド両方ともサポートされます。
   ソケットや両方向パイプに便利です。
   :class:`BufferedIOBase` を継承しています。

   *reader* と *writer* はそれぞれ読み込み可能、書き込み可能な :class:`RawIOBase`
   オブジェクトです。
   *buffer_size* が省略された場合 :data:`DEFAULT_BUFFER_SIZE` がデフォルトになります。
   (バッファ付きライターのための) *max_buffer_size* が省略された場合、バッファサイズの 2 倍がデフォルトになります。

   :class:`BufferedRWPair` は :class:`BufferedIOBase` の全てのメソッドを実装します。


.. class:: BufferedRandom(raw[, buffer_size[, max_buffer_size]])

   ランダムアクセスストリームへのバッファ付きインタフェース。
   :class:`BufferedReader` および :class:`BufferedWriter` を継承しています。

   このコンストラクタは第一引数として与えられるシーク可能な生ストリームに対し、
   リーダーおよびライターを作成します。
   *buffer_size* が省略された場合 :data:`DEFAULT_BUFFER_SIZE` がデフォルトになります。
   (バッファ付きライターのための) *max_buffer_size* が省略された場合、バッファサイズの 2 倍がデフォルトになります。

   :class:`BufferedRandom` は :class:`BufferedReader` や :class:`BufferedWriter`
   にできることは何でもできます。


文字列 I/O
------------

.. class:: TextIOBase

   テキストストリームの基底クラスです。
   このクラスはストリーム I/O への文字と行に基づいたインタフェースを提供します。
   :meth:`readinto` メソッドは Python の文字列が変更不可能なので存在しません。
   :class:`IOBase` を継承します。
   パブリックなコンストラクタはありません。

   :class:`IOBase` から継承した属性とメソッドに加えて、
   :class:`TextIOBase` は以下のデータ属性とメソッドを提供しています:

   .. attribute:: encoding

      エンコーディング名で、ストリームのバイト列を文字列にデコードするとき、
      また文字列をバイト列にエンコードするときに使われます。

   .. attribute:: newlines

      文字列、文字列のタプル、または ``None`` で、改行がどのように読み換えられるかを指定します。

   .. method:: read(n)

      最大 *n* 文字をストリームから読み込み、一つの文字列にして返します。
      *n* が負の値または ``None`` ならば、 EOF まで読みます。

   .. method:: readline()

      改行または EOF まで読み込み、一つの ``str`` を返します。
      ストリームが既に EOF に到達している場合、空文字列が返されます。

   .. method:: write(s)

      文字列 *s* をストリームに書き込み、書き込まれた文字数を返します。


.. class:: TextIOWrapper(buffer[, encoding[, errors[, newline[, line_buffering]]]])

   :class:`BufferedIOBase` 生ストリーム *buffer* 上のバッファ付きテキストストリーム。
   :class:`TextIOBase` を継承します。

   *encoding* にはストリームをデコードしたりそれを使ってエンコードしたりするエンコーディング名を渡します。
   デフォルトは :func:`locale.getpreferredencoding` です。

   *errors* はオプションの文字列でエンコードやデコードの際のエラーをどのように扱うかを指定します。
   エンコードエラーがあったら :exc:`ValueError` 例外を送出させるには
   ``'strict'`` を渡します(デフォルトの ``None`` でも同じです)。
   エラーを無視させるには ``'ignore'`` です。
   (注意しなければならないのはエンコーディングエラーを無視するとデータ喪失につながる可能性があるということです。)
   ``'replace'`` は正常に変換されなかった文字の代わりにマーカ
   (たとえば ``'?'``) を挿入させます。
   書き込み時には ``'xmlcharrefreplace'`` (適切な XML 文字参照に置き換え) や、
   ``'backslashreplace'`` (バックスラッシュによるエスケープシーケンスに置き換え)
   も使えます。
   他にも :func:`codecs.register_error` で登録されたエラー処理名が有効です。

   *newline* は ``None``, ``''``, ``'\n'``, ``'\r'``, ``'\r\n'`` のいずれかです。
   行末の扱いを制御します。
   ``None`` では、ユニバーサルニューラインが有効になります。
   これが有効になると、入力時、行末の ``'\n'``, ``'\r'``, ``'\r\n'`` は ``'\n'``
   に変換されて呼び出し側に返されます。
   逆に出力時は ``'\n'`` がシステムのデフォルト行区切り文字 (:data:`os.linesep`)
   に変換されます。
   *newline* が他の適切な値の場合には、ファイル読み込みの際にその改行で改行されるようになり、
   変換は行われません。
   出力時には ``'\n'`` が *newline* に変換されます。

   *line_buffering* が ``True`` の場合、write への呼び出しが改行文字を含んでいれば
   :meth:`flush` がそれに伴って呼び出されます。

   :class:`TextIOBase` およびその親クラスの属性に加えて、
   :class:`TextIOWrapper` は以下のデータ属性を提供しています:

   .. attribute:: errors

      エンコーディングおよびデコーディングエラーの設定。

   .. attribute:: line_buffering

      行バッファリングが有効かどうか。


.. class:: StringIO([initial_value[, encoding[, errors[, newline]]]])

   テキストのためのインメモリストリーム。
   :class:`TextIOWrapper` を継承します。

   新しい StringIO ストリームを初期値、エンコーディング、エラーの扱い、改行設定から作成します。
   より詳しい情報は :class:`TextIOWrapper` のコンストラクタを参照して下さい。

   :class:`TextIOWrapper` およびその親クラスから継承したメソッドに加えて
   :class:`StringIO` は以下のメソッドを提供しています:

   .. method:: getvalue()

      バッファの全内容を保持した ``str`` を返します。


.. class:: IncrementalNewlineDecoder

   ユニバーサルニューラインモード向けに改行をデコードする補助コーデック。
   :class:`codecs.IncrementalDecoder` を継承します。

