15.2. io —ストリームを操作するためのコアツール—Pythonドキュメント

15.2。 io —ストリームを操作するためのコアツール

バージョン2.6の新機能。

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

ノート

このモジュールは主にPython3.x用に設計されているため、このドキュメントでの「バイト」の使用はすべて str タイプ（bytesはエイリアス）、および「テキスト」のすべての使用は、 unicode タイプを指します。 さらに、これら2つのタイプは、 io APIでは互換性がありません。

I / O階層の最上位には、抽象基本クラス IOBase があります。 ストリームへの基本的なインターフェイスを定義します。 ただし、ストリームへの読み取りと書き込みの間に分離はないことに注意してください。 実装は、特定の操作をサポートしていない場合、IOErrorを発生させることができます。

IOBase の拡張は RawIOBase であり、ストリームへの生バイトの読み取りと書き込みを簡単に処理します。 FileIO サブクラス RawIOBase は、マシンのファイルシステム内のファイルへのインターフェイスを提供します。

BufferedIOBase は、生のバイトストリーム（ RawIOBase ）でのバッファリングを処理します。 そのサブクラスである BufferedWriter 、 BufferedReader 、および BufferedRWPair は、読み取り可能、書き込み可能、および読み取り可能と書き込み可能の両方のバッファーストリームです。 BufferedRandom は、ランダムアクセスストリームへのバッファリングされたインターフェイスを提供します。 BytesIO は、メモリ内バイトの単純なストリームです。

別の IOBase サブクラス TextIOBase は、バイトがテキストを表すストリームを処理し、 unicode 文字列との間のエンコードとデコードを処理します。 それを拡張する TextIOWrapper は、バッファリングされたrawストリーム（ BufferedIOBase ）へのバッファリングされたテキストインターフェイスです。 最後に、 StringIO は、Unicodeテキスト用のメモリ内ストリームです。

引数名は仕様の一部ではなく、 open（）の引数のみがキーワード引数として使用されることを目的としています。

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

io.DEFAULT_BUFFER_SIZE

モジュールのバッファリングされたI / Oクラスによって使用されるデフォルトのバッファサイズを含むint。 open（）は、可能であればファイルのblksize（ os.stat（）で取得）を使用します。

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

ファイルを開き、対応するストリームを返します。 ファイルを開くことができない場合は、IOErrorが発生します。

file は、開くファイルのパス名（現在の作業ディレクトリに対する絶対パス名または相対パス名）を示す文字列、またはラップするファイルの整数ファイル記述子のいずれかです。 （ファイル記述子が指定されている場合、 closefd がFalseに設定されていない限り、返されたI / Oオブジェクトが閉じられると閉じられます。）

mode は、ファイルが開かれるモードを指定するオプションの文字列です。 デフォルトは'r'で、テキストモードで読むことができます。 他の一般的な値は、書き込み用の'w'（ファイルが既に存在する場合はファイルを切り捨てる）、および追加用の'a'（一部の Unixシステムでは、すべてを意味します）です。 は、現在のシーク位置に関係なく、ファイルの末尾に追加を書き込みます）。 テキストモードでは、 encoding が指定されていない場合、使用されるエンコーディングはプラットフォームによって異なります。 （rawバイトの読み取りと書き込みには、バイナリモードを使用し、 encoding は指定しないでください。）使用可能なモードは次のとおりです。

キャラクター	意味
'r'	読み取り用に開く（デフォルト）
'w'	書き込み用に開き、最初にファイルを切り捨てます
'a'	書き込み用に開き、ファイルが存在する場合はファイルの末尾に追加します
'b'	バイナリモード
't'	テキストモード（デフォルト）
'+'	更新（読み取りと書き込み）のためにディスクファイルを開く
'U'	ユニバーサル改行モード（下位互換性のため。新しいコードでは使用しないでください）

