# `io` --- ストリームを扱うコアツール

ソースコード: Lib/io.py

## 概要

`io` モジュールは様々な種類の I/O を扱う Python の主要な機能を提供しています。 I/O には主に3つの種類があります; テキスト I/O, バイナリ I/O, raw I/O です。これらは汎用的なカテゴリで、各カテゴリには様々なストレージが利用されます。これらのいずれかのカテゴリに属する具象オブジェクトは全て file object と呼ばれます。他によく使われる用語として ストリーム と file-like オブジェクト があります。

それぞれの具象ストリームオブジェクトは、カテゴリに応じた機能を持ちます。ストリームは読み込み専用、書き込み専用、読み書き可能のいずかになります。任意のランダムアクセス（前方、後方の任意の場所にシークする）が可能かもしれませんし、シーケンシャルアクセスしかできないかもしれません（例えばソケットやパイプなど）。

全てのストリームは、与えられたデータの型に対して厳密です。例えば、バイナリストリームの `write()` メソッドに対して `str` オブジェクトを渡すと `TypeError` 例外を発生させます。テキストストリームの `write()` メソッドに `bytes` オブジェクトを渡しても同じです。

バージョン 3.3 で変更: 以前 `IOError` を送出していた操作が `OSError` を送出するようになりました。 `IOError` は今は `OSError` の別名です。

### テキスト I/O

テキスト I/O は、 `str` オブジェクトを受け取り、生成します。すなわち、背後にあるストレージがバイト列 (例えばファイルなど) を格納するときは常に、透過的にデータのエンコード・デコードを行ない、オプションでプラットフォーム依存の改行文字変換を行います。

テキストストリームを作る一番簡単な方法は、オプションでエンコーディングを指定して、 `open()` を利用することです:

    f = open("myfile.txt", "r", encoding="utf-8")

`StringIO` オブジェクトはインメモリーのテキストストリームです:

    f = io.StringIO("some initial text data")

テキストストリームの API は `TextIOBase` のドキュメントで詳しく解説します。

### バイナリ I/O

バイナリー I/O (buffered I/O とも呼ばれます) は bytes-like オブジェクト を受け取り `bytes` オブジェクトを生成します。エンコード、デコード、改行文字変換は一切行いません。このカテゴリのストリームは全ての非テキストデータや、テキストデータの扱いを手動で管理したい場合に利用することができます。

バイナリーストリームを生成する一番簡単な方法は、 `open()` の mode 文字列に `'b'` を指定することです:

    f = open("myfile.jpg", "rb")

`BytesIO` はインメモリーのバイナリストリームです:

    f = io.BytesIO(b"some initial binary data: \x00\x01")

バイナリーストリーム API は `BufferedIOBase` のドキュメントで詳しく解説します。

他のライブラリモジュールが、別のテキスト・バイナリーストリームを生成する方法を提供しています。例えば `socket.socket.makefile()` などです。

### Raw I/O

Raw I/O (unbuffered I/O とも呼ばれます) は、バイナリーストリームやテキストストリームの低水準の部品としてよく利用されます。ユーザーコードで直接 raw ストリームを扱うべき場面は滅多にありません。とはいえ、バッファリングを無効にしてファイルをバイナリーモードで開くことで raw ストリームを作ることができます:

    f = open("myfile.jpg", "rb", buffering=0)

raw ストリーム API は `RawIOBase` のドキュメントで詳しく解説します。

## Text Encoding

The default encoding of `TextIOWrapper` and `open()` is locale-specific (`locale.getpreferredencoding(False)`).

However, many developers forget to specify the encoding when opening text files encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc...) since most Unix platforms use UTF-8 locale by default. This causes bugs because the locale encoding is not UTF-8 for most Windows users. For example:

    # May not work on Windows when non-ASCII characters in the file.
    with open("README.md") as f:
        long_description = f.read()

Additionally, while there is no concrete plan as of yet, Python may change the default text file encoding to UTF-8 in the future.

