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

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

## 概要

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

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

All streams are careful about the type of data you give to them. For example giving a `str` object to the `write()` method of a binary stream will raise a `TypeError`. So will giving a `bytes` object to the `write()` method of a text stream.

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

### テキスト I/O

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

The easiest way to create a text stream is with `open()`, optionally specifying an encoding:

    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` オブジェクトを生成します。エンコード、デコード、改行文字変換は一切行いません。このカテゴリのストリームは全ての非テキストデータや、テキストデータの扱いを手動で管理したい場合に利用することができます。

The easiest way to create a binary stream is with `open()` with `'b'` in the mode string:

    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.getencoding()`).

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()

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 since Python 3.10.

参考

Python UTF-8 Mode

  Python UTF-8 Mode can be used to change the default encoding to UTF-8 from locale-specific encoding.

PEP 686

  Python 3.15 will make Python UTF-8 Mode default.

### Opt-in EncodingWarning

Added in version 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()` 関数のエイリアスです。

  This function raises an auditing event `open` with arguments path, mode and flags. The mode and flags arguments may have been modified or inferred from the original call.

io.open_code(path)

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

  path should be a `str` and an absolute path.

  The behavior of this function may be overridden by an earlier call to the `PyFile_SetOpenCodeHook()`. However, assuming that path is a `str` and an absolute path, `open_code(path)` should always behave the same as `open(path, 'rb')`. Overriding the behavior is intended for additional validation or preprocessing of the file.

  Added in version 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`. Otherwise, it returns `"locale"` or `"utf-8"` depending on UTF-8 Mode.

  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.

  Added in version 3.10.

  バージョン 3.11 で変更: `text_encoding()` returns "utf-8" when UTF-8 mode is enabled and encoding is `None`.

exception io.BlockingIOError

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

exception io.UnsupportedOperation

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

参考

`sys`

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

## クラス階層

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

注釈

The abstract base classes also provide default implementations of some methods in order to help implementation of concrete stream classes. For example, `BufferedIOBase` provides unoptimized implementations of `readinto()` and `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.

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

  Even though `IOBase` does not declare `read()` or `write()` because their signatures will vary, implementations and clients should consider those methods part of the interface. Also, implementations may raise a `ValueError` (or `UnsupportedOperation`) when operations they do not support are called.

  ファイルへのバイナリデータの読み書きに用いられる基本型は `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()

    Return `True` if the stream can be read from. If `False`, `read()` will raise `OSError`.

  readline(size=-1, /)

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

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

  readlines(hint=-1, /)

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

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

    Note that it's already possible to iterate on file objects using `for line in file: ...` without calling `file.readlines()`.

  seek(offset, whence=os.SEEK_SET, /)

    Change the stream position to the given byte offset, interpreted relative to the position indicated by whence, and return the new absolute position. Values for whence are:

    - `os.SEEK_SET` or `0` -- start of the stream (the default); offset should be zero or positive

    - `os.SEEK_CUR` or `1` -- current stream position; offset may be negative

    - `os.SEEK_END` or `2` -- end of the stream; offset is usually negative

    Added in version 3.1: The `SEEK_*` constants.

    Added in version 3.3: Some operating systems could support additional values, like `os.SEEK_HOLE` or `os.SEEK_DATA`. The valid values for a file could depend on it being open in text or binary mode.

  seekable()

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

  tell()

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

  truncate(size=None, /)

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

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

  writable()

    Return `True` if the stream supports writing. If `False`, `write()` and `truncate()` will raise `OSError`.

  writelines(lines, /)

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

  __del__()

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