デフォルトのモードは'rt'（テキストを読むために開いています）です。 バイナリランダムアクセスの場合、モード'w+b'はファイルを開いて0バイトに切り捨てますが、'r+b'はファイルを切り捨てずに開きます。

Pythonは、基盤となるオペレーティングシステムで開かれていない場合でも、バイナリモードとテキストモードで開かれたファイルを区別します。 バイナリモードで開かれたファイル（モード引数の'b'を含む）は、デコードせずにコンテンツをbytesオブジェクトとして返します。 テキストモード（デフォルト、または't'が mode 引数に含まれている場合）では、ファイルの内容は unicode 文字列として返されます。最初に、プラットフォームに依存するエンコーディングを使用するか、指定されている場合は指定されたエンコーディングを使用してデコードされます。

buffering は、バッファリングポリシーを設定するために使用されるオプションの整数です。 0を渡してバッファリングをオフに切り替え（バイナリモードでのみ許可）、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 は、ユニバーサル改行の動作を制御します（テキストモードにのみ適用されます）。 None、、'\n'、'\r'、および'\r\n'にすることができます。 これは次のように機能します。

• 入力時に、 newline がNoneの場合、ユニバーサル改行モードが有効になります。 入力の行は、'\n'、'\r'、または'\r\n'で終わる可能性があり、これらは呼び出し元に返される前に'\n'に変換されます。 の場合、ユニバーサル改行モードが有効になりますが、行末は変換されずに呼び出し元に返されます。 他の有効な値のいずれかがある場合、入力行は指定された文字列でのみ終了し、行の終了は変換されずに呼び出し元に返されます。

• 出力時に、 newline がNoneの場合、書き込まれた'\n'文字はすべて、システムのデフォルトの行区切り文字 os.linesep に変換されます。 改行がの場合、変換は行われません。 newline が他の有効な値のいずれかである場合、書き込まれた'\n'文字はすべて指定された文字列に変換されます。

closefd がFalseであり、ファイル名ではなくファイル記述子が指定されている場合、ファイルが閉じられても、基になるファイル記述子は開いたままになります。 ファイル名が指定されている場合、 closefd は効果がなく、True（デフォルト）である必要があります。

open（）関数によって返されるファイルオブジェクトのタイプは、モードによって異なります。 open（）を使用してファイルをテキストモードで開く場合（'w'、'r'、'wt'、'rt'など。）、 TextIOBase （具体的には TextIOWrapper ）のサブクラスを返します。 バッファリングを使用してバイナリモードでファイルを開くために使用される場合、返されるクラスは BufferedIOBase のサブクラスです。 正確なクラスは異なります。読み取りバイナリモードでは、 BufferedReader を返します。 書き込みバイナリおよび追加バイナリモードでは、 BufferedWriter を返し、読み取り/書き込みモードでは、 BufferedRandom を返します。 バッファリングが無効になっている場合、生のストリーム、 RawIOBase 、 FileIO のサブクラスが返されます。

unicode またはbytes文字列を読み取りと書き込みの両方のファイルとして使用することもできます。 unicode 文字列の場合、 StringIO はテキストモードで開いたファイルのように使用でき、bytesの場合、 BytesIO は開いたファイルのように使用できますバイナリモードで。

exception io.BlockingIOError

非ブロッキングストリームでブロッキングが発生するとエラーが発生します。 IOErrorを継承します。

IOErrorの属性に加えて、 BlockingIOError には次の1つの属性があります。

characters_written

ストリームがブロックされる前にストリームに書き込まれた文字数を含む整数。

exception io.UnsupportedOperation

サポートされていない操作がストリームで呼び出されたときに発生するIOErrorおよびValueErrorを継承する例外。

15.2.2。 I / O基本クラス

class io.IOBase

バイトのストリームに作用する、すべてのI / Oクラスの抽象基本クラス。 パブリックコンストラクタはありません。

このクラスは、派生クラスが選択的にオーバーライドできる多くのメソッドに空の抽象実装を提供します。 デフォルトの実装は、読み取り、書き込み、またはシークできないファイルを表します。

