16.2. io --- ストリームを扱うコアツール

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

---

16.2.1. 概要

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

Independently of its category, each concrete stream object will also have various capabilities: it can be read-only, write-only, or read-write. It can also allow arbitrary random access (seeking forwards or backwards to any location), or only sequential access (for example in the case of a socket or pipe).

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

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

16.2.1.1. テキスト I/O

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

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

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

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

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

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

16.2.1.2. バイナリ 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() などです。

16.2.1.3. Raw I/O

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

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

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

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

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

exception io.BlockingIOError

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

exception io.UnsupportedOperation

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

16.2.2.1. インメモリー ストリーム

str や bytes-like オブジェクト を、読み書き可能なファイルのように扱うことができます。 StringIO は文字列に対して、テキストモードで開かれたファイルのように使うことができます。 BytesIO はバイナリーモードで開いたファイルのように扱うことができます。この2つのクラスは、読み書き可能で、ランダムアクセス可能です。

参考

sys

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

16.2.3. クラス階層

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

注釈

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

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

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

BufferedIOBase ABC は生のバイトストリーム (RawIOBase) 上にバッファ処理を追加します。そのサブクラスの BufferedWriter, BufferedReader, BufferedRWPair では、 それぞれ読み込み専用、書き込み専用、読み書き可能なストリームをバッファします。 BufferedRandom ではランダムアクセスストリームに対してバッファされたインタフェースを提供します。 BytesIO も BufferedIOBase のサブクラスで、インメモリのバイト列へのシンプルなストリームです。

