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 のドキュメントで詳しく解説します。

警告

Raw I/O is a low-level interface and methods generally must have their return values checked and be explicitly retried to ensure an operation completes. For instance write() returns the number of bytes written which may be less than the number of bytes provided (a partial write). High-level I/O objects like バイナリ I/O and テキスト I/O implement retry behavior.

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 モード

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 モード default.

EncodingWarning の有効化

Added in version 3.10: 詳しくは PEP 597 を参照してください。

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.

open() や TextIOWrapper に encoding=None を渡す API を提供する場合、text_encoding() を使用すると、API の呼び出し元が encoding を渡さなかったときに EncodingWarning を発生させられます。 ただし、新しい API では UTF-8 をデフォルトにすること (encoding="utf-8") を検討してください。

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

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 を発生させます。 mode と flags は、元の呼び出しの引数から変更または推定されている場合があります。

io.open_code(path)

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

path は str 型の絶対パスでなければなりません。

この関数の動作は、事前に PyFile_SetOpenCodeHook() を呼び出すことで変更できます。 ただし、path が str 型の絶対パスである限り、open_code(path) は常に open(path, 'rb') と同じように動作する必要があります。 動作の変更は、ファイルの追加の検証や前処理を行うことを目的としています。

Added in version 3.8.

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

これは、open() や TextIOWrapper を使用し、encoding=None という引数を持つ呼び出し可能オブジェクトのための補助関数です。

encoding が None でなければ、その値を返します。 それ以外の場合は、UTF-8 モード に応じて "locale" または "utf-8" を返します。

sys.flags.warn_default_encoding が真で encoding が None の場合、この関数は EncodingWarning を発生させます。 stacklevel は警告を発生させる場所を指定します。 例えば次のように使います。

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

この例では、read_text() の呼び出し元に対して EncodingWarning が発生します。

詳しくは Text Encoding を参照してください。

Added in version 3.10.

バージョン 3.11 で変更: UTF-8 モードが有効で encoding が None の場合、text_encoding() は "utf-8" を返すようになりました。

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 を継承してマシンのファイルシステム中のファイルへのインターフェースを提供します。

抽象基底クラス BufferedIOBase は IOBase を拡張します。 このクラスは raw バイナリストリーム (RawIOBase) のバッファリングを扱います。 そのサブクラスである BufferedWriter、BufferedReader、BufferedRWPair は、それぞれ書き込み可能、読み取り可能、読み書き可能な raw バイナリストリームをバッファリングします。 BufferedRandom はシーク可能なストリームにバッファ付きのインターフェースを提供します。 BufferedIOBase の別のサブクラスである BytesIO は、メモリ内のバイト列を扱うストリームです。

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

すべての I/O クラスの抽象基底クラスです。

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

シグネチャが一様でないため、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: ... を使ってファイルオブジェクトを反復処理できます。

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

whence が示す位置から offset バイトだけ移動した位置にストリームの位置を変更し、新しい絶対位置を返します。 whence には次の値を指定できます。

• os.SEEK_SET または 0 -- ストリームの先頭 (デフォルト)。 offset は 0 以上でなければなりません。

• os.SEEK_CUR または 1 -- 現在のストリーム位置。 offset には負の値も指定できます。

• os.SEEK_END または 2 -- ストリームの末尾。 offset は通常、負の値です。

Added in version 3.1: SEEK_* 定数を追加しました。

Added in version 3.3: OS によっては、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

raw バイナリストリームの基底クラスです。 IOBase を継承します。

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

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

read(size=-1, /)

Read up to size bytes from the object and return them. As a convenience, if size is unspecified or -1, all bytes until EOF are returned.

Attempts to make only one system call but will retry if interrupted and the signal handler does not raise an exception (see PEP 475 for the rationale). This means fewer than size bytes may be returned if the operating system call returns fewer than size bytes.

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

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

readall()

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

If 0 bytes are returned this indicates end of file. If the object is in non-blocking mode and the underlying read() returns None indicating no bytes are available, None is returned.

readinto(b, /)

Read bytes into a pre-allocated, writable bytes-like object b, and return the number of bytes read. For example, b might be a bytearray.

If 0 is returned and len(b) is not 0, this indicates end of file. If the object is in non-blocking mode and no bytes are available, None is returned.

write(b, /)

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

警告

This function does not ensure all bytes are written or an exception is thrown. Callers may implement that behavior by checking the return value and, if it is less than the length of b, looping with additional write calls until all unwritten bytes are written. High-level I/O objects like バイナリ I/O and テキスト I/O implement retry behavior.

class io.BufferedIOBase

何らかのバッファリングをサポートするバイナリストリームの基底クラスです。 IOBase を継承します。

RawIOBase との主な違いは、read() と readinto() が要求された量の入力を読み込もうとし、write() が渡されたすべてのデータを書き出そうとする点です。

また、下層の raw ストリームが非ブロッキングモードの場合、操作がブロックすることをシステムが通知すると、write() は BlockingIOError.characters_written を設定した BlockingIOError を送出します。 read() はそれまでに読み込んだデータを返し、データがなければ None を返します。

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

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

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

raw

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

detach()

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

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

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

Added in version 3.1.

read(size=-1, /)

最大 size バイト読み込んで返します。 引数を省略した場合や None または負の値を指定した場合は、可能な限り読み込みます。

要求したバイト数より少ないデータを返す場合があります。 ストリームがすでに EOF に達している場合は、空の bytes オブジェクトを返します。 複数回の読み込みを行うことがあり、特定のエラーが発生した場合には再試行することもあります。 詳しくは os.read() と PEP 475 を参照してください。 返されたバイト数が size 未満でも、EOF が近いとは限りません。