IOBase はread()、readinto()、またはwrite()を宣言しませんが、それらの署名は異なるため、実装とクライアントはこれらのメソッドをインターフェイスの一部と見なす必要があります。 また、実装がサポートしていない操作が呼び出されると、IOErrorが発生する場合があります。

ファイルからの読み取りまたはファイルへの書き込みに使用される基本的なタイプは、bytes（ str とも呼ばれます）です。 メソッド引数は、バイト配列の bytearray または memoryview の場合もあります。 readinto（）などの場合、 bytearray などの書き込み可能なオブジェクトが必要になります。 テキストI / Oクラスは、 unicode データで機能します。

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

クローズドストリームでのメソッドの呼び出し（問い合わせも含む）は定義されていないことに注意してください。 この場合、実装によってIOErrorが発生する可能性があります。

IOBase（およびそのサブクラス）はイテレータープロトコルをサポートします。つまり、 IOBase オブジェクトは、ストリーム内の行を生成する際に反復できます。 行の定義は、ストリームがバイナリストリーム（bytesを生成）であるか、テキストストリーム（ unicode 文字列を生成）であるかによってわずかに異なります。 以下の readline（）を参照してください。

IOBaseはコンテキストマネージャーでもあるため、 with ステートメントをサポートします。 この例では、 file は、 with ステートメントのスイートが終了した後、例外が発生した場合でも閉じられます。

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

IOBase は、次のデータ属性とメソッドを提供します。

close()

このストリームをフラッシュして閉じます。 ファイルがすでに閉じられている場合、この方法は効果がありません。 ファイルが閉じられると、ファイルに対するすべての操作（例： 読み取りまたは書き込み）は、ValueErrorを発生させます。

便宜上、このメソッドを複数回呼び出すことができます。 ただし、最初の呼び出しのみが効果を発揮します。

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)

ストリームから行のリストを読み取って返します。 ヒントを指定して、読み取る行数を制御できます。これまでのすべての行の合計サイズ（バイト/文字）がヒントを超えると、それ以上の行は読み取られません。

file.readlines()を呼び出さなくても、for line in file: ...を使用してファイルオブジェクトを反復処理することはすでに可能であることに注意してください。

seek(offset, whence=SEEK_SET)

ストリーム位置を指定されたバイトオフセットに変更します。 offset は、 whence で示される位置を基準にして解釈されます。 whence のデフォルト値はSEEK_SETです。 whence の値は次のとおりです。

• SEEK_SETまたは0 –ストリームの開始（デフォルト）。 オフセットはゼロまたは正である必要があります

• SEEK_CURまたは1 –現在のストリーム位置。 オフセットは負の可能性があります

• SEEK_ENDまたは2 –ストリームの終わり。 オフセットは通常負です

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

バージョン2.7の新機能： SEEK_*定数

seekable()

ストリームがランダムアクセスをサポートしている場合は、Trueを返します。 False、 seek（）、 tell（）、および truncate（）の場合、IOErrorが発生します。

tell()

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

truncate(size=None)

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

writable()

ストリームが書き込みをサポートしている場合は、Trueを返します。 Falseの場合、write()および truncate（）はIOErrorを発生させます。

writelines(lines)

行のリストをストリームに書き込みます。 行区切り記号は追加されないため、通常、提供される各行の最後に行区切り記号があります。

__del__()

オブジェクトの破壊に備えます。 IOBase は、インスタンスの close（）メソッドを呼び出すこのメソッドのデフォルトの実装を提供します。

class io.RawIOBase

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

生のバイナリI / Oは通常、基盤となるOSデバイスまたはAPIへの低レベルのアクセスを提供し、高レベルのプリミティブにカプセル化しようとはしません（これは、バッファI / OとテキストI / Oに委ねられます。これについては、後で説明します）。ページ）。

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

read(n=- 1)