Accordingly, it is highly recommended that you specify the encoding explicitly when opening text files. If you want to use UTF-8, pass `encoding="utf-8"`. To use the current locale encoding, `encoding="locale"` is supported in Python 3.10.

When you need to run existing code on Windows that attempts to open UTF-8 files using the default locale encoding, you can enable the UTF-8 mode. See UTF-8 mode on Windows.

### Opt-in EncodingWarning

バージョン 3.10 で追加: See PEP 597 for more details.

To find where the default locale encoding is used, you can enable the `-X warn_default_encoding` command line option or set the `PYTHONWARNDEFAULTENCODING` environment variable, which will emit an `EncodingWarning` when the default encoding is used.

If you are providing an API that uses `open()` or `TextIOWrapper` and passes `encoding=None` as a parameter, you can use `text_encoding()` so that callers of the API will emit an `EncodingWarning` if they don't pass an `encoding`. However, please consider using UTF-8 by default (i.e. `encoding="utf-8"`) for new APIs.

## 高水準のモジュールインターフェイス

`io.``DEFAULT_BUFFER_SIZE`

  このモジュールの buffered I/O クラスで利用されるデフォルトのバッファーサイズを表す整数です。可能であれば、`open()` は file の blksize (`os.stat()` で取得される) を利用します。

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

  組み込みの `open()` 関数のエイリアスです。

  引数 `path`, `mode`, `flags` を指定して 監査イベント `open` を送出します。

`io.``open_code`(path)

  `'rb'` モードでファイルを開きます。この関数はファイルの中身を実行可能なコードとして扱いたい場合にのみ使用します。

  `path` は `str` 型の絶対パスです。

  この関数の振る舞いは、この関数より以前に `PyFile_SetOpenCodeHook()` を呼び出すことにより上書きされているかもしれません。しかし、 `path` が `str` で絶対パスをあらわすことを前提として、 `open_code(path)` は常に `open(path, 'rb')` と同じように振る舞うべきです。振る舞いの上書きは、ファイルに対する追加の検証や処理を目的とするべきです。

  バージョン 3.8 で追加.

`io.``text_encoding`(encoding, stacklevel=2, /)

  This is a helper function for callables that use `open()` or `TextIOWrapper` and have an `encoding=None` parameter.

  This function returns encoding if it is not `None` and `"locale"` if encoding is `None`.

  This function emits an `EncodingWarning` if `sys.flags.warn_default_encoding` is true and encoding is None. stacklevel specifies where the warning is emitted. For example:

      def read_text(path, encoding=None):
          encoding = io.text_encoding(encoding)  # stacklevel=2
          with open(path, encoding) as f:
              return f.read()

  In this example, an `EncodingWarning` is emitted for the caller of `read_text()`.

  See Text Encoding for more information.

  バージョン 3.10 で追加.

exception `io.``BlockingIOError`

  互換性のための、組み込みの `BlockingIOError` 例外のエイリアスです。

exception `io.``UnsupportedOperation`

  `OSError` と `ValueError` を継承した例外です。ストリームがサポートしていない操作を行おうとした時に送出されます。

参考

`sys`

  標準 IO ストリームを持っています: `sys.stdin`, `sys.stdout`, `sys.stderr`。

## クラス階層

I/O ストリームの実装はクラス階層に分けて整理されています。まずストリームのカテゴリを分類するための 抽象基底クラス (ABC) があり、続いて標準のストリーム実装を行う具象クラス群があります。

> 注釈

> 抽象基底クラス群は、具象ストリームクラスの実装を助けるために、いくつかのデフォルトの実装を提供しています。例えば、 `BufferedIOBase` は `readinto()` と `readline()` の最適化されていない実装を提供しています。

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

`RawIOBase` ABC は `IOBase` を拡張します。このクラスはストリームからの bytes の読み書きを扱います。 `FileIO` は、 `RawIOBase` を継承してマシンのファイルシステム中のファイルへのインターフェースを提供します。