もう一つの IOBase のサブクラスである TextIOBase ABC は、 テキストを表すバイトストリームを扱い、文字列とのエンコードやデコードといった処理を行います。 TextIOWrapper はその拡張で、バッファ付き raw ストリーム (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	Inherited IOBase methods, readinto
TextIOBase	IOBase	detach, read, readline, write	IOBase から継承したメソッド、 encoding, errors, newlines

16.2.3.1. I/O 基底クラス

class io.IOBase

すべての I/O クラスの抽象基底クラスです。バイトストリームへの操作を行います。パブリックなコンストラクタはありません。

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

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

ファイルへのバイナリデータの読み書きに用いられる基本型は bytes です。他の bytes-like オブジェクト もメソッドの引数として受け付けられます。いくつかのケース、たとえば readinto() では、 bytearray のような書き込み可能なオブジェクトが要求されます。テキスト 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 の値を超えた場合、読み込みをそこで終了します。

ただし、 file.readlines() を呼びださなくても for line in file: ... のように file オブジェクトを直接イテレートすることができます。

seek(offset[, whence])

ストリーム位置を指定された offset バイトに変更します。offset は whence で指定された位置からの相対位置として解釈されます。 whence のデフォルト値は SEEK_SET です。 whence に指定できる値は:

• SEEK_SET または 0 -- ストリームの先頭 (デフォルト)。 offset は 0 もしくは正の値でなければなりません。
• SEEK_CUR または 1 -- 現在のストリーム位置。 offset は負の値も可能です。
• SEEK_END または 2 -- ストリームの末尾。 offset は通常負の値です。

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

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

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

seekable()

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

tell()

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

truncate(size=None)

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

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

writable()

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

writelines(lines)

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

__del__()

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

class io.RawIOBase

生のバイナリ I/O への基底クラスです。 IOBase を継承しています。パブリックコンストラクタはありません。

raw バイナリ I/O は典型的に、下にある OS デバイスや API への低水準のアクセスを提供し、高水準の基本要素へとカプセル化しようとはしません (これはこのページで後述する Buffered I/O や Text I/O に任せます)。

IOBase の属性やメソッドに加えて、 RawIOBase は次のメソッドを提供します:

read(size=-1)

Read up to size bytes from the object and return them. As a convenience, if size is unspecified or -1, readall() is called. Otherwise, only one system call is ever made. Fewer than size bytes may be returned if the operating system call returns fewer than size bytes.

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

readall()

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

readinto(b)

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

write(b)

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

class io.BufferedIOBase

何らかのバッファリングをサポートするバイナリストリームの基底クラスです。 IOBase を継承します。パブリックなコンストラクタはありません。

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

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

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

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

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

raw

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

detach()

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

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

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

バージョン 3.1 で追加.

read(size=-1)

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

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

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

read1(size=-1)

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

readinto(b)

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

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

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

readinto1(b)

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

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

バージョン 3.5 で追加.

write(b)

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

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

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

16.2.3.2. 生ファイルI/O

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

FileIO はバイトデータを含む OS レベルのファイルを表します。 RawIOBase インタフェースを (したがって IOBase インタフェースも) 実装しています。

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

• 開くファイルへのパスを表す文字列または bytes オブジェクト。 この場合、closefd は True (デフォルト) でなければなりません。 True でない場合、エラーが送出されます。
• 結果の FileIO オブジェクトがアクセスを与える、既存の OS レベルファイル記述子の数を表す整数。FileIO オブジェクトが閉じられると、closefd が False に設定されていない場合、この fd も閉じられます。

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

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

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

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

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

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

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

IOBase と RawIOBase の属性やメソッドに加え、FileIO は以下のデータ属性を提供します:

mode

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

name

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

16.2.3.3. バッファ付きストリーム

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

class io.BytesIO([initial_bytes])

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

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

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

getbuffer()

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

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

注釈

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

バージョン 3.2 で追加.

getvalue()

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

read1()

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

readinto1()

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

バージョン 3.5 で追加.

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

読み込み可能でシーケンシャルな RawIOBase オブジェクトへの高水準のアクセスを提供するバッファです。 BufferedIOBase を継承します。このオブジェクトからデータを読み込むとき、より大きい量のデータが根底の raw ストリームから要求され、内部バッファに保存される場合があります。バッファされたデータは、その次の読み込み時に直接返されます。

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

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

peek([size])

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

read([size])

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

read1(size)

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

書き込み可能でシーケンシャルな RawIOBase オブジェクトへの、高レベルなアクセスを提供するバッファです。 BufferedIOBase を継承します。このオブジェクトに書き込むとき、データは通常内部バッファに保持されます。このバッファは、以下のような種々の状況で根底の RawIOBase オブジェクトに書き込まれます。

• 保留中の全データに対してバッファが足りなくなったとき;
• flush() が呼び出されたとき;
• seek() が (BufferedRandom オブジェクトに対して) 呼び出されたとき;
• BufferedWriter オブジェクトが閉じられたり破棄されたりしたとき。

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

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

flush()

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

write(b)

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

ランダムアクセスストリームへのバッファ付きインタフェース。 BufferedReader および BufferedWriter を継承し、さらに seek() および tell() をサポートしています。

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

BufferedRandom は BufferedReader や BufferedWriter にできることは何でもできます。

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

2つの単方向 RawIOBase オブジェクト -- 一つは読み込み可能、他方が書き込み可能 -- を組み合わせてバッファ付きの双方向 I/O オブジェクトにしたものです。 BufferedIOBase を継承しています。

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

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

警告

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

16.2.3.4. テキスト I/O

class io.TextIOBase

テキストストリームの基底クラスです。このクラスはストリーム I/O への文字と行に基づいたインタフェースを提供します。 Python の unicode 文字列は変更不可能なので、 readinto() メソッドは存在しません。 IOBase を継承します。パブリックなコンストラクタはありません。

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

encoding

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

errors

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

newlines

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

buffer

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

detach()

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

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

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

バージョン 3.1 で追加.

read(size)

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

readline(size=-1)

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

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

seek(offset[, whence])

指定された offset にストリーム位置を変更します。 挙動は whence 引数によります。 whence のデフォルト値は SEEK_SET です。:

• SEEK_SET または 0: ストリームの先頭からシークします (デフォルト)。 offset は TextIOBase.tell() が返す数か0のどちらかでなければなりません。それ以外の offset 値は未定義の挙動を起こします。
• SEEK_CUR または 1: 現在の位置に "シークします"。 offset は 0 でなければなりません。つまり何もしません (他の値はサポートされていません)。
• SEEK_END または 2: ストリーム終端へシークします。 offset は 0 でなければなりません (他の値はサポートされていません)．

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

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

tell()

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

write(s)

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

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

BufferedIOBase バイナリストリーム上のバッファ付きテキストストリーム。 TextIOBase を継承します。

encoding はストリームがエンコードやデコードされるエンコード名です。デフォルトは locale.getpreferredencoding(False) です。

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

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

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

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

TextIOBase およびその親クラスの属性に加えて、 TextIOWrapper は以下の属性を提供しています:

line_buffering

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

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

テキストIO のためのインメモリストリーム。テキストバッファは close() メソッドが呼び出された際に破棄されます。

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

newline 引数は TextIOWrapper のものと同じように働きます。デフォルトでは \n 文字だけを行末とみなし、また、改行の変換は行いません。 newline に None をセットすると改行コードを全てのプラットフォームで \n で書き込みますが、読み込み時にはそれでもユニバーサル改行としてのデコードは実行されます。

TextIOBase およびその親クラスから継承したメソッドに加えて StringIO は以下のメソッドを提供しています:

getvalue()

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

使用例:

import io

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

# Retrieve file contents -- this will be
# 'First line.\nSecond line.\n'
contents = output.getvalue()

# Close object and discard memory buffer --
# .getvalue() will now raise an exception.
output.close()

class io.IncrementalNewlineDecoder

改行を universal newlines モードにデコードするヘルパーコーデックです。 codecs.IncrementalDecoder を継承しています。

16.2.4. 性能

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

16.2.4.1. バイナリ I/O

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

16.2.4.2. テキスト I/O

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

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

16.2.4.3. マルチスレッディング

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

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

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

16.2.4.4. リエントラント性

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

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