オブジェクトから最大 n バイトを読み取り、それらを返します。 便宜上、 n が指定されていないか、-1の場合、 readall（）が呼び出されます。 それ以外の場合、システムコールは1回だけ行われます。 オペレーティングシステムコールが n バイト未満を返す場合、 n バイト未満が返される場合があります。

0バイトが返され、 n が0でない場合、これはファイルの終わりを示します。 オブジェクトが非ブロッキングモードであり、使用可能なバイトがない場合、Noneが返されます。

readall()

必要に応じてストリームへの複数の呼び出しを使用して、ストリームからEOFまでのすべてのバイトを読み取って返します。

readinto(b)

最大len（b）バイトを b に読み込み、読み取ったバイト数を返します。 オブジェクト b は、 bytearray または memoryview のいずれかで、事前に割り当てられた書き込み可能なバイト配列である必要があります。 オブジェクトが非ブロッキングモードであり、使用可能なバイトがない場合、Noneが返されます。

write(b)

b を基になるrawストリームに書き込み、書き込まれたバイト数を返します。 オブジェクト b は、bytes、 bytearray 、または memoryview のいずれかのバイト配列である必要があります。 基になるrawストリームの詳細に応じて、特に非ブロッキングモードの場合、戻り値はlen(b)未満になる可能性があります。 Noneは、生のストリームがブロックしないように設定されていて、1バイトを簡単に書き込むことができない場合に返されます。 呼び出し元は、このメソッドが戻った後に b を解放または変更する可能性があるため、実装はメソッド呼び出し中にのみ b にアクセスする必要があります。

class io.BufferedIOBase

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

RawIOBase との主な違いは、メソッド read（）、 readinto（）、および write（）が（それぞれ）読み取りを試みることです。おそらく複数のシステムコールを行うことを犠牲にして、要求されただけの入力、または指定されたすべての出力を消費します。

さらに、これらのメソッドは、基になるrawストリームが非ブロッキングモードであり、十分なデータを取得または提供できない場合、 BlockingIOError を発生させる可能性があります。 RawIOBase の対応物とは異なり、Noneを返すことはありません。

さらに、 read（）メソッドには、 readinto（）に従うデフォルトの実装がありません。

一般的な BufferedIOBase 実装は、 RawIOBase 実装から継承するべきではありませんが、 BufferedWriter や BufferedReader のようにラップします。

BufferedIOBase は、 IOBase のメソッドと属性に加えて、これらのメソッドと属性を提供またはオーバーライドします。

raw

BufferedIOBase が処理する基になるrawストリーム（ RawIOBase インスタンス）。 これは BufferedIOBase APIの一部ではなく、一部の実装には存在しない可能性があります。

detach()

基になるrawストリームをバッファーから分離し、それを返します。

生のストリームが切り離された後、バッファは使用できない状態になります。

BytesIO などの一部のバッファーには、このメソッドから返される単一のrawストリームの概念がありません。 UnsupportedOperation を発生させます。

バージョン2.7の新機能。

read(n=- 1)

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

引数が正で、基になるrawストリームが対話型でない場合、バイトカウントを満たすために複数のraw読み取りが発行される場合があります（最初にEOFに到達しない限り）。 ただし、インタラクティブなrawストリームの場合、最大で1つのraw読み取りが発行され、短い結果はEOFが差し迫っていることを意味しません。

BlockingIOError は、基になるrawストリームが非ブロッキングモードであり、現在利用可能なデータがない場合に発生します。

read1(n=- 1)

基になるrawストリームの read（）メソッドを最大1回呼び出すだけで、最大 n バイトを読み取って返します。 これは、 BufferedIOBase オブジェクトの上に独自のバッファリングを実装している場合に役立ちます。

readinto(b)

最大len（b）バイトを b に読み込み、読み取ったバイト数を返します。 オブジェクト b は、 bytearray または memoryview のいずれかで、事前に割り当てられた書き込み可能なバイト配列である必要があります。

