# 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()` にも同様に影響します。