15.2. io — ストリームを扱うコアツール

バージョン 2.6 で追加.

io モジュールはストリーム処理を行う Python インタフェースを提供します。 Python 2.x では、これは組み込みの file オブジェクトの代わりとして提案されていますが、Python 3.x では、これがファイルやストリームのデフォルトインタフェースです。

注釈

このモジュールはもともと、Python 3.x のために設計されたものなので、このドキュメントの中で使われるすべての "bytes" は (bytes がエイリアスとなる) str 型のことで、すべての "text" は unicode 型のことです。さらに、 io API では、この 2 つの型は入れ替えられません。

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

IOBase の拡張は、単純なストリームに対する生のバイト列の読み書きを扱う RawIOBase です。 FileIO は、 RawIOBase を継承してマシンのファイルシステム中のファイルへのインタフェースを提供します。

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

IOBase のもう一つのサブクラスである TextIOBase は、テキストを表すバイトストリームを扱い、 unicode エンコードやデコードといった処理を行います。 TextIOWrapper はその拡張で、バッファ付き生ストリーム (BufferedIOBase) へのバッファされたテキストインタフェースです。最後に StringIO は Unicode テキストに対するインメモリストリームです。

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

15.2.1. モジュールインタフェース

io.DEFAULT_BUFFER_SIZE

モジュールのバッファ I/O クラスで使用されるデフォルトのバッファサイズを指定する整数値です。 open() は可能であればファイル全体のサイズ (os.stat() で取得されます) を使用します。

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

file を開き、対応するストリームを返します。ファイルが開けなかった場合、 IOError が発生します。

file は開きたいファイルの (絶対、またはカレントワーキングディレクトリに対する相対) パス名を示す文字列か、開きたいファイルがラップされているファイル記述子です。 (ファイル記述子が与えられた場合、 closefd が False に設定されていない限り、返された I/O オブジェクトが閉じられたときにそのファイル識別子も閉じられます)

mode はオプションの文字列です。これによってファイルをどのようなモードで開くか明示することができます。デフォルトは 'r' でテキストモードで読み取り専用で開くことを指します。他にも 'w' は書き込み専用 (もしファイルが存在していた場合は上書きになります) となり、 'a' では追記モードとなります。 ('a' は いくつかの Unixシステムでは すべての 書き込みがシーク位置に関係なくファイルの末尾に追記されることを意味します) テキストモードでは、もし encoding が指定されていなかった場合、エンコーディングはプラットフォーム依存となります。 (生のバイトデータの読み込みと書き込みはバイナリモードを用いて、 encoding は未指定のままとします) 指定可能なモードは次の表の通りです。

文字	意味
'r'	読み込み用に開く (デフォルト)
'w'	書き込み用に開き、ファイルはまず切り詰められる
'a'	書き込み用に開き、ファイルが存在する場合は末尾に追記する
'b'	バイナリモード
't'	テキストモード (デフォルト)
'+'	ディスクファイルを更新用に開く (読み込み／書き込み)
'U'	ユニバーサル改行モード (後方互換性のためのものです; 新しいコードでは使うべきでありません)

デフォルトモードは 'rt' です (テキストを読み込み専用で開きます)。バイナリのランダムアクセスでは 'w+b' はファイルを開き、ファイルを 0 バイトに切り詰めます。一方で 'r+b' でファイルを開くとサイズの切り詰めは行われません。

Python ではバイナリモードで開かれたファイルとテキストモードで開かれたファイルは区別されます。オペレーティングシステムが区別しない場合でもこの区別は適用されます。バイナリモードで開かれたファイル (つまり mode 引数に 'b' が含まれるとき) では、中身を bytes オブジェクトとして返し、一切のデコードを行いません。テキストモード (デフォルトか mode 引数に 't' が含まれている場合) では、ファイルの内容は unicode 文字列として返され、バイト列はプラットフォーム依存のエンコーディングか、 encoding が指定された場合は指定されたエンコーディングを使ってデコードされます。

オプションの buffering はバッファ用の設定を行う整数値です。 0 を設定することでバッファがオフになります (バイナリモードでのみ有効です)。 1 の場合は 1 行ごとのバッファリングを行い (テキストモードでのみ利用可能です)、 1 より大きい場合は固定サイズチャンクバッファのサイズを表します。 buffering 引数が与えられなければ、デフォルトのバッファリングポリシーは以下のように働きます:

• バイナリファイルは固定サイズのチャンクでバッファリングされます。バッファサイズは、背後のデバイスの「ブロックサイズ」を決定するヒューリスティックを用いて選択され、それが不可能な場合は代わりに DEFAULT_BUFFER_SIZE が使われます。多くのシステムでは、典型的なバッファサイズは 4096 か 8192 バイト長になるでしょう。
• 「対話的な」テキストファイル (isatty() が True を返すファイル) は行バッファリングを使用します。その他のテキストファイルは、上で説明されたバイナリファイルのためのポリシーを使用します。

