15.2. "io" --- ストリームを扱うコアツール
*****************************************

バージョン 2.6 で追加.

"io" モジュールはストリーム処理を行う Python インタフェースを提供しま
す。 Python 2.x では、これは組み込みの "file" オブジェクトの代わりとし
て提案されていますが、Python 3.x では、これがファイルやストリームのデ
フォルトインタフェースです。

注釈: このモジュールはもともと、Python 3.x のために設計されたものな
  ので、 このドキュメントの中で使われるすべての "bytes" は ("bytes" が
  エイリ アスとなる) "str" 型のことで、すべての "text" は "unicode" 型
  のこと です。さらに、 "io" API では、この 2 つの型は入れ替えられませ
  ん。

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

"IOBase" の拡張は、単純なストリームに対する生のバイト列の読み書きを扱
う "RawIOBase" です。 "FileIO" は、 "RawIOBase" を継承してマシンのファ
イルシステム中のファイルへのインタフェースを提供します。

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

"IOBase" のもう一つのサブクラスである "TextIOBase" は、テキストを表す
バイトストリームを扱い、 "unicode" エンコードやデコードといった処理を
行います。 "TextIOWrapper" はその拡張で、バッファ付き生ストリーム
("BufferedIOBase") へのバッファされたテキストインタフェースです。最後
に "StringIO" は Unicode テキストに対するインメモリストリームです。

引数名は規約に含まれていません。そして "open()" の引数だけがキーワード
引数として用いられることが意図されています。


15.2.1. モジュールインタフェース
================================

io.DEFAULT_BUFFER_SIZE

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