可能な限り読み込む場合、デフォルト実装は、利用できれば raw.readall を使用します (これは RawIOBase.readall() を実装している必要があります)。 そうでなければ、読み込みが None や空の bytes を返すか、再試行できないエラーが発生するまで読み込みを繰り返します。 大部分のストリームでは EOF まで読み込まれますが、非ブロッキングストリームでは後からさらにデータを読み取れるようになる場合があります。

注釈

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, /)

readinto() を呼び出して最大 size バイト読み込み、返します。 EINTR が発生した場合は PEP 475 に従って再試行することがあります。 size が -1 または省略された場合、実装が 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 and implements its low-level access design. This means write() does not guarantee all bytes are written and read() may read less bytes than requested even when more bytes may be present in the underlying file. To get "write all" and "read at least" behavior, use バイナリ I/O.

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

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

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

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

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

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

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

警告

FileIO is a low-level I/O object and members, such as read() and write(), need to have their return values checked explicitly in a retry loop to implement "write all" and "read at least" behavior. High-level I/O objects バイナリ I/O and テキスト I/O implement retry behavior.

バージョン 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 オブジェクトはリサイズやクローズができません。

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)

読み取り可能でシーク不能な RawIOBase の raw バイナリストリームに、高水準のアクセスを提供するバッファ付きバイナリストリームです。 BufferedIOBase を継承します。

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

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

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

peek(size=0, /)

ストリームの位置を進めずにバイト列を返します。 返されるバイト数は、要求したバイト数より少ない場合も多い場合もあります。 下層の raw ストリームが非ブロッキングで、操作を行うとブロックする場合は空のバイト列を返します。

read(size=-1, /)

BufferedReader では io.BufferedIOBase.read() と同じです。

read1(size=-1, /)

BufferedReader では io.BufferedIOBase.read1() と同じです。

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

• flush() が呼び出されたとき。

• BufferedRandom オブジェクトで seek() が要求されたとき。

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

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

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

flush()

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

write(b, /)

bytes-like オブジェクト b を書き込み、書き込んだバイト数を返します。 非ブロッキングモードでは、バッファの書き出しが必要になっても raw ストリームがブロックする場合、BlockingIOError.characters_written を設定した BlockingIOError を送出します。

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffered binary stream implementing BufferedIOBase interfaces providing higher-level access to a seekable RawIOBase raw binary stream.

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

BufferedRandom は、BufferedReader や BufferedWriter でできることをすべて行えます。 さらに、seek() と tell() の実装が保証されています。

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

読み取り用と書き込み用の 2 つのシーク不能な RawIOBase の raw バイナリストリームに、高水準のアクセスを提供するバッファ付きバイナリストリームです。 BufferedIOBase を継承します。

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

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

警告

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

テキスト I/O

class io.TextIOBase

テキストストリームの基底クラスです。 このクラスは、ストリーム I/O に文字単位および行単位のインターフェースを提供します。 IOBase を継承します。

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

encoding

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

errors

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

newlines

これまでに変換した改行の種類を示す文字列、文字列のタプル、または None です。 実装やコンストラクタに渡した初期フラグによっては利用できません。

buffer

TextIOBase が扱う下層のバイナリバッファ (BufferedIOBase または RawIOBase のインスタンス) です。 これは TextIOBase の API の一部ではなく、実装によっては存在しません。

detach()

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

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

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

Added in version 3.1.

read(size=-1, /)

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

readline(size=-1, /)

改行または EOF まで読み込み、1 つの 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 でなければなりません (他の値はサポートされません)。

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

Added in version 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. 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' 文字は与えられた文字列に変換されます。

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 で変更: encoding 引数がダミーのエンコーディング名 "locale" をサポートするようになりました。

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 で変更: encoding="locale" オプションをサポートするようになりました。

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

ストリームの位置を設定します。 新しいストリームの位置を int として返します。

次の引数の組み合わせによる 4 つの操作をサポートします。

• seek(0, SEEK_SET): ストリームの先頭に戻ります。

• seek(cookie, SEEK_SET): 以前の位置を復元します。 cookie は tell() が返した数値で なければなりません。

• seek(0, SEEK_END): ストリームの末尾に進みます。

• seek(0, SEEK_CUR): 現在のストリーム位置を変更しません。

それ以外の引数の組み合わせは無効であり、例外が送出されることがあります。

参考

os.SEEK_SET、os.SEEK_CUR、os.SEEK_END をサポートしました。

tell()

ストリームの位置を不透明な数値として返します。 tell() の戻り値を seek() に渡すと、以前のストリーム位置を復元できます。

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

メモリ内のテキストバッファを使うテキストストリームです。 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()

バッファの全内容を含む str を返します。 改行は read() と同様にデコードされますが、ストリームの位置は変わりません。

使用例:

import io

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

# ファイルの内容を取得する。
# 結果は次のとおり。
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# オブジェクトを閉じ、メモリバッファを破棄する。
# これ以降、.getvalue() は例外を送出する。
output.close()

class io.IncrementalNewlineDecoder

ユニバーサル改行 モード用に改行をデコードする補助コーデックです。 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 は、文字コーデックを使って Unicode とバイナリデータを相互に変換する必要があるため、同じストレージに対するバイナリ I/O より大幅に遅くなります。 大きなログファイルのように大量のテキストデータを扱う場合、この差が目立つことがあります。 また、tell() と seek() も、使用している再構築アルゴリズムのため、かなり低速です。

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

マルチスレッディング

FileIO オブジェクトは、ラップしている OS のシステムコール (Unix の read(2) など) がスレッドセーフな範囲でスレッドセーフです。

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

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

リエントラント性

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

open() 関数はバッファ付きオブジェクトを TextIOWrapper でラップするため、上記の制約はテキストファイルにも当てはまります。 これには標準ストリームも含まれるので、組み込みの print() 関数にも影響します。