encoding はファイルのエンコードやデコードに使われるエンコーディングの名前です。このオプションはテキストモードでのみ使用されるべきです。デフォルトエンコーディングはプラットフォーム依存 (locale.getpreferredencoding() が返すもの) ですが、Pythonでサポートされているエンコーディングはどれでも使えます。詳しくは codecs モジュール内のサポートしているエンコーディングのリストを参照してください。

errors はエンコードやデコードの際のエラーをどのように扱うかを指定する文字列で、バイナリモードでは使えません。 'strict' を指定すると、エンコードエラーがあった場合 ValueError 例外が発生します (デフォルトである None は同様の処理を行います)。 'ignore' を指定した場合はエラーを無視します。 'replace' を指定した場合は正常に変換されなかった文字の代わりにマーカ (例えば '?' のような文字) を挿入します。書き込みの際には 'xmlcharrefreplace' (適切なXML文字参照に置き換える) か 'backslashreplace' (バックスラッシュによるエスケープシーケンスに置き換える) のどちらかが使用できます。 codecs.register_error() に登録されている他のエラー処理名も指定できます。

newline は universal newlines モードがどのように働くかを制御します (テキストモードでのみはたらきます)。これは None, '', '\n', '\r', '\r\n' のいずれかです。これは以下のようにはたらきます:

• ストリームからの入力の読み込み時、newline が None であれば、ユニバーサル改行モードが有効になります。入力中の行は '\n', '\r', または '\r\n' で終端され、呼び出し元に返される前に '\n' に切り詰められます。'' なら、ユニバーサル改行モードは有効になりますが、行末は翻訳されずに呼び出し元に返されます。その他の正当な値なら、入力行は与えられた文字列でのみ終端され、行末は翻訳されずに呼び出し元に返されます。
• 出力時、 newline が None の場合は、すべての '\n' 文字はシステムのデフォルト行区切り文字 os.linesep に変換されます。もし newline が '' の場合、変換は起こりません。もし newline に他の適切な値が指定された場合は、 '\n' 文字は与えられた文字に変換されます。

もし closefd が False で、ファイル名ではなくてファイル記述子が与えられていた場合、処理中のファイル記述子はファイルが閉じられた後も開いたままとなります。もしファイル名が与えられていた場合は、 closefd は関係ありません。しかし True でなければなりません (デフォルト値)。

open() によって返されるファイルオブジェクトの型はモードに依存します。 open() がテキストモードでファイルを開くために使われた場合 ('w'、 'r'、 'wt'、 'rt' など) TextIOBase のサブクラス (具体的には TextIOWrapper) が返されます。バッファリングをしてバイナリモードでファイルを開く場合、 BufferedIOBase のサブクラスが返されます。具体的なクラスは多様です。もし読み取り専用のバイナリモードだった場合は BufferedReader が返されます。書き込み専用のバイナリモードだった場合は BufferedWriter が返されます。読み書き可能なバイナリモードの場合は BufferedRandom が返されます。バッファリングが無効な場合、raw ストリーム、 RawIOBase のサブクラス、 FileIO が返されます。

unicode 文字列や bytes 文字列をファイルとして読み書きすることも可能です。 unicode 文字列では StringIO を使えばテキストモードで開いたファイルのように扱えます。 bytes では BytesIO を使えばバイナリモードで開いたファイルのように扱えます。

exception io.BlockingIOError

非ブロッキングストリームでブロック処理が起きた場合に発生するエラーです。 IOError を継承しています。

IOError で持っている属性以外に BlockingIOError では次の属性を持っています。

characters_written

ブロック前にストリームに書き込まれる文字数を保持する整数値です。

exception io.UnsupportedOperation

IOError と ValueError を継承した例外で、ストリームに未サポートの操作が行われた場合に発生します。

15.2.2. I/O 基底クラス

class io.IOBase

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

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

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

ファイルへのバイナリデータの読み書きに用いられる基本型は (str としても知られる) bytes です。メソッドの引数によっては bytearray や bytes 配列の memoryview のこともあります。 readinto() などのケースでは、 bytearray のような書き込み可能オブジェクトが必要です。テキスト I/O クラスは unicode データを扱います。

バージョン 2.7 で変更: 実装は memoryview 引数をサポートする必要があります。

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

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

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

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

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

close()

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

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

closed

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

fileno()

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

flush()

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

isatty()

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

readable()

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

readline(limit=-1)

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

バイナリファイルでは行末文字は常に 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 は通常負の値です。

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

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

seekable()

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

tell()

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

truncate(size=None)

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

writable()

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

writelines(lines)

ストリームに複数行書き込みます。行区切り文字は付与されないので、通常書き込む各行の行末には行区切り文字があります。

__del__()

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

class io.RawIOBase

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

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

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

read(n=-1)

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

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

readall()

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

readinto(b)