io.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True)

   *file* を開き、対応するストリームを返します。ファイルが開けなかった
   場合、 "IOError" が発生します。

   *file* は開きたいファイルの (絶対、またはカレントワーキングディレク
   トリに対する相対) パス名を示す文字列か、開きたいファイルがラップさ
   れているファイル記述子です。 (ファイル記述子が与えられた場合、
   *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'" が含まれている場合) では、ファイルの内
   容は "unicode" 文字列として返され、バイト列はプラットフォーム依存の
   エンコーディングか、 *encoding* が指定された場合は指定されたエンコ
   ーディングを使ってデコードされます。

   オプションの *buffering* はバッファ用の設定を行う整数値です。 0 を
   設定することでバッファがオフになります (バイナリモードでのみ有効で
   す)。 1 の場合は 1 行ごとのバッファリングを行い (テキストモードでの
   み利用可能です)、 1 より大きい場合は固定サイズチャンクバッファのサ
   イズを表します。 *buffering* 引数が与えられなければ、デフォルトのバ
   ッファリングポリシーは以下のように働きます:

   * バイナリファイルは固定サイズのチャンクでバッファリングされます
     。 バッファサイズは、背後のデバイスの「ブロックサイズ」を決定する
     ヒ ューリスティックを用いて選択され、それが不可能な場合は代わりに
     "DEFAULT_BUFFER_SIZE" が使われます。多くのシステムでは、典型的な
     バッファサイズは 4096 か 8192 バイト長になるでしょう。

   * 「対話的な」テキストファイル ("isatty()" が True を返すファイル
     ) は行バッファリングを使用します。その他のテキストファイルは、上
     で 説明されたバイナリファイルのためのポリシーを使用します。

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

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

   *newline* は *universal newlines* モードがどのように働くかを制御し
   ます (テキストモードでのみはたらきます)。これは "None", "''",
   "'\n'", "'\r'", "'\r\n'" のいずれかです。これは以下のようにはたらき
   ます:

   * ストリームからの入力の読み込み時、*newline* が "None" であれば
     、 ユニバーサル改行モードが有効になります。入力中の行は "'\n'",
     "'\r'", または "'\r\n'" で終端され、呼び出し元に返される前に
     "'\n'" に切り詰められます。"''" なら、ユニバーサル改行モードは有
     効になりますが、行末は翻訳されずに呼び出し元に返されます。その他
     の正当な値なら、入力行は与えられた文字列でのみ終端され、行末は翻
     訳されずに呼び出し元に返されます。

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

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

   "open()" によって返されるファイルオブジェクトの型はモードに依存しま
   す。 "open()" がテキストモードでファイルを開くために使われた場合
   ("'w'"、 "'r'"、 "'wt'"、 "'rt'" など) "TextIOBase" のサブクラス (
   具体的には "TextIOWrapper") が返されます。バッファリングをしてバイ
   ナリモードでファイルを開く場合、 "BufferedIOBase" のサブクラスが返
   されます。具体的なクラスは多様です。もし読み取り専用のバイナリモー
   ドだった場合は "BufferedReader" が返されます。書き込み専用のバイナ
   リモードだった場合は "BufferedWriter" が返されます。読み書き可能な
   バイナリモードの場合は "BufferedRandom" が返されます。バッファリン
   グが無効な場合、raw ストリーム、 "RawIOBase" のサブクラス、
   "FileIO" が返されます。

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

exception io.BlockingIOError

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

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

   characters_written

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

exception io.UnsupportedOperation

   "IOError" と "ValueError" を継承した例外で、ストリームに未サポート
   の操作が行われた場合に発生します。


15.2.2. I/O 基底クラス
======================

class io.IOBase

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

   継承先のクラスが選択的にオーバライドできるように、このクラスは多く
   のメソッドに空の抽象実装をしています。デフォルトの実装では、読み込
   み、書き込み、シークができないファイルを表現します。

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

   ファイルへのバイナリデータの読み書きに用いられる基本型は ("str" と
   しても知られる) "bytes" です。 メソッドの引数によっては "bytearray"
   や bytes 配列の "memoryview" のこともあります。 "readinto()" などの
   ケースでは、 "bytearray" のような書き込み可能オブジェクトが必要です
   。 テキスト I/O クラスは "unicode" データを扱います。

   バージョン 2.7 で変更: 実装は "memoryview" 引数をサポートする必要が
   あります。

   閉じられたストリームに対するメソッド呼び出しは (問い合わせであって
   も) 未定義です。この場合、実装は "IOError" を発生させることがありま
   す。

   "IOBase" (とそのサブクラス) はイテレータプロトコルをサポートします
   。 "IOBase" オブジェクトをイテレートすると、ストリーム内の行が
   yield されます。行は、ストリームが ("bytes" を与える) バイナリスト
   リームか ("unicode" 文字列を与える) テキストストリームかによって、
   少し違う定義がされています。下の "readline()" を参照してください。

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

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

   "IOBase" は以下のデータ属性とメソッドを提供します:

   close()

      このストリームをフラッシュして閉じます。このメソッドはファイルが
      既に閉じられていた場合は特に何の効果もありません。いったんファイ
      ルが閉じられると、すべてのファイルに対する操作 (例えば読み込みや
      書き込み) で "ValueError" が発生します。

      利便性のためにこのメソッドを複数回呼ぶことは許されています。しか
      し、効果があるのは最初の1回だけです。

   closed

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

   fileno()

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

   flush()

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

   isatty()

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

   readable()

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

   readline(limit=-1)

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

      バイナリファイルでは行末文字は常に "b'\n'" となります。テキスト
      ファイルでは、認識される行末文字を選択するために "open()" に対す
      る *newline* 引数が使われます。

   readlines(hint=-1)

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

      "file.readlines()" を呼びださなくても "for line in file: ..." の
      ように、file オブジェクトを直接イテレートすることができることに
      注意してください。

   seek(offset, whence=SEEK_SET)

      ストリーム位置を指定された *offset* バイトに変更します。*offset*
      は *whence* で指定された位置からの相対位置として解釈されます。
      *whence* のデフォルト値は "SEEK_SET" です。 *whence* に指定でき
      る値は:

      * "SEEK_SET" または "0" -- ストリームの先頭 (デフォルト)。
        *offset* は 0 もしくは正の値でなければなりません。

      * "SEEK_CUR" または "1" -- 現在のストリーム位置。 *offset* は
        負 の値も可能です。

      * "SEEK_END" または "2" -- ストリームの末尾。 *offset* は通常
        負 の値です。

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

      バージョン 2.7 で追加: "SEEK_*" 定数

   seekable()

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

   tell()

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

   truncate(size=None)

      指定された *size* バイト (または *size* が指定されなければ現在の
      位置) にストリームをリサイズします。現在のストリーム位置は変更さ
      れません。このリサイズは、現在のファイルサイズを拡大または縮小さ
      せることができます。拡大の場合には、新しいファイル領域の内容はプ
      ラットホームに依存します (ほとんどのシステムでは、追加のバイトが
      0 で埋められます。 Windowsでは不定です)。新しいファイルサイズが
      返されます。

   writable()

      ストリームが書き込みをサポートしている場合 "True" を返します。
      "False" の場合は "write()"、 "truncate()" は "IOError" を返しま
      す。

   writelines(lines)

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

   __del__()

      オブジェクトの破壊の用意をします。このメソッドはインスタンスの
      "close()" メソッドを呼びます。 "IOBase" はこのメソッドのデフォル
      トの実装を提供します

class io.RawIOBase

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

   生のバイナリ I/O は典型的に、下にある OS デバイスや API への、低レ
   ベルなアクセスを提供し、高レベルな基本要素へとカプセル化しようとは
   しません (これはこのページで後述する Buffered I/O や Text I/O に任
   せます)。

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

   read(n=-1)

      オブジェクトを *n* バイトまで読み込み、それを返します。簡単のた
      め、 *n* が指定されていないか -1 なら、 "readall()" が呼び出され
      ます。そうでなければ、システムコール呼び出しが一度だけ行われます
      。既に EOF に達していたら空のバイトオブジェクトが返されます。オ
      ペレーティングシステムコールが返したものがが *n* バイトより少な
      ければ、 *n* バイトより少なく返されることがあります。

      0 バイトが返って、 *n* が 0 でなければ、それはファイルの終端を表
      します。オブジェクトがノンブロッキングモードで、 1 バイトも読み
      込めなければ、 "None" が返されます。

   readall()

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

   readinto(b)

      *b* に最大 len(b) バイト分読み込み、読み込んだバイト数を返します
      。 オブジェクト *b* はメモリ確保済みの書き込み可能なバイト配列、
      "bytearray" もしくは "memoryview" である必要があります。 オブジ
      ェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、
      "None" が返されます。

   write(b)

      *b* を生ストリームに書き込み、書き込んだバイト数を返します。 こ
      のオブジェクト *b* はバイト配列、"bytes" 、 "bytearray" 、
      "memoryview" のいずれかである必要があります。 返り値は、根底の生
      ストリームの性質によって、特にノンブロッキングモードである場合に
      、 "len(b)" より小さくなることがあります。 生ストリームがブロッ
      クされないように設定されていて、かつ1バイトも即座に書き込むこと
      ができない場合は、 "None" が返されます。 このメソッドから返った
      後で呼び出し元は *b* を解放したり変更したりするかもしれないので
      、実装はメソッド呼び出しの間だけ *b* にアクセスすべきです。

class io.BufferedIOBase

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

   "RawIOBase" との主な違いは、メソッド "read()"、 "readinto()" および
   "write()" は 、ことによると複数回のシステムコールを行って、(それぞ
   れ) 要求されただけの入力を読み込もうとしたり与えられた出力の全てを
   消費しようとしたりする点です。

   加えて、元になる生ストリームが非ブロッキングモードでかつ準備ができ
   ていない場合に、これらのメソッドは、 "BlockingIOError" を送出するか
   もしれません。対応する "RawIOBase" バージョンと違って、 "None" を返
   すことはありません。

   さらに、 "read()" メソッドは、 "readinto()" に従うデフォルト実装を
   持ちません。

   通常の "BufferedIOBase" 実装は "RawIOBase" 実装を継承せずに、
   "BufferedWriter" と "BufferedReader" がするようにこれをラップすべき
   です。

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

   raw

      "BufferedIOBase" が扱う根底の生ストリーム ("RawIOBase" インスタ
      ンス) を返します。これは "BufferedIOBase" API には含まれず、よっ
      て実装に含まれないことがあります。

   detach()

      根底の生ストリームをバッファから分離して返します。

      生ストリームが取り外された後、バッファは使用不能状態になります。

      バッファには、 "BytesIO" など、このメソッドで返される単体のスト
      リームという概念を持たないものがあります。これらは
      "UnsupportedOperation" を送出します。

      バージョン 2.7 で追加.

   read(n=-1)

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

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

      元になる生ストリームがノンブロッキングモードで、呼び出された時点
      でデータを持っていなければ、 "BlockingIOError" が送出されます。

   read1(n=-1)

      根底の生ストリームの "read()" メソッドを高々 1 回呼び出し、最大
      で *n* バイト読み込み、返します。これは、 "BufferedIOBase" オブ
      ジェクトの上に独自のバッファリングを実装するときに便利です。

   readinto(b)

      *b* に最大 len(b) バイト分読み込み、読み込んだバイト数を返します
      。 オブジェクト *b* はメモリ確保済みの書き込み可能なバイト配列、
      "bytearray" もしくは "memoryview" である必要があります。

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

      元になる生ストリームがノンブロッキングモードで、呼び出された時点
      でデータを持っていなければ、 "BlockingIOError" が送出されます。

   write(b)

      *b* を書き込み、書き込んだバイト数を返します (これは常に
      "len(b)" と等しいです。なぜなら、もし書き込みに失敗した場合は
      "IOError" が発生するからです)。 このオブジェクト *b* はバイト配
      列、"bytes" 、 "bytearray" 、 "memoryview" のいずれかである必要
      があります。 実際の実装に依って、これらのバイトは根底のストリー
      ムに読めるように書きこまれたり、パフォーマンスとレイテンシの理由
      でバッファに保持されたりします。

      ノンブロッキングモードであるとき、バッファが満杯で根底の生ストリ
      ームが書き込み時点でさらなるデータを受け付けられない場合
      "BlockingIOError" が送出されます。

      このメソッドが戻った後で、呼び出し元は *b* を解放、または変更す
      るかもしれないので、実装はメソッド呼び出しの間だけ *b* にアクセ
      スすべきです。


15.2.3. 生ファイルI/O
=====================

class io.FileIO(name, mode='r', closefd=True)

   "FileIO" はバイトデータを含む OS レベルのファイルを表します。
   "RawIOBase" インタフェースを (したがって "IOBase" インタフェースも)
   実装しています。

   *name* はこの 2 つのいずれかに出来ます:

   * 開くファイルのパスを表す文字列

   * 結果の "FileIO" オブジェクトがアクセスを与える、既存の OS レベ
     ル ファイルディスクリプタの数を表す整数

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

   このクラスの "read()" (正の引数で呼び出されたとき), "readinto()" お
   よび "write()" メソッドは、単にシステムコールを一度呼び出します。

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

   mode

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

   name

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


15.2.4. バッファ付きストリーム
==============================

バッファ付き I/O ストリームは、I/O デバイスに生 I/O より高レベルなイン
タフェースを提供します。

class io.BytesIO([initial_bytes])

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

   省略可能な引数 *initial_bytes* は、初期データを含んだ "bytes" オブ
   ジェクトです。

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

   getvalue()

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

   read1()

      "BytesIO" においては、このメソッドは "read()" と同じです。

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

   読み込み可能でシーケンシャルな "RawIOBase" オブジェクトへの、高レベ
   ルなアクセスを提供するバッファです。 "BufferedIOBase" を継承します
   。このオブジェクトからデータを読み込むとき、根底の生ストリームから
   より大きい量のデータが要求されることがあり、内部バッファに保存され
   ます。バッファされたデータは、続く読み込み時に直接返されます。

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

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

   peek([n])

      位置を進めずにストリームからバイト列を返します。これを果たすため
      に生ストリームに対して行われる read は高々一度だけです。返される
      バイト数は、要求より少ないかもしれませんし、多いかもしれません。

   read([n])

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

   read1(n)

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

   書き込み可能でシーケンシャルな "RawIOBase" オブジェクトへの、高レベ
   ルなアクセスを提供するバッファです。 "BufferedIOBase" を継承します
   。このオブジェクトに書き込むとき、データは通常内部バッファに保持さ
   れます。このバッファは、以下のような種々の状況で根底の "RawIOBase"
   オブジェクトに書きこまれます:

   * 保留中の全データに対してバッファが足りなくなったとき;

   * "flush()" が呼び出されたとき;

   * "seek()" が ("BufferedRandom" オブジェクトに対して) 呼び出され
     た とき;

   * "BufferedWriter" オブジェクトが閉じられたり破棄されたりしたとき
     。

   このコンストラクタは与えられた書き込み可能な *raw* ストリームに対し
   "BufferedWriter" を生成します。 *buffer_size* が省略された場合、
   "DEFAULT_BUFFER_SIZE" がデフォルトになります。

   第三引数 *max_buffer_size* が提供されていますが、使われず、非推奨で
   す。

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

   flush()

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

   write(b)

      *b* を書き込み、書き込んだバイト数を返します。 このオブジェクト
      *b* はバイト配列、"bytes" 、 "bytearray" 、 "memoryview" のいず
      れかである必要があります。 ノンブロッキングモードのときは、バッ
      ファが書き込まれる必要があるところで生ストリームがブロックした場
      合 "BlockingIOError" が送出されます。

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

   ランダムアクセスストリームへのバッファ付きインタフェース。
   "BufferedReader" および "BufferedWriter" を継承し、さらに "seek()"
   および "tell()" をサポートしています。

   このコンストラクタは第一引数として与えられるシーク可能な生ストリー
   ムに対し、リーダーおよびライターを作成します。 *buffer_size* が省略
   された場合、 "DEFAULT_BUFFER_SIZE" がデフォルトになります。

   第三引数 *max_buffer_size* が提供されていますが、使われず、非推奨で
   す。

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

class io.BufferedRWPair(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)

   2つの単方向 "RawIOBase" オブジェクト -- 一つは読み込み可能、他方が
   書き込み可能 -- を組み合わせてバッファ付きの双方向 I/O オブジェクト
   にしたものです。 "BufferedIOBase" を継承しています。

   *reader* と *writer* はそれぞれ読み込み可能、書き込み可能な
   "RawIOBase" オブジェクトです。 *buffer_size* が省略された場合
   "DEFAULT_BUFFER_SIZE" がデフォルトになります。

   第四引数 *max_buffer_size* が提供されていますが、使われず、非推奨で
   す。

   "BufferedRWPair" は、 "UnsupportedOperation" を送出する "detach()"
   を除く、 "BufferedIOBase" の全てのメソッドを実装します。

   警告: "BufferedRWPair" は下層の生ストリームのアクセスを同期しよう
     とはし ません。同じオブジェクトをリーダとライタとして渡してはいけ
     ません 。その場合は代わりに "BufferedRandom" を使用してください。


15.2.5. テキスト I/O
====================

class io.TextIOBase

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

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

   encoding

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

   errors

      このエンコーダやデコーダのエラー設定です。

   newlines

      文字列、文字列のタプル、または "None" で、改行がどのように読み換
      えられるかを指定します。実装や内部コンストラクタのフラグに依って
      、これは利用できないことがあります。

   buffer

      "TextIOBase" が扱う根底のバイナリバッファ ("BufferedIOBase" イン
      スタンス) です。これは "TextIOBase" API には含まれず、よって実装
      に含まれないことがあります。

   detach()

      根底のバイナリバッファを "TextIOBase" から分離して返します。

      根底のバッファが取り外された後、 "TextIOBase" は使用不能状態にな
      ります。

      "TextIOBase" 実装には、 "StringIO" など、根底のバッファという概
      念を持たないものがあります。これらを呼び出すと
      "UnsupportedOperation" を送出します。

      バージョン 2.7 で追加.

   read(n=-1)

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

   readline(limit=-1)

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

      もし *limit* が指定された場合、最大で *limit* バイトが読み込まれ
      ます。

   seek(offset, whence=SEEK_SET)

      指定された *offset* にストリーム位置を変更します。 挙動は
      *whence* 引数によります。 *whence* のデフォルト値は "SEEK_SET"
      です。:

      * "SEEK_SET" または "0": ストリームの先頭からシークします (デ
        フ ォルト)。 *offset* は "TextIOBase.tell()" が返す数か0のどち
        ら かでなければなりません。それ以外の *offset* 値は未定義の挙
        動を 起こします。

      * "SEEK_CUR" または "1": 現在の位置に "シークします"。
        *offset* は 0 でなければなりません。つまり何もしません (他の値
        はサポー トされていません)。

      * "SEEK_END" または "2": ストリーム終端へシークします。
        *offset* は 0 でなければなりません (他の値はサポートされていま
        せん)．

      新しい絶対位置を、不透明な数値で返します。

      バージョン 2.7 で追加: "SEEK_*" 定数.

   tell()

      ストリームの現在位置を不透明な数値で返します。この値は根底のバイ
      ナリストレージ内でのバイト数を表すとは限りません。

   write(s)

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

class io.TextIOWrapper(buffer, encoding=None, errors=None, newline=None, line_buffering=False)

   "BufferedIOBase" バイナリストリーム上のバッファ付きテキストストリー
   ム。 "TextIOBase" を継承します。

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

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

   *newline* は行末をどのように処理するかを制御します 。これは "None",
   "''", "'\n'", "'\r'", "'\r\n'" のいずれかです。これは以下のように働
   きます:

   * ストリームからの入力を読み込んでいる時、*newline* が "None" の
     場 合、*universal newlines* モードが有効になります。入力中の行は
     "'\n'"、"'\r'"、または "'\r\n'" で終わり、呼び出し元に返される前
     に "'\n'" に変換されます。 "''" の場合、ユニバーサル改行モードは
     有効になりますが、行末は変換されずに呼び出し元に返されます。その
     他の合法な値の場合、入力行は与えられた文字列でのみ終わり、行末は
     変換されずに呼び出し元に返されます。

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

   *line_buffering* が "True" の場合、 write への呼び出しが改行文字も
   しくはキャリッジリターンを含んでいれば、暗黙的に "flush()" が呼び出
   されます。

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

   line_buffering

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

class io.StringIO(initial_value=u'', newline=u'\n')

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

   バッファの初期値を *initial_value* で与えることが出来ます。改行変換
   を有効にすると、改行コードは "write()" によってエンコードされます。
   ストリームはバッファの開始位置に配置されます。

   *newline* 引数は "TextIOWrapper" のものと同じように働きます。デフォ
   ルトでは "\n" 文字だけを行末とみなし、また、改行の変換は行いません
   。 *newline* に "None" をセットすると改行コードを全てのプラットフォ
   ームで "\n" で書き込みますが、読み込み時にはそれでもユニバーサル改
   行としてのデコードは実行されます。

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

   getvalue()

      "StringIO" オブジェクトの "close()" メソッドが呼び出される前の、
      任意の時点でのバッファの全内容を含む "unicode" を返します。改行
      コードのデコードは "read()" によって行われますが、これによるスト
      リーム位置の変更は起こりません。

   使用例:

      import io

      output = io.StringIO()
      output.write(u'First line.\n')
      output.write(u'Second line.\n')

      # Retrieve file contents -- this will be
      # u'First line.\nSecond line.\n'
      contents = output.getvalue()

      # Close object and discard memory buffer --
      # .getvalue() will now raise an exception.
      output.close()

class io.IncrementalNewlineDecoder

   改行を *universal newlines* モードにデコードするヘルパーコーデック
   です。 "codecs.IncrementalDecoder" を継承しています。


15.2.6. 進んだ話題
==================

ここで、上述の I/O 実装に関係するいくつかの進んだ話題について議論しま
す。


15.2.6.1. パフォーマンス
------------------------


15.2.6.1.1. バイナリ I/O
~~~~~~~~~~~~~~~~~~~~~~~~

バッファ付き I/O は、ユーザが 1 バイトだけ要求したときでさえ、データを
大きな塊でのみ読み書きします。これにより、オペレーティングシステムのバ
ッファ無し I/O ルーチンを呼び出して実行する非効率性をすべて隠していま
す。その成果は、OS と処理される I/O の種類に本当にとても大きく依存しま
す (例えば、Linux のような現行の OS では、バッファ無しディスク I/O が
バッファ付き I/O と同じくらい早いことがあります)。しかし、最低でも、バ
ッファ付き I/O は予測できるパフォーマンスを提供します。ですから、ほと
んどいつも、バッファ無し I/O より、バッファ付きの I/O を使うほうが望ま
しいです。


15.2.6.1.2. テキスト I/O
~~~~~~~~~~~~~~~~~~~~~~~~

(ファイルなどの) バイナリストレージ上のテキスト I/O は、同じストレージ
上のバイナリ I/O より非常に遅いです。なぜならこれは、文字コーデックを
使った Unicode からバイナリデータへの変換を暗示しているからです。これ
は大量のテキストデータ (例えば非常に大きなログファイル) を扱うときに顕
著に成り得ます。同様に、 "TextIOWrapper.tell()" や
"TextIOWrapper.seek()" はどちらも、使われている復元アルゴリズムのため
に遅くなります。

しかし "StringIO" は、ネイティブなインメモリ Unicode コンテナで、
"BytesIO" と同程度の速度を示します。


15.2.6.2. マルチスレッディング
------------------------------

(Unix における "read(2)" のような) オペレーティングシステムコールの、
それがラッピングしているものがスレッドセーフであるような範囲内では、
"FileIO" オブジェクトもまた、スレッドセーフです。

バイナリバッファ付きオブジェクト ("BufferedReader", "BufferedWriter",
"BufferedRandom" および "BufferedRWPair" のインスタンス) は、その内部
構造をロックを使って保護します。このため、これらを複数のスレッドから同
時に呼び出しても安全です。

"TextIOWrapper" オブジェクトはスレッドセーフではありません。


15.2.6.3. リエントラント性
--------------------------

バイナリバッファ付きオブジェクト ("BufferedReader", "BufferedWriter",
"BufferedRandom" および "BufferedRWPair" のインスタンス) は、リエント
ラントではありません。リエントラントな呼び出しは普通の状況では起こりま
せんが、 I/O を "signal" ハンドラで行なっているときに起こりえます。バ
ッファ化されたオブジェクトに、すでに *同じスレッドから* アクセスされて
いるのにもかかわらず、再び入ろうとすると "RuntimeError" が送出されます
。

"open()" 関数は "TextIOWrapper" 内部のバッファ付きオブジェクトをラップ
するため、テキストファイルにも暗黙に拡張されます。これは、標準ストリー
ムを含むので、組み込み関数 "print()" にも同様に影響します。