read（）と同様に、基になるrawストリームが「対話型」でない限り、複数の読み取りが基になるrawストリームに発行される場合があります。

BlockingIOError は、基になるrawストリームが非ブロッキングモードであり、現在利用可能なデータがない場合に発生します。

write(b)

b を書き込み、書き込まれたバイト数を返します（書き込みが失敗すると、IOErrorが発生するため、常にlen(b)と等しくなります）。 オブジェクト b は、bytes、 bytearray 、または memoryview のいずれかのバイト配列である必要があります。 実際の実装に応じて、これらのバイトは、基になるストリームに簡単に書き込まれるか、パフォーマンスと遅延の理由でバッファーに保持される場合があります。

非ブロッキングモードでは、データをrawストリームに書き込む必要があるが、ブロッキングなしですべてのデータを受け入れることができない場合、 BlockingIOError が発生します。

呼び出し元は、このメソッドが戻った後に b を解放または変更する可能性があるため、実装はメソッド呼び出し中にのみ b にアクセスする必要があります。

15.2.3。 RawファイルI / O

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

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

名前は、次の2つのいずれかになります。

• 開かれるファイルへのパスを表す文字列。

• 結果の FileIO オブジェクトがアクセスを許可する既存のOSレベルのファイル記述子の番号を表す整数。

モードは、読み取り（デフォルト）、書き込み、または追加のために'r'、'w'、または'a'にすることができます。 書き込みまたは追加のために開いたときにファイルが存在しない場合、ファイルが作成されます。 書き込み用に開くと切り捨てられます。 モードに'+'を追加して、読み取りと書き込みを同時に実行できるようにします。

このクラスのread()（正の引数で呼び出された場合）、readinto()、およびwrite()メソッドは、1回のシステムコールのみを行います。

IOBase および RawIOBase の属性とメソッドに加えて、 FileIO は次のデータ属性とメソッドを提供します。

mode

コンストラクターで指定されたモード。

name

ファイル名。 これは、コンストラクターで名前が指定されていない場合のファイルのファイル記述子です。

15.2.4。 バッファリングされたストリーム

バッファリングされたI / Oストリームは、生のI / Oよりも高レベルのインターフェイスをI / Oデバイスに提供します。