b に最大 len(b) バイト分読み込み、読み込んだバイト数を返します。オブジェクト b はメモリ確保済みの書き込み可能なバイト配列、 bytearray もしくは memoryview である必要があります。オブジェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、 None が返されます。

write(b)

b を生ストリームに書き込み、書き込んだバイト数を返します。このオブジェクト b はバイト配列、bytes 、 bytearray 、 memoryview のいずれかである必要があります。返り値は、根底の生ストリームの性質によって、特にノンブロッキングモードである場合に、 len(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 を送出します。

バージョン 2.7 で追加.

read(n=-1)

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

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

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

read1(n=-1)

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

readinto(b)

b に最大 len(b) バイト分読み込み、読み込んだバイト数を返します。オブジェクト b はメモリ確保済みの書き込み可能なバイト配列、 bytearray もしくは memoryview である必要があります。

read() と同様、元になる生ストリームが '対話的' でない限り、複数回の read が発行されるかもしれません。

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

write(b)

b を書き込み、書き込んだバイト数を返します (これは常に len(b) と等しいです。なぜなら、もし書き込みに失敗した場合は IOError が発生するからです)。このオブジェクト b はバイト配列、bytes 、 bytearray 、 memoryview のいずれかである必要があります。実際の実装に依って、これらのバイトは根底のストリームに読めるように書きこまれたり、パフォーマンスとレイテンシの理由でバッファに保持されたりします。

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

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

15.2.3. 生ファイルI/O

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

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

name はこの 2 つのいずれかに出来ます:

• 開くファイルのパスを表す文字列
• 結果の FileIO オブジェクトがアクセスを与える、既存の OS レベルファイルディスクリプタの数を表す整数

mode はそれぞれ読み込み (デフォルト)、書き込み、追記を表す 'r'、 'w'、 'a' にすることができます。ファイルは書き込みまたは追記モードで開かれたときに存在しなければ作成されます。書き込みモードでは存在したファイル内容は消されます。読み込みと書き込みを同時に行いたければ '+' をモードに加えて下さい。

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

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

mode

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

name

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

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

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

class io.BytesIO([initial_bytes])

インメモリの bytes バッファを利用したストリームの実装。 BufferedIOBase を継承します。

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

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

getvalue()

バッファの全内容を保持した bytes を返します。

read1()

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

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

peek([n])

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

read([n])

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

read1(n)

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

第三引数 max_buffer_size が提供されていますが、使われず、非推奨です。

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

flush()

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

write(b)

b を書き込み、書き込んだバイト数を返します。このオブジェクト b はバイト配列、bytes 、 bytearray 、 memoryview のいずれかである必要があります。ノンブロッキングモードのときは、バッファが書き込まれる必要があるところで生ストリームがブロックした場合 BlockingIOError が送出されます。

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

第三引数 max_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 がデフォルトになります。

第四引数 max_buffer_size が提供されていますが、使われず、非推奨です。

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

警告

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

15.2.5. テキスト I/O

class io.TextIOBase

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

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

encoding

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

errors

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

newlines

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

buffer

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

detach()

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

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

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

バージョン 2.7 で追加.

read(n)

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

readline(limit=-1)

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

もし limit が指定された場合、最大で limit バイトが読み込まれます。

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

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

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

tell()

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

write(s)

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

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

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

encoding にはストリームをデコードしたりそれを使ってエンコードしたりするエンコーディング名を渡します。デフォルトは locale.getpreferredencoding() です。

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

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

• ストリームからの入力を読み込んでいる時、newline が None の場合、universal newlines モードが有効になります。入力中の行は '\n'、'\r'、または '\r\n' で終わり、呼び出し元に返される前に '\n' に変換されます。 '' の場合、ユニバーサル改行モードは有効になりますが、行末は変換されずに呼び出し元に返されます。その他の合法な値の場合、入力行は与えられた文字列でのみ終わり、行末は変換されずに呼び出し元に返されます。
• 出力時、 newline が None の場合は、すべての '\n' 文字はシステムのデフォルト行区切り文字 os.linesep に変換されます。もし newline が '' の場合、変換は起こりません。もし newline に他の適切な値が指定された場合は、 '\n' 文字は与えられた文字に変換されます。

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

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

line_buffering

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

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

Unicode テキストのためのインメモリストリーム。 TextIOWrapper を継承します。

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

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

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

getvalue()

StringIO オブジェクトの close() メソッドが呼び出される前の、任意の時点でのバッファの全内容を含む unicode を返します。改行コードのデコードは read() によって行われますが、これによるストリーム位置の変更は起こりません。

使用例:

import io

output = io.StringIO()
output.write(u'First line.\n')
output.write(u'Second line.\n')

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

15.2.6. 進んだ話題

ここで、上述の I/O 実装に関係するいくつかの進んだ話題について議論します。

15.2.6.1. パフォーマンス

15.2.6.1.1. バイナリ I/O

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

15.2.6.1.2. テキスト I/O

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

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

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

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

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

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

15.2.6.3. リエントラント性

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

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