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

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

======================================================================


概要
====

The "io" module provides Python's main facilities for dealing with
various types of I/O.  There are three main types of I/O: *text I/O*,
*binary I/O* and *raw I/O*.  These are generic categories, and various
backing stores can be used for each of them.  A concrete object
belonging to any of these categories is called a *file object*.  Other
common terms are *stream* and *file-like object*.

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

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

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

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

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

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

注釈:

  When working with a non-blocking stream, be aware that read
  operations on text I/O objects might raise a "BlockingIOError" if
  the stream cannot perform the operation immediately.

テキストストリームの 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.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()" の引数だけがキーワー
ド引数として用いられることが意図されています。

The following table summarizes the ABCs provided by the "io" module:

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

   注釈:

     When the underlying raw stream is non-blocking, a
     "BlockingIOError" may be raised if a read operation cannot be
     completed immediately.

   "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".


Static Typing
=============

The following protocols can be used for annotating function and method
arguments for simple stream reading or writing operations. They are
decorated with "@typing.runtime_checkable".

class io.Reader[T]

   Generic protocol for reading from a file or other input stream. "T"
   will usually be "str" or "bytes", but can be any type that is read
   from the stream.

   Added in version 3.14.

   read()
   read(size, /)

      Read data from the input stream and return it. If *size* is
      specified, it should be an integer, and at most *size* items
      (bytes/characters) will be read.

   例えば:

      def read_it(reader: Reader[str]):
          data = reader.read(11)
          assert isinstance(data, str)

class io.Writer[T]

   Generic protocol for writing to a file or other output stream. "T"
   will usually be "str" or "bytes", but can be any type that can be
   written to the stream.

   Added in version 3.14.

   write(data, /)

      Write *data* to the output stream and return the number of items
      (bytes/characters) written.

   例えば:

      def write_binary(writer: Writer[bytes]):
          writer.write(b"Hello world!\n")

See ABCs and Protocols for working with I/O for other I/O related
protocols and classes that can be used for static type checking.


性能
====

このセクションでは与えられた具体的な 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.