class io.RawIOBase

  Base class for raw binary streams. It inherits from `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 from `IOBase`.

  The main difference with `RawIOBase` is that methods `read()`, `readinto()` and `write()` will try (respectively) to read as much input as requested or to emit all provided data.

  In addition, if the underlying raw stream is in non-blocking mode, when the system returns would block `write()` will raise `BlockingIOError` with `BlockingIOError.characters_written` and `read()` will return data read so far or `None` if no data is available.

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

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

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

  raw

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

  detach()

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

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

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

    Added in version 3.1.

  read(size=-1, /)

    Read and return up to size bytes. If the argument is omitted, `None`, or negative read as much as possible.

    Fewer bytes may be returned than requested. An empty `bytes` object is returned if the stream is already at EOF. More than one read may be made and calls may be retried if specific errors are encountered, see `os.read()` and PEP 475 for more details. Less than size bytes being returned does not imply that EOF is imminent.

    When reading as much as possible the default implementation will use `raw.readall` if available (which should implement `RawIOBase.readall()`), otherwise will read in a loop until read returns `None`, an empty `bytes`, or a non-retryable error. For most streams this is to EOF, but for non-blocking streams more data may become available.

    注釈

    When the underlying raw stream is non-blocking, implementations may either raise `BlockingIOError` or return `None` if no data is available. `io` implementations return `None`.

  read1(size=-1, /)

    Read and return up to size bytes, calling `readinto()` which may retry if `EINTR` is encountered per PEP 475. If size is `-1` or not provided, the implementation will choose an arbitrary value for size.

    注釈

    When the underlying raw stream is non-blocking, implementations may either raise `BlockingIOError` or return `None` if no data is available. `io` implementations return `None`.

  readinto(b, /)

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

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

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

  readinto1(b, /)

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

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

    Added in version 3.5.

  write(b, /)

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

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

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

### 生ファイルI/O

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

  A raw binary stream representing an OS-level file containing bytes data. It inherits from `RawIOBase`.

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

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

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

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

  The `read()` (when called with a positive argument), `readinto()` and `write()` methods on this class will only make one system call.

  呼び出し可能オブジェクトを 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'')

  A binary stream using an in-memory bytes buffer. It inherits from `BufferedIOBase`. The buffer is discarded when the `close()` method is called.

  省略可能な引数 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` オブジェクトはリサイズやクローズされません。

    Added in version 3.2.

  getvalue()

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

  read1(size=-1, /)

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

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

  readinto1(b, /)

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

    Added in version 3.5.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a readable, non seekable `RawIOBase` raw binary stream. It inherits from `BufferedIOBase`.

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

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

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

  peek(size=0, /)

    Return bytes from the stream without advancing the position. The number of bytes returned may be less or more than requested. If the underlying raw stream is non-blocking and the operation would block, returns empty bytes.

  read(size=-1, /)

    In `BufferedReader` this is the same as `io.BufferedIOBase.read()`

  read1(size=-1, /)

    In `BufferedReader` this is the same as `io.BufferedIOBase.read1()`

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a writeable, non seekable `RawIOBase` raw binary stream. It inherits from `BufferedIOBase`.

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

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

  - when `flush()` is called;

  - when a `seek()` is requested (for `BufferedRandom` objects);

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

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

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

  flush()

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

  write(b, /)

    Write the bytes-like object, b, and return the number of bytes written. When in non-blocking mode, a `BlockingIOError` with `BlockingIOError.characters_written` set is raised if the buffer needs to be written out but the raw stream blocks.

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

  A buffered binary stream providing higher-level access to a seekable `RawIOBase` raw binary stream. It inherits from `BufferedReader` and `BufferedWriter`.

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

  `BufferedRandom` is capable of anything `BufferedReader` or `BufferedWriter` can do. In addition, `seek()` and `tell()` are guaranteed to be implemented.

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

  A buffered binary stream providing higher-level access to two non seekable `RawIOBase` raw binary streams---one readable, the other writeable. It inherits from `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 from `IOBase`.

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

  encoding

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

  errors

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

  newlines

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

  buffer

    The underlying binary buffer (a `BufferedIOBase` or `RawIOBase` instance) that `TextIOBase` deals with. This is not part of the `TextIOBase` API and may not exist in some implementations.

  detach()

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

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

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

    Added in version 3.1.

  read(size=-1, /)

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

  readline(size=-1, /)

    Read until newline or EOF and return a single `str`. If the stream is already at EOF, an empty string is returned.

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

  seek(offset, whence=SEEK_SET, /)

    Change the stream position to the given offset. Behaviour depends on the whence parameter. The default value for whence is `SEEK_SET`.

    - `SEEK_SET` or `0`: seek from the start of the stream (the default); offset must either be a number returned by `TextIOBase.tell()`, or zero. Any other offset value produces undefined behaviour.

    - `SEEK_CUR` or `1`: "seek" to the current position; offset must be zero, which is a no-operation (all other values are unsupported).

    - `SEEK_END` or `2`: seek to the end of the stream; offset must be zero (all other values are unsupported).

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

    Added in version 3.1: The `SEEK_*` constants.

  tell()

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

  write(s, /)

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

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

  A buffered text stream providing higher-level access to a `BufferedIOBase` buffered binary stream. It inherits from `TextIOBase`.

  encoding gives the name of the encoding that the stream will be decoded or encoded with. In UTF-8 Mode, this defaults to UTF-8. Otherwise, it defaults to `locale.getencoding()`. `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'` 文字は与えられた文字列に変換されます。

  If line_buffering is `True`, `flush()` is implied when a call to write contains a newline character or a carriage return.

  If write_through is `True`, calls to `write()` are guaranteed not to be buffered: any data written on the `TextIOWrapper` object is immediately handled to its underlying binary 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

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

    Added in version 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を変更することはできます。

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

    Added in version 3.7.

    バージョン 3.11 で変更: The method supports `encoding="locale"` option.

  seek(cookie, whence=os.SEEK_SET, /)

    Set the stream position. Return the new stream position as an `int`.

    Four operations are supported, given by the following argument combinations:

    - `seek(0, SEEK_SET)`: Rewind to the start of the stream.

    - `seek(cookie, SEEK_SET)`: Restore a previous position; cookie must be a number returned by `tell()`.

    - `seek(0, SEEK_END)`: Fast-forward to the end of the stream.

    - `seek(0, SEEK_CUR)`: Leave the current stream position unchanged.

    Any other argument combinations are invalid, and may raise exceptions.

    参考

    `os.SEEK_SET`, `os.SEEK_CUR`, and `os.SEEK_END`.

  tell()

    Return the stream position as an opaque number. The return value of `tell()` can be given as input to `seek()`, to restore a previous stream position.

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

  A text stream using an in-memory text buffer. It inherits from `TextIOBase`.

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

  The initial value of the buffer can be set by providing initial_value. If newline translation is enabled, newlines will be encoded as if by `write()`. The stream is positioned at the start of the buffer which emulates opening an existing file in a `w+` mode, making it ready for an immediate write from the beginning or for a write that would overwrite the initial value. To emulate opening a file in an `a+` mode ready for appending, use `f.seek(0, io.SEEK_END)` to reposition the stream at the end of the buffer.

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

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

  getvalue()

    Return a `str` containing the entire contents of the buffer. Newlines are decoded as if by `read()`, although the stream position is not changed.

  使用例:

      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

  A helper codec that decodes newlines for universal newlines mode. It inherits from `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

Text I/O over a binary storage (such as a file) is significantly slower than binary I/O over the same storage, because it requires conversions between unicode and binary data using a character codec. This can become noticeable handling huge amounts of text data like large log files. Also, `tell()` and `seek()` are both quite slow due to the reconstruction algorithm used.

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

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

`FileIO` objects are thread-safe to the extent that the operating system calls (such as read(2) under Unix) they wrap are thread-safe too.

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

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

### リエントラント性

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

The above implicitly extends to text files, since the `open()` function will wrap a buffered object inside a `TextIOWrapper`. This includes standard streams and therefore affects the built-in `print()` function as well.