class io.BytesIO([initial_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ストリームから大量のデータが要求され、内部バッファーに保持される場合があります。 バッファリングされたデータは、その後の読み取りで直接返すことができます。

コンストラクターは、指定された読み取り可能な raw ストリームおよび buffer_size に対して BufferedReader を作成します。 buffer_size を省略すると、 DEFAULT_BUFFER_SIZE が使用されます。

BufferedReader は、 BufferedIOBase および IOBase のメソッドに加えて、これらのメソッドを提供またはオーバーライドします。

peek([n])

位置を進めずにストリームからバイトを返します。 呼び出しを満たすために、生のストリームで最大1回の読み取りが行われます。 返されるバイト数は、要求された数より少ない場合と多い場合があります。

read([n])

n バイトを読み取って返すか、 n が指定されていないか負の場合は、EOFまで、または読み取り呼び出しが非ブロックモードでブロックされるかどうか。

read1(n)

生のストリームを1回呼び出すだけで、最大 n バイトを読み取って返します。 少なくとも1バイトがバッファリングされている場合、バッファリングされたバイトのみが返されます。 それ以外の場合は、生のストリーム読み取り呼び出しが1回行われます。

class io.BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)

書き込み可能なシーケンシャル RawIOBase オブジェクトへの高レベルのアクセスを提供するバッファー。 BufferedIOBase を継承します。 このオブジェクトに書き込む場合、データは通常、内部バッファに保持されます。 バッファは、次のようなさまざまな条件下で、基になる RawIOBase オブジェクトに書き出されます。

• 保留中のすべてのデータに対してバッファが小さくなりすぎた場合。

• flush（）が呼び出されたとき。

• seek()が要求されたとき（ BufferedRandom オブジェクトの場合）。

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

コンストラクターは、指定された書き込み可能な raw ストリームに対して BufferedWriter を作成します。 buffer_size が指定されていない場合、デフォルトで DEFAULT_BUFFER_SIZE になります。

3番目の引数 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()機能をサポートします。

コンストラクターは、最初の引数で指定された、シーク可能なrawストリームのリーダーとライターを作成します。 buffer_size を省略すると、デフォルトで DEFAULT_BUFFER_SIZE になります。

3番目の引数 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 になります。

4番目の引数 max_buffer_size はサポートされていますが、未使用で非推奨です。

BufferedRWPair は、 UnsupportedOperation を発生させる detach（）を除いて、 BufferedIOBase 'のすべてのメソッドを実装します。

警告

BufferedRWPair は、基になるrawストリームへのアクセスを同期しようとしません。 リーダーやライターと同じオブジェクトを渡さないでください。 代わりに BufferedRandom を使用してください。

15.2.5。 テキストI / O

class io.TextIOBase

テキストストリームの基本クラス。 このクラスは、I / OをストリーミングするためのUnicode文字および行ベースのインターフェイスを提供します。 Pythonの unicode 文字列は不変であるため、readinto()メソッドはありません。 IOBase を継承します。 パブリックコンストラクタはありません。

TextIOBase は、 IOBase のものに加えて、これらのデータ属性とメソッドを提供またはオーバーライドします。

encoding

ストリームのバイトを文字列にデコードし、文字列をバイトにエンコードするために使用されるエンコーディングの名前。

errors

デコーダーまたはエンコーダーのエラー設定。

newlines

文字列、文字列のタプル、またはNoneは、これまでに翻訳された改行を示します。 実装と初期コンストラクタフラグによっては、これが利用できない場合があります。

buffer

TextIOBase が処理する基になるバイナリバッファー（ BufferedIOBase インスタンス）。 これは TextIOBase APIの一部ではなく、一部の実装には存在しない可能性があります。

detach()

基になるバイナリバッファを TextIOBase から分離し、それを返します。

基になるバッファがデタッチされた後、 TextIOBase は使用できない状態になります。

StringIO などの一部の TextIOBase 実装には、基になるバッファーの概念がない場合があり、このメソッドを呼び出すと UnsupportedOperation が発生します。

バージョン2.7の新機能。

read(n=- 1)

ストリームから最大 n 文字を読み取り、単一の unicode として返します。 n が負またはNoneの場合、EOFまで読み取ります。

readline(limit=- 1)

改行またはEOFまで読み取り、単一のunicodeを返します。 ストリームがすでにEOFにある場合は、空の文字列が返されます。

limit を指定した場合、最大で limit 文字が読み取られます。

seek(offset, whence=SEEK_SET)

ストリームの位置を指定されたオフセットに変更します。 動作は whence パラメーターによって異なります。 whence のデフォルト値はSEEK_SETです。

• SEEK_SETまたは0：ストリームの先頭からシークします（デフォルト）。 offset は、 TextIOBase.tell（）によって返される数値、またはゼロのいずれかである必要があります。 その他の offset 値は、未定義の動作を生成します。

• SEEK_CURまたは1：現在の位置に「シーク」します。 offset はゼロでなければなりません。これは操作なしです（他のすべての値はサポートされていません）。

• SEEK_ENDまたは2：ストリームの最後までシークします。 offset はゼロでなければなりません（他のすべての値はサポートされていません）。

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

バージョン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 は、エンコードおよびデコードエラーの処理方法を指定するオプションの文字列です。 エンコードエラーがある場合は'strict'を渡してValueError例外を発生させるか（デフォルトのNoneでも同じ効果があります）、エラーを無視するには'ignore'を渡します。 （エンコードエラーを無視すると、データが失われる可能性があることに注意してください。）'replace'を使用すると、データの形式が正しくない場所に置換マーカー（'?'など）が挿入されます。 書き込むときは、'xmlcharrefreplace'（適切なXML文字参照に置き換えます）または'backslashreplace'（バックスラッシュエスケープシーケンスに置き換えます）を使用できます。 codecs.register_error（）に登録されているその他のエラー処理名も有効です。

newline は、行末の処理方法を制御します。 None、、'\n'、'\r'、および'\r\n'にすることができます。 これは次のように機能します。

• 入力時に、改行がNoneの場合、ユニバーサル改行モードが有効になります。 入力の行は、'\n'、'\r'、または'\r\n'で終わる可能性があり、これらは呼び出し元に返される前に'\n'に変換されます。 の場合、ユニバーサル改行モードが有効になりますが、行末は変換されずに呼び出し元に返されます。 他の有効な値のいずれかがある場合、入力行は指定された文字列でのみ終了し、行の終了は変換されずに呼び出し元に返されます。

• 出力時に、 newline がNoneの場合、書き込まれた'\n'文字はすべて、システムのデフォルトの行区切り文字 os.linesep に変換されます。 改行がの場合、変換は行われません。 newline が他の有効な値のいずれかである場合、書き込まれた'\n'文字はすべて指定された文字列に変換されます。

line_buffering がTrueの場合、writeの呼び出しに改行文字またはキャリッジリターンが含まれていると、flush()が暗黙指定されます。

TextIOWrapper は、 TextIOBase とその親の属性に加えて、次の1つの属性を提供します。

line_buffering

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

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

Unicodeテキストのメモリ内ストリーム。 TextIOWrapper を継承します。

バッファの初期値は、 initial_value を指定することで設定できます。 改行変換が有効になっている場合、改行は write（）のようにエンコードされます。 ストリームはバッファの先頭に配置されます。

newline 引数は、 TextIOWrapper の引数と同じように機能します。 デフォルトでは、\n文字のみが行の終わりと見なされ、改行の変換は行われません。 newline がNoneに設定されている場合、すべてのプラットフォームで改行は\nとして書き込まれますが、読み取り時にユニバーサル改行デコードが実行されます。

StringIO は、 TextIOWrapper とその親からのメソッドに加えて、このメソッドを提供します。

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

ユニバーサル改行モードの改行をデコードするヘルパーコーデック。 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は、文字コーデックを使用したUnicodeからバイナリデータへの変換を意味するため、同じストレージでのバイナリI / Oよりも大幅に低速です。 これは、大量のテキストデータ（たとえば、非常に大きなログファイル）を処理する場合に顕著になる可能性があります。 また、TextIOWrapper.tell()とTextIOWrapper.seek()はどちらも、使用されている再構成アルゴリズムのために非常に低速です。

ただし、 StringIO はネイティブのメモリ内Unicodeコンテナであり、 BytesIO と同様の速度を示します。

15.2.6.2。 マルチスレッド

FileIO オブジェクトは、それらがラップしているオペレーティングシステムコール（Unixのread(2)など）がスレッドセーフである限り、スレッドセーフです。

バイナリバッファオブジェクト（ BufferedReader 、 BufferedWriter 、 BufferedRandom 、 BufferedRWPair のインスタンス）は、ロックを使用して内部構造を保護します。 したがって、一度に複数のスレッドからそれらを呼び出すことは安全です。

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

15.2.6.3。 再入可能

バイナリバッファオブジェクト（ BufferedReader 、 BufferedWriter 、 BufferedRandom 、および BufferedRWPair のインスタンス）は再入可能ではありません。 再入可能呼び出しは通常の状況では発生しませんが、 signal ハンドラーでI / Oを実行している場合に発生する可能性があります。 同じスレッドからに既にアクセスされているときに、バッファリングされたオブジェクトを再度入力しようとすると、RuntimeErrorが発生します。

open（）関数はバッファリングされたオブジェクトを TextIOWrapper 内にラップするため、上記は暗黙的にテキストファイルに拡張されます。 これには標準ストリームが含まれるため、組み込み関数 print（）にも影響します。