io --- ストリームを扱うコアツール¶
ソースコード: Lib/io.py
概要¶
io モジュールは、さまざまな種類の I/O を扱うための Python の主要な機能を提供します。
I/O は大きく テキスト I/O、バイナリ I/O、raw I/O の 3 種類に分かれます。
これらは一般的な分類であり、いずれも背後の記憶媒体としてさまざまなものを使用できます。
これらのいずれかに属する具体的なオブジェクトを ファイルオブジェクト と呼びます。
ストリーム や ファイルライクオブジェクト という呼び方もよく使われます。
それぞれの具象ストリームオブジェクトは、カテゴリとは独立にさまざまな機能を持ちます。 読み込み専用、書き込み専用、読み書き可能のいずれかであり、任意のランダムアクセス (前後の任意の位置へのシーク) ができるものもあれば、ソケットやパイプのようにシーケンシャルアクセスしかできないものもあります。
すべてのストリームは、渡されたデータの型を厳密に扱います。
例えば、バイナリストリームの write() メソッドに str オブジェクトを渡すと TypeError が送出されます。
テキストストリームの write() メソッドに bytes オブジェクトを渡した場合も同様です。
テキスト I/O¶
テキスト I/O は、 str オブジェクトを受け取り、生成します。すなわち、背後にあるストレージがバイト列 (例えばファイルなど) を格納するときは常に、透過的にデータのエンコード・デコードを行ない、オプションでプラットフォーム依存の改行文字変換を行います。
テキストストリームを作る一番簡単な方法は、オプションでエンコーディングを指定して、 open() を利用することです:
f = open("myfile.txt", "r", encoding="utf-8")
StringIO オブジェクトはインメモリーのテキストストリームです:
f = io.StringIO("some initial text data")
注釈
非ブロッキングストリームを扱う場合、ストリームが直ちに操作を実行できないと、テキスト I/O オブジェクトの読み取り操作が BlockingIOError を送出する場合があることに注意してください。
テキストストリームの 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 のドキュメントで詳しく解説します。
テキストのエンコーディング¶
TextIOWrapper と open() のデフォルトのエンコーディングは UTF-8 です。
Python UTF-8 モード が無効な場合、デフォルトのエンコーディングはロケールによって決まります (locale.getencoding())。
参考
- Python UTF-8 モード
Python UTF-8 モードはロケールのエンコーディングを無視し、UTF-8 を強制的に使用します。
- PEP 686
Python 3.15 では Python UTF-8 モード がデフォルトになりました。
EncodingWarning の有効化¶
Added in version 3.10: 詳しくは PEP 597 を参照してください。
デフォルトのエンコーディングが使われている箇所を見つけるには、コマンドラインオプション -X warn_default_encoding を有効にするか、環境変数 PYTHONWARNDEFAULTENCODING を設定します。
これにより、デフォルトのエンコーディングを使用すると EncodingWarning が発生します。
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が発生します。詳しくは テキストのエンコーディング を参照してください。
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 |
継承元 |
スタブメソッド |
Mixin するメソッドとプロパティ |
|---|---|---|---|
|
|
||
|
|
||
|
|
||
|
|
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になります。
- flush()¶
適用可能であればストリームの書き込みバッファをフラッシュします。読み出し専用や非ブロッキングストリームでは何もしません。
- isatty()¶
ストリームが対話的であれば (つまりターミナルや tty デバイスにつながっている場合)
Trueを返します。
- 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, /)¶
ストリームに行のリストを書き込みます。行区切り文字は追加されないので、書き込む各行の行末に行区切り文字を含ませるのが一般的です。
- class io.RawIOBase¶
raw バイナリストリームの基底クラスです。
IOBaseを継承します。生のバイナリストリームは典型的に、背後にある OS デバイスや API への低水準なアクセスを提供し、それらを高水準の基本要素へカプセル化しようとはしません (そのような機能は後述するバッファされたバイナリストリームやテキストストリームのような高水準のクラスで行われます)。
RawIOBaseはIOBaseが提供するメソッドに加えて、以下のメソッドを提供します:- read(size=-1, /)¶
オブジェクトから最大 size バイト読み込んで返します。 便宜上、size が指定されていないか -1 の場合は、EOF までのすべてのバイトを返します。
システムコールを 1 回だけ行おうとしますが、割り込まれた際にシグナルハンドラが例外を送出しなければ再試行します (その理由は PEP 475 を参照してください)。 そのため、OS のシステムコールが size バイト未満を返すと、戻り値も size バイト未満になる場合があります。
size が 0 でないのに 0 バイトが返った場合、それはファイルの終端を表します。オブジェクトがノンブロッキングモードで、1 バイトも読み込めなければ、
Noneが返されます。デフォルトの実装は
readall()とreadinto()に従います。
- readall()¶
EOF までストリームからすべてのバイトを読み込んで返します。 必要な場合はストリームに対して複数の呼び出しをします。
0バイトが返された場合、ファイルの終端を示します。 オブジェクトが非ブロッキングモードで、下層のread()が読み取り可能なバイトがないことを示すNoneを返した場合は、Noneを返します。
- readinto(b, /)¶
事前に確保された書き込み可能な bytes-like オブジェクト b にバイト列を読み込み、読み込んだバイト数を返します。 例えば、b には
bytearrayを使用できます。len(b)が0でないのに0が返された場合、ファイルの終端を示します。 オブジェクトが非ブロッキングモードで、読み取り可能なバイトがない場合はNoneを返します。
- write(b, /)¶
与えられた bytes-like オブジェクト b を生ストリームに書き込み、書き込んだバイト数を返します。これは、根底の生ストリームの性質や、特にノンブロッキングである場合に、 b のバイト数より小さくなることがあります。生ストリームがブロックされないように設定されていて、かつ1バイトも即座に書き込むことができなければ、
Noneが返されます。このメソッドから返った後で呼び出し元は b を解放したり変更したりするかもしれないので、実装はメソッド呼び出しの間だけ b にアクセスすべきです。
- 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インスタンス) を返します。これはBufferedIOBaseAPI には含まれず、よって実装に含まれないことがあります。
- 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 まで読み込まれますが、非ブロッキングストリームでは後からさらにデータを読み取れるようになる場合があります。注釈
下層の raw ストリームが非ブロッキングで、読み取り可能なデータがない場合、実装は
BlockingIOErrorを送出するかNoneを返すことができます。ioの実装はNoneを返します。
- read1(size=-1, /)¶
readinto()を呼び出して最大 size バイト読み込み、返します。EINTRが発生した場合は PEP 475 に従って再試行することがあります。 size が-1または省略された場合、実装が size の値を任意に選びます。注釈
下層の raw ストリームが非ブロッキングで、読み取り可能なデータがない場合、実装は
BlockingIOErrorを送出するかNoneを返すことができます。ioの実装は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 にアクセスすべきです。
raw ファイル I/O¶
- class io.FileIO(name, mode='r', closefd=True, opener=None)¶
バイトデータを含む OS レベルのファイルを表す raw バイナリストリームです。
RawIOBaseを継承し、その低水準のアクセス方式を実装しています。 つまり、write()はすべてのバイトの書き込みを保証せず、read()は下層のファイルにまだデータがあっても要求したバイト数より少ないデータを読み込むことがあります。 「すべて書き込む」「少なくとも指定量を読み込む」という動作が必要な場合は バイナリ 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は低水準の I/O オブジェクトです。 「すべて書き込む」「少なくとも指定量を読み込む」という動作を実現するには、再試行のループでread()やwrite()などのメンバーの戻り値を明示的に確認する必要があります。 高水準の I/O オブジェクトである バイナリ I/O と テキスト I/O は、再試行の処理を実装しています。バージョン 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.
- 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)¶
BufferedIOBaseのインターフェースを実装し、シーク可能なRawIOBaseの raw バイナリストリームに高水準のアクセスを提供するバッファ付きバイナリストリームです。このコンストラクタは第一引数として与えられるシーク可能な生ストリームに対し、リーダーおよびライターを作成します。 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.
- 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 は、ストリームのデコードやエンコードに使用するエンコーディング名を指定します。 デフォルトは UTF-8 ですが、UTF-8 モード が無効な場合は
locale.getencoding()の値になります。encoding="locale"を使うと、現在のロケールのエンコーディングを明示的に指定できます。 詳しくは テキストのエンコーディング を参照してください。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"をサポートするようになりました。注釈
下層の raw ストリームが非ブロッキングで、読み取り操作を直ちに完了できない場合、
BlockingIOErrorが送出されることがあります。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をサポートしました。
- 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 aw+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 ana+mode ready for appending, usef.seek(0, io.SEEK_END)to reposition the stream at the end of the buffer.newline 引数は
TextIOWrapperの同名の引数と同じように働きます。ただし、出力をストリームに書き込む時に newline がNoneの場合には、改行は全てのプラットフォームで\nになります。TextIOBaseとIOBaseから継承したメソッドに加えてStringIOは以下のメソッドを提供しています:使用例:
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を継承します。
静的型付け¶
次のプロトコルを使うと、単純なストリームの読み書きを行う関数やメソッドの引数に注釈を付けられます。
これらには @typing.runtime_checkable デコレータが付いています。
- class io.Reader[T]¶
ファイルやその他の入力ストリームから読み込むためのジェネリックなプロトコルです。
Tは通常strかbytesですが、ストリームから読み込める任意の型を指定できます。Added in version 3.14.
- read()¶
- read(size, /)
入力ストリームからデータを読み込んで返します。 size を指定する場合は整数でなければならず、最大 size 個の項目 (バイトまたは文字) を読み込みます。
例えば:
def read_it(reader: Reader[str]): data = reader.read(11) assert isinstance(data, str)
- class io.Writer[T]¶
ファイルやその他の出力ストリームに書き込むためのジェネリックなプロトコルです。
Tは通常strかbytesですが、ストリームに書き込める任意の型を指定できます。Added in version 3.14.
- write(data, /)¶
出力ストリームに data を書き込み、書き込んだ項目 (バイトまたは文字) の数を返します。
例えば:
def write_binary(writer: Writer[bytes]): writer.write(b"Hello world!\n")
静的型検査に使える他の I/O 関連のプロトコルやクラスについては、入出力を扱うための抽象基底クラスとプロトコル を参照してください。
性能¶
このセクションでは与えられた具体的な 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() 関数にも影響します。