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

16.2.1. 概要

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 の別名です。

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

バイナリーストリームを生成する一番簡単な方法は、 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

ストリームがサポートしていない操作を行おうとした時に発生させる、 OSErrorValueError を継承した例外です。

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

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

参考

sys

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

16.2.3. クラス階層

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

注釈

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

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

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

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

もう一つの 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

IOBase から継承したメソッド、 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 です。 bytearray も利用可能で、いくつかのケース (たとえば readinto) では必須です。 テキスト I/O クラスは str データを扱います。

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

IOBase (とそのサブクラス) はイテレータプロトコルをサポートします。 IOBase オブジェクトをイテレートすると、ストリーム内の行が 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(limit=-1)

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

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

readlines(hint=-1)

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

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

seek(offset, whence=SEEK_SET)

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

  • SEEK_SET または 0 – ストリームの先頭 (デフォルト)。 offset は 0 もしくは正の値でなければなりません。

  • SEEK_CUR または 1 – 現在のストリーム位置。 offset は負の値も可能です。

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

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

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

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

seekable()

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

tell()

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

truncate(size=None)

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

writable()

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

writelines(lines)

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

class io.RawIOBase

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

raw バイナリ 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)

bytearray b に最大 len(b) バイト分読み込み、読み込んだバイト数を返します。 オブジェクトがノンブロッキングモードで、 1 バイトも読み込めなければ、 None が返されます。

write(b)

与えられた bytes または bytearray オブジェクト b を raw ストリームに書き込み、書き込んだバイト数を返します。 これは、根底の raw ストリームの性質や、特にノンブロッキングである場合に、 len(b) より小さくなり得ます。 raw ストリームがブロックされないように設定されていて、 1 バイトも読み込めるように書きこまれなければ、 None が返されます。

class io.BufferedIOBase

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

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

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

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

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

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

raw

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

detach()

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

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

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

バージョン 3.1 で追加.

read(n=-1)

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

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

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

read1(n=-1)

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

readinto(b)

bytearray b に最大``len(b)`` バイトを読み込み、読み込んだバイト数を返します。

Like read(), multiple reads may be issued to the underlying raw stream, unless the latter is interactive.

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

write(b)

Write the given bytes or bytearray object, b and return the number of bytes written (never less than len(b), since if the write fails an OSError will be raised). Depending on the actual implementation, these bytes may be readily written to the underlying stream, or held in a buffer for performance and latency reasons.

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

16.2.3.2. raw ファイルI/O

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

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

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

  • 開かれるファイルへのパスを表す文字列または bytes オブジェクト;

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

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

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

A custom opener can be used by passing a callable as opener. The underlying file descriptor for the file object is then obtained by calling opener with (name, flags). opener must return an open file descriptor (passing os.open as opener results in functionality similar to passing None).

See the open() built-in function for examples on using the opener parameter.

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

In addition to the attributes and methods from IOBase and RawIOBase, FileIO provides the following data attributes:

mode

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

name

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

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

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

class io.BytesIO([initial_bytes])

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

引数 initial_bytes は省略可能な bytes データの初期値です。

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

getbuffer()

Return a readable and writable view over the contents of the buffer without copying them. Also, mutating the view will transparently update the contents of the buffer:

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

注釈

As long as the view exists, the BytesIO object cannot be resized.

バージョン 3.2 で追加.

getvalue()

Return bytes containing the entire contents of the buffer.

read1()

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

class io.BufferedReader(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

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

peek([n])

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

read([n])

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

read1(n)

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

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

A buffer providing higher-level access to a writeable, sequential RawIOBase object. It inherits BufferedIOBase. When writing to this object, data is normally placed into an internal buffer. The buffer will be written out to the underlying RawIOBase object under various conditions, including:

  • 未解決のデータに対してバッファが足りなくなったとき

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

  • seek() が (BufferedRandom オブジェクトに対して) 呼び出されたとき;

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

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

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

flush()

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

write(b)

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

class io.BufferedRandom(raw, buffer_size=DEFAULT_BUFFER_SIZE)

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

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

BufferedRandomBufferedReaderBufferedWriter にできることは何でもできます。

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

A buffered I/O object combining two unidirectional RawIOBase objects – one readable, the other writeable – into a single bidirectional endpoint. It inherits BufferedIOBase.

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

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

警告

BufferedRWPair does not attempt to synchronize accesses to its underlying raw streams. You should not pass it the same object as reader and writer; use BufferedRandom instead.

16.2.3.4. テキスト I/O

class io.TextIOBase

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

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

encoding

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

errors

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

newlines

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

buffer

The underlying binary buffer (a BufferedIOBase 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 を送出します。

バージョン 3.1 で追加.

read(n)

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

readline(limit=-1)

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

If limit is specified, at most limit characters will be read.

seek(offset, whence=SEEK_SET)

Change the stream position to the given offset. Behaviour depends on the whence parameter:

  • 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).

Return the new absolute position as an opaque number.

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

tell()

Return the current stream position as an opaque number. The number does not usually represent a number of bytes in the underlying binary storage.

write(s)

Write the string s to the stream and return the number of characters written.

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. It defaults to locale.getpreferredencoding(False).

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

newline controls how line endings are handled. It can be None, '', '\n', '\r', and '\r\n'. It works as follows:

  • When reading input from the stream, if newline is None, universal newlines mode is enabled. Lines in the input can end in '\n', '\r', or '\r\n', and these are translated into '\n' before being returned to the caller. If it is '', universal newlines mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.
  • ストリームへの出力の書き込み時、newlineNone であれば、書かれたすべての '\n' 文字はシステムデフォルトの行セパレータ os.linesep に翻訳されます。 newline'' または '\n' なら、翻訳はなされません。newline がその他の正当な値なら、すべての '\n' 文字は与えられた文字列に翻訳して書き出されます。

line_bufferingTrue の場合、 write への呼び出しが改行文字を含んでいれば flush() がそれに伴って呼び出されます。

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 で変更: The write_through argument has been added.

バージョン 3.3 で変更: The default encoding is now locale.getpreferredencoding(False) instead of locale.getpreferredencoding(). Don’t change temporary the locale encoding using locale.setlocale(), use the current locale encoding instead of the user preferred encoding.

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

line_buffering

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

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

テキストIO のためのインメモリストリーム。

The initial value of the buffer (an empty string by default) can be set by providing initial_value. The newline argument works like that of TextIOWrapper. The default is to consider only \n characters as end of lines and to do no newline translation.

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

getvalue()

StringIO オブジェクトの close() のバッファの全内容を保持した str を返します。

Example usage:

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 codecs.IncrementalDecoder.

16.2.4. パフォーマンス

This section discusses the performance of the provided concrete I/O implementations.

16.2.4.1. バイナリ I/O

By reading and writing only large chunks of data even when the user asks for a single byte, buffered I/O hides any inefficiency in calling and executing the operating system’s unbuffered I/O routines. The gain depends on the OS and the kind of I/O which is performed. For example, on some modern OSes such as Linux, unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however, is that buffered I/O offers predictable performance regardless of the platform and the backing device. Therefore, it is almost always preferable to use buffered I/O rather than unbuffered I/O for binary data.

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. リエントラント性

Binary buffered objects (instances of BufferedReader, BufferedWriter, BufferedRandom and BufferedRWPair) are not reentrant. While reentrant calls will not happen in normal situations, they can arise from doing I/O in a signal handler. If a thread tries to re-enter a buffered object which it is already accessing, a RuntimeError is raised. Note this doesn’t prohibit a different thread from entering the buffered object.

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