The `BufferedIOBase` ABC extends `IOBase`. It deals with buffering on a raw binary stream (`RawIOBase`). Its subclasses, `BufferedWriter`, `BufferedReader`, and `BufferedRWPair` buffer raw binary streams that are writable, readable, and both readable and writable, respectively. `BufferedRandom` provides a buffered interface to seekable streams. Another `BufferedIOBase` subclass, `BytesIO`, is a stream of in-memory bytes.

`TextIOBase` ABC は `IOBase` を拡張します。このクラスはテキストをあらわすバイトストリームを対象とし、バイトデータと文字列の間のエンコーディングやデコーディングを適切に行います。 `TextIOWrapper` は `TextIOBase` を拡張し、バッファリングされた生のストリーム (`BufferedIOBase`) に対するバッファリングされたテキストのインターフェースです。最後に、 `StringIO` はメモリ上のテキストデータに対するストリームです。

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

次のテーブルは `io` モジュールが提供する ABC の概要です:

ABC | 継承元 | スタブメソッド | Mixin するメソッドとプロパティ
--- | --- | --- | ---
`IOBase` |  | `fileno`, `seek`, `truncate` | `close`, `closed`, `__enter__`, `__exit__`, `flush`, `isatty`, `__iter__`, `__next__`, `readable`, `readline`, `readlines`, `seekable`, `tell`, `writable`, `writelines`
`RawIOBase` | `IOBase` | `readinto`, `write` | `IOBase` から継承したメソッド、 `read`, `readall`
`BufferedIOBase` | `IOBase` | `detach`, `read`, `read1`, `write` | `IOBase` から継承したメソッド、 `readinto`, `readinto1`
`TextIOBase` | `IOBase` | `detach`, `read`, `readline`, `write` | `IOBase` から継承したメソッド、 `encoding`, `errors`, `newlines`

### I/O 基底クラス

class `io.``IOBase`

  The abstract base class for all I/O classes.

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

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

  ファイルへのバイナリデータの読み書きに用いられる基本型は `bytes` です。 他の bytes-like オブジェクト もメソッドの引数として受け付けられます。 テキスト I/O クラスは `str` データを扱います。

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

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

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

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

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

  `close`()

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

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

  `closed`

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

  `fileno`()

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

  `flush`()

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

  `isatty`()

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

  `readable`()

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

  `readline`(size=- 1, /)

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

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

  `readlines`(hint=- 1, /)

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

    引数 hint の値が `0` 以下、および `None` の場合は、ヒントがないものとして取り扱われます。

    ただし、 `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 は通常負の値です。

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

    バージョン 3.1 で追加: `SEEK_*` 定数.

    バージョン 3.3 で追加: 一部のオペレーティングシステムは `os.SEEK_HOLE` や `os.SEEK_DATA` など、追加の値をサポートすることがあります。ファイルに対して利用できる値は、そのファイルがテキストモードで開かれたかバイナリモードで開かれたかに依存します。

  `seekable`()

    ストリームがランダムアクセスをサポートしている場合、 `True` を返します。 `False` の場合、 `seek()`、 `tell()`、 `truncate()` を使用すると `OSError` を発生させます。

  `tell`()

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

  `truncate`(size=None, /)

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

    バージョン 3.5 で変更: Windows で、拡大時に追加領域を 0 で埋めるようになりました。

  `writable`()

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

  `writelines`(lines, /)

    ストリームに行のリストを書き込みます。行区切り文字は追加されないので、書き込む各行の行末に行区切り文字を含ませるのが一般的です。

  `__del__`()

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

class `io.``RawIOBase`

  Base class for raw binary streams. It inherits `IOBase`.

  生のバイナリストリームは典型的に、背後にある OS デバイスや API への低水準なアクセスを提供し、それらを高水準の基本要素へカプセル化しようとはしません (そのような機能は後述するバッファされたバイナリストリームやテキストストリームのような高水準のクラスで行われます)。

  `RawIOBase` は `IOBase` が提供するメソッドに加えて、以下のメソッドを提供します:

  `read`(size=- 1, /)

    オブジェクトを size バイトまで読み込み、それを返します。 簡単のため、 size が指定されていないか -1 の場合は、 EOF までの全てのバイトを返します。 そうでない場合は、システムコール呼び出しが一度だけ行われます。 オペレーティングシステムコールから返ってきたものが size バイトより少なければ、 size バイトより少ない返り値になることがあります。

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

    デフォルトの実装は `readall()` と `readinto()` に従います。

  `readall`()

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

  `readinto`(b, /)

    あらかじめ確保された書き込み可能な bytes 類オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。 例えば、 b は `bytearray` です。 オブジェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、 `None` が返されます。

  `write`(b, /)

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

class `io.``BufferedIOBase`

  Base class for binary streams that support some kind of buffering. It inherits `IOBase`.

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

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

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

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

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

  `raw`

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

  `detach`()

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

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

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

    バージョン 3.1 で追加.

  `read`(size=- 1, /)

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

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

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

  `read1`(size=- 1, /)

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

    size に `-1` （デフォルト値)を指定すると任意バイト長を返します（EOFに到達していなければ返されるバイト数は 0 より大きくなります）

  `readinto`(b, /)

    あらかじめ確保された書き込み可能な bytes 類オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。 例えば、 b は `bytearray` です。

    `read()` と同様に、下層の raw ストリームが対話的でない限り、複数の読み込みは下層の raw ストリームに与えられるかもしれません。

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

  `readinto1`(b, /)

    根底の raw ストリームの `read()` (または `readinto()`) メソッドを高々 1 回呼び出し、あらかじめ確保された書き込み可能な bytes-like オブジェクト b にバイト列を読み込みます。読み込んだバイト数を返します。

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

    バージョン 3.5 で追加.

  `write`(b, /)

    与えられた bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します (これは常に b のバイト数と等しくなります。なぜなら、もし書き込みに失敗した場合は `OSError` が発生するからです)。実際の実装に依存して、これらのバイト列は根底のストリームに即座に書き込まれることもあれば、パフォーマンスやレイテンシの関係でバッファに保持されることもあります。

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

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

### 生ファイルI/O

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

  バイトデータを含む OS レベルのファイルを表現する生のバイナリストリームです。 `RawIOBase` を継承しています。

  name は、次の 2 つのいずれかです。

  - 開くファイルへのパスを表す文字列または `bytes` オブジェクト。 この場合、closefd は `True` (デフォルト) でなければなりません。 `True` でない場合、エラーが送出されます。

  - 結果の `FileIO` オブジェクトがアクセスを与える、既存の OS レベルファイル記述子の数を表す整数。FileIO オブジェクトが閉じられると、closefd が `False` に設定されていない場合、この fd も閉じられます。

  mode は 読み込み（デフォルト）、書き込み、排他的作成、追記に対し `'r'` 、 `'w'` 、 `'x'` 、 `'a'` です。ファイルは書き込みや追記で開かれたときに存在しない場合作成されます。書き込みのときにファイルの内容は破棄されます。作成時に既に存在する場合は `FileExistsError` が送出されます。作成のためにファイルを開くのは暗黙的に書き込みなので、このモードは `'w'` と同じように振る舞います。読み込みと書き込みを同時に許可するにはモードに `'+'` を加えてください。

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

  呼び出し可能オブジェクトを opener として与えることで、カスタムのオープナーが使えます。そしてファイルオブジェクトの基底のファイルディスクリプタは、opener を (name, flags) で呼び出して得られます。opener は開いたファイルディスクリプタを返さなければなりません。 (`os.open` を opener として渡すと、`None` を渡したのと同様の機能になります。)

  新たに作成されたファイルは 継承不可 です。

  opener 引数を使う例については `open()` 組み込み関数を参照してください。

  バージョン 3.3 で変更: opener 引数が追加されました。`'x'` モードが追加されました。

  バージョン 3.4 で変更: ファイルが継承不可になりました。

  `FileIO` は `RawIOBase` と `IOBase` から継承したデータ属性に加えて以下のデータ属性を提供します:

  `mode`

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

  `name`

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

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

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

class `io.``BytesIO`(initial_bytes=b'')

  メモリ上のバイトバッファを利用したバイナリストリームの実装です。 `BufferedIOBase` を継承します。バッファは `close()` メソッドが呼び出された際に破棄されます。

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

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

  `getbuffer`()

    バッファの内容をコピーすることなく、その内容の上に、読み込み及び書き込みが可能なビューを返します。また、このビューを変更すると、バッファの内容は透過的に更新されます:

        >>> b = io.BytesIO(b"abcdef")
        >>> view = b.getbuffer()
        >>> view[2:4] = b"56"
        >>> b.getvalue()
        b'ab56ef'

    注釈

    ビューが存在する限り、`BytesIO` オブジェクトはリサイズやクローズされません。

    バージョン 3.2 で追加.

  `getvalue`()

    バッファの全内容を含む `bytes` を返します。

  `read1`(size=- 1, /)

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

    バージョン 3.7 で変更: size 引数が任意になりました。

  `readinto1`(b, /)

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

    バージョン 3.5 で追加.

class `io.``BufferedReader`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  読み出し可能、シーク不可である生のバイナリストリーム `RawIOBase` に対する高水準なアクセスを提供するバッファされたバイナリストリームです。 `BufferedIOBase` を継承します。

  このオブジェクトからデータを読み出した時、背後にある生のストリームからはより大きな量のデータの読み出しがリクエストされ、内部バッファに読み出したデータが保持されることがあります。バッファされたデータはその後の読み出し処理で直接返すことができます。

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

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

  `peek`(size=0, /)

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

  `read`(size=- 1, /)

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

  `read1`(size=- 1, /)

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

    バージョン 3.7 で変更: size 引数が任意になりました。

class `io.``BufferedWriter`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  書き込み可能、シーク不可である生のバイナリストリーム `RawIOBase` に対する高水準なアクセスを提供するバッファされたバイナリストリームです。 `BufferedIOBase` を継承します。

  このオブジェクトに対して書き込みを行なったとき、データは通常内部バッファに配置されます。バッファは以下に示すさまざまな条件で背後にある `RawIOBase` オブジェクトに書き込まれます:

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

  - `flush()` が呼び出されたとき;

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

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

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

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

  `flush`()

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

  `write`(b, /)

    bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します。ノンブロッキング時、バッファが書き込まれるべきなのに生ストリームがブロックした場合 `BlockingIOError` が送出されます。

class `io.``BufferedRandom`(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  シーク可能な生のバイナリストリーム `RawIOBase` に対する高水準なアクセスを提供するバッファされたバイナリストリームです。 `BufferedReader` と `BufferedWriter` を継承します。

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

  `BufferedRandom` は `BufferedReader` と `BufferedWriter` ができることは何でもできる能力があります。さらに `seek()` と `tell()` が実装されていることが保証されています。

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

  それぞれ読み出し可能、書き込み可能である2つのシーク不可な生のバイナリストリーム `RawIOBase` に対する高水準のアクセスを提供するバッファされたバイナリストリームです。 `BufferedIOBase` を継承します。

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

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

  警告

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

### テキスト I/O

class `io.``TextIOBase`

  Base class for text streams. This class provides a character and line based interface to stream I/O. It inherits `IOBase`.

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

  `encoding`

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

  `errors`

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

  `newlines`

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

  `buffer`

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

  `detach`()

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

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

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

    バージョン 3.1 で追加.

  `read`(size=- 1, /)

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

  `readline`(size=- 1, /)

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

    size が指定された場合、最大 size 文字が読み込まれます。

  `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 でなければなりません (他の値はサポートされていません)．

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

    バージョン 3.1 で追加: `SEEK_*` 定数.

  `tell`()

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

  `write`(s, /)

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

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

  バッファ付きバイナリストリーム `BufferedIOBase` に対する高水準のアクセスを提供するバッファ付きテキストストリームです。 `TextIOBase` を継承しています。

  encoding gives the name of the encoding that the stream will be decoded or encoded with. It defaults to `locale.getpreferredencoding(False)`. `encoding="locale"` can be used to specify the current locale's encoding explicitly. See Text Encoding for more information.

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

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

  - ストリームからの入力を読み込んでいるとき、もし newline が `None` ならば universal newlines モードが有効になります。入力中の行は `'\n'`, `'\r'`, または `'\r\n'` のいずれで終わってもよく、それらは呼び出し元に返される前に``'n'`` に変換されます。 newline が `''` の場合、 universal newlines モードは有効になりますが、行末のコードは変換されずに呼び出し元に返されます。 newline がその他の有効な値の場合は、入力行は与えられた文字列のみで終端され、行末は変換されずに呼び出し元に返されます。

  - ストリームへの出力の書き込み時、newline が `None` の場合、全ての `'\n'` 文字はシステムのデフォルトの行セパレータ `os.linesep` に変換されます。 newline が `''` または `'\n'` の場合は変換されません。newline がその他の正当な値の場合、全ての `'\n'` 文字は与えられた文字列に変換されます。

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

  write_through が `True` の場合、`write()` の呼び出しはバッファされないことが保証されます。 `TextIOWrapper` オブジェクトに書かれた全てのデータは直ちに下層のバイナリ buffer に処理されます。

  バージョン 3.3 で変更: write_through 引数が追加されました。

  バージョン 3.3 で変更: encoding の規定値が `locale.getpreferredencoding()` から `locale.getpreferredencoding(False)` になりました。 `locale.setlocale()` を用いてロケールのエンコーディングを一時的に変更してはいけません。ユーザが望むエンコーディングではなく現在のロケールのエンコーディングを使用してください。

  バージョン 3.10 で変更: The encoding argument now supports the `"locale"` dummy encoding name.

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

  `line_buffering`

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

  `write_through`

    書き込みが、根柢のバイナリバッファに即座に渡されるかどうか。

    バージョン 3.7 で追加.

  `reconfigure`(*, encoding=None, errors=None, newline=None, line_buffering=None, write_through=None)

    このテキストストリームを encoding, errors, newline, line_buffering と write_through を新しい設定として再設定します。

    encoding が指定されており、errors が指定されていないときに、 `errors='strict'` が使われている場合を除き、指定されなかったパラメータは現在の設定が保持されます。

    ストリームからすでにデータが読み出されていた場合、encodingとnewlineは変更できません。一方で、書き込み後にencodingを変更することはできます。

    このメソッドは、新しい設定を適用するまえにストリームをフラッシュします。

    バージョン 3.7 で追加.

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

  インメモリのテキストバッファを使ったテキストストリームです。 `TextIOBase` を継承しています。

  テキストバッファは `close()` メソッドが呼び出されたときに破棄されます。

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

  newline 引数は `TextIOWrapper` の同名の引数と同じように働きます。ただし、出力をストリームに書き込む時に newline が `None` の場合には、改行は全てのプラットフォームで `\n` になります。

  `TextIOBase` と `IOBase` から継承したメソッドに加えて `StringIO` は以下のメソッドを提供しています:

  `getvalue`()

    バッファの全内容を含む `str` を返します。改行コードのデコードは `read()` によって行われますが、これによるストリーム位置の変更は起こりません。

  使用例:

      import io

      output = io.StringIO()
      output.write('First line.\n')
      print('Second line.', file=output)

      # Retrieve file contents -- this will be
      # '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` を継承しています。

## 性能

このセクションでは与えられた具体的な I/O 実装の性能について議論します。

### バイナリ I/O

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

### テキスト I/O

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

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

### マルチスレッディング

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

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

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

### リエントラント性

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

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