バージョン 2.6 で追加.
io モジュールはストリーム処理をする Python インタフェースを提供します。 組み込み関数 open() はこのモジュールで定義されています。
I/O 階層の最上位には抽象基底クラスの IOBase があります。 IOBase ではストリームに対して基本的なインタフェースを定義しています。 しかしながら、ストリームの読みと書きの間に違いがないことに留意してください。 実装においては与えられた操作をサポートしない場合は IOError を投げることが許されています。
IOBase の拡張は生のバイト列の読み書きをしてストリームに落とす処理を単純に扱う RawIOBase です。 FileIO は RawIOBase を継承してマシンのファイルシステム中のファイルへのインタフェースを提供します。
BufferedIOBase では生のバイトストリーム (RawIOBase) の上にバッファ処理を追加します。 そのサブクラスの BufferedWriter, BufferedReader, BufferedRWPair ではそれぞれ読み込み専用、書き込み専用、読み書き可能なストリームをバッファします。 BufferedRandom ではランダムアクセスストリームに対してバッファされたインタフェースを提供します。 BytesIO はインメモリバイトへのシンプルなストリームです。
もう一つの IOBase のサブクラスである、 TextIOBase は文字列を表すバイトストリームやその文字列に対するエンコーディングやデコーディングといった処理を行います。 TextIOWrapper はその拡張で、バッファされた生ストリーム (BufferedIOBase) へのバッファされた文字列インタフェースです。 最後に StringIO は文字列に対するインメモリストリームです。
引数名は規約に含まれていません。 また open() の引数はキーワード引数として用いられることが意図されています。
モジュールのバッファ I/O クラスに使用されるデフォルトのバッファサイズを指定する整数値です。 open() は可能であればファイル全体のサイズを使用します。(ファイル全体のサイズは os.stat() で取得されます)
file を開きストリームを返します。 もしファイルを開くことが出来なかった場合、 IOError が発生します。
file は開きたいファイルの名前(とカレントディレクトリにない場合はそのパス)を示す文字列であるか、開きたいファイルのファイルディスクリプタです。 (たとえば os.fdopen() から得られるようなファイルディスクリプタが与えられた場合、 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' が含まれている場合)ではファイルの中身は文字列として返され、バイト列はプラットフォーム依存のエンコーディングをされるか、 encoding が指定された場合は指定されたエンコーディングを行います。
オプションである buffering はバッファ用の設定を行う整数値です。 デフォルトではフルバッファがオンに設定されています。 0を設定することでバッファがオフになります。(バイナリモードでのみ有効です) 1の場合は1行ごとのバッファリングを行い、1より大きい場合はフルバッファが行われます。
encoding はファイルをエンコードあるいはデコードするために使われるエンコーディング名です。 このオプションはテキストモードでのみ使用されるべきです。 デフォルトエンコーディングはプラットフォーム依存ですが、Pythonでサポートされているエンコーディングはどれでも使えます。 詳しくは codecs モジュール内のサポートしているエンコーディングのリストを参照してください。
errors はエンコードやデコードの際のエラーをどのように扱うかを指定する文字列です。 'strict' を指定するとエンコードエラーがあった場合 ValueError 例外を発生させます。 (デフォルトである None は同様の処理を行います) 'ignore' を指定した場合はエラーを無視します。 'replace' を指定した場合は正常に変換されなかった文字の代わりにマーカ(例えば '?' のような文字)を挿入します。 書き込みの際に 'xmlcharrefreplace' (適切なXML文字参照に置き換える)か 'backslashreplace' (バックスラッシュによるエスケープシーケンスに置き換える)のどちらかが使用出来ます。 codecs.register_error() に登録されている他のエラー処理名も指定出来ます。
newline ではユニバーサルニューラインの挙動を制御しています。(テキストモードのみ有効です) None, '', '\n', '\r', '\r\n' が指定出来ます。 以下のように動作します:
もし closefd が False で、ファイル名ではなくてファイルディスクリプタが与えられていた場合、処理中のファイルディスクリプタはファイルが閉じられた後も開いたままとなります。 もしファイル名が与えられていた場合は、 closefd は関係ありません。しかし True でなければいけません。(デフォルト値)
open() によって返されるファイルオブジェクトのタイプの話をすると、 open() がテキストモードでファイルを開くときに使われた場合( 'w', 'r', 'wt', 'rt' など)、 TextIOWrapper が返されます。 バイナリモードでファイルを開くときに使われた場合、返される値は変わってきます。もし読み取り専用のバイナリモードだった場合は BufferedReader が返されます。 書き込み専用のバイナリモードだった場合は BufferedWriter が返されます。 読み書き可能なバイナリモードの場合は BufferedRandom が返されます。
もし文字列やバイト列をファイルとして読み書きすることも可能です。 文字列では StringIO を使えばテキストモードで開いたファイルのように扱えます。 バイト列では BytesIO を使えばバイナリモードで開いたファイルのように扱えます。
非ブロッキングストリームでブロック処理が起きた場合に発生するエラーです。 IOError を継承しています。
IOError で持っている属性以外に BlockingIOError では次の属性を持っています。
ブロック前にストリームに書き込まれる文字数を保持する整数値です。
IOError と ValueError を継承した例外でストリームに予想外の操作が行われた場合に発生します。
すべてのI/Oクラスの抽象ベースクラスです。バイトストリームへの操作を行います。 パブリックなコンストラクタはありません。
このクラスでは継承先のクラスがオーバライドするかの選択の余地を残すためにたくさんの 空の抽象実装を持っています。デフォルトの実装では読み込み、書き込み、シークができない ファイルとなっています。
IOBase がそのシグナチャーが変化するため read(), readinto(), write() を宣言していなくても、実装やクライアントはインタフェースの一部として これらのメソッドを考慮するべきです。 また実装はサポートしていない操作を呼び出されたときは IOError を発生させるかもしれません。
ファイル等への読み書きに用いられるバイナリデータに使われるバイナリ型は bytes です。 bytearray も許可されています。ほかにもいくつかのクラス(たとえば readinto) が必要です。文字列のI/Oクラスは str のデータを扱っています。
閉じたストリームでメソッドを呼び出し(問い合わせでさえ)は定義されていません。 この場合実装は IOError を発生させます。
IOBase(とそのサブクラス)はイテレータプロトコルをサポートします。 それはつまり IOBase オブジェクトはストリーム内の行をyieldを使って イテレートすることが出来ます。
IOBaseはコンテキストマネージャでもあります。そのため with 構文を サポートします。次の例では file は with 構文が終わった後、 閉じられます。–それがたとえ例外が発生したあとでさえです。
- with open(‘spam.txt’, ‘w’) as file:
- file.write(‘Spam and eggs!’)
IOBase データ属性とメソッドを提供します:
このストリームをフラッシュして閉じます。このメソッドはファイルが既に閉じられていた場合 特になにも影響を与えません。
ストリームが閉じられていた場合Trueになります。
ストリームが保持しているファイルディスクリプタ(整数値)が存在する場合はそれを返します。 もしIOオブジェクトがファイルディスクリプタを使っていない場合は IOError が発生します。
適用可能であればストリームの書き込みバッファをフラッシュします。 読み込み専用や非ブロッキングストリームには影響を与えません。
ストリームが相互作用的であれば(つまりターミナルやttyデバイスにつながっている場合) True を返します。
ストリームから1行読み込んで返します。 もし limit が指定された場合、最大で limit バイトが読み込まれます。
バイナリファイルでは行末文字は常に b'\n' となります。テキストファイルでは open() への newlines 引数は行末文字が認識されたときに使われます。
ストリームから行のリストを読み込んで返します。 hint を指定することで、何行読み込むかを指定出来ます。 もし読み込んだすべての行のサイズ(バイト数、もしくは文字数)が hint の値を超えた場合読み込みをそこで終了します。
ストリーム位置を指定された offset バイトに変更します。 offset は whence で指定された位置からの相対位置として解釈されます。 whence に入力できる値は:
新しい絶対位置を返します。
もしストリームがランダムアクセスをサポートしていた場合 True を返します。 False の場合は seek(), tell(), truncate() は IOError を発生させます。
現在のストリーム位置を返します。
ストリームが書き込みをサポートしていた場合 True を返します。 False の場合は write(), truncate() は IOError を返します。
ストリームに複数行書き込みます。 行区切り文字は付与されないので、書き込む各行の行末には行区切り文字があります。
生バイナリI/Oへのベースクラスです。 IOBase を継承しています。 パブリックコンストラクタはありません。
IOBase の属性やメソッドに加えて、 RawIOBase は次のメソッドを提供します:
EOF まで、あるいは n が指定された場合 n バイトまでストリームからすべてのバイトを読み込んで返します。たった1つのシステムコールが呼ばれます。 既に EOF に達していたら空のバイトオブジェクトが返されます。 もしオブジェクトがブロックされず読み込むべきデータがない場合は None が返されます。
EOF までストリームからすべてのバイトを読み込みます。 必要な場合はストリームに対して複数の呼び出しをします。
バイト列 b に len(b) バイト分読み込み、読み込んだバイト数を返します。
FileIO はバイトデータを含むファイルを表します。 RawIOBase インタフェースを (そしてしたがって IOBase インタフェースも) 実装しています。
mode はそれぞれ読み込み(デフォルト)、書き込み、追記を表す 'r', 'w', 'a' にすることができます。 ファイルは書き込みまたは追記モードで開かれたときに存在しなければ作成されます。 書き込みモードでは存在したファイル内容は消されます。 読み込みと書き込みを同時に行いたければ '+' をモードに加えて下さい。
IOBase および RawIOBase から継承した属性とメソッドに加えて、 FileIO は以下のデータ属性とメソッドを提供しています:
コンストラクタに渡されたモードです。
ファイル名。 コンストラクタに名前が渡されなかったときはファイルディスクリプタになります。
最大で n バイト読み込み、返します。 システムコールを一度呼び出すだけなので、要求されたより少ないデータが返されることもあります。 実際に返されたバイト数を得たければ len() を返されたバイトオブジェクトに対して使って下さい。 (非ブロッキングモードでは、データが取れなければ None が返されます。)
ファイルの全内容を読み込み、単一のバイトオブジェクトに入れて返します。 非ブロッキングモードでは直ちに取得できる限りのものが返されます。 EOF に到達すると、 b'' が返されます。
与えられたバイトあるいはバイト列オブジェクト b をファイルに書き込み、 実際に書き込まれた(バイト)数を返します。 システムコールを一度呼び出すだけなので、データの一部だけが書き込まれることもあり得ます。
FileIO オブジェクトでは継承された readinto() メソッドを使うべきではないということを忘れないで下さい。
バッファリングをサポートするストリームの基底クラスです。 IOBase を継承します。 パブリックなコンストラクタはありません。
RawIOBase との主な違いは read() メソッドが size 引数の省略を許し、 readinto() と異なるデフォルト実装を持たないことです。
さらに、 read(), readinto(), write() が、 元になる生ストリームが非ブロッキングモードでかつ準備ができていない場合に、 BlockingIOError を送出するかもしれません。 対応する”生”バージョンと違って、 None を返すことはありません。
通常の実装では RawIOBase 実装を継承して実装せず、 BufferedWriter と BufferedReader のようにラップすべきです。
BufferedIOBase は IOBase からのメソッドに加えて、 以下のメソッドを提供するかもしくはオーバーライドします:
最大で n バイト読み込み、返します。 引数が省略されるか、 None か、または負の値であった場合、 データは EOF に到達するまで読み込まれます。 ストリームが既に EOF に到達していた場合空の bytes オブジェクトが返されます。
引数が正で、元になる生ストリームが対話的でなければ、 複数回の生 read が必要なバイト数を満たすように発行されるかもしれません (先に EOF に到達しない限りは)。 対話的である場合には、最大で一回の raw read しか発行されず、 短い結果でも EOF に達したことを意味しません。
元になる生ストリームが呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。
len(b) バイトを上限に bytearray b に読み込み、何バイト読んだかを返します。
read() と同様、元になる生ストリームに、それが対話的でない限り、 複数回の read が発行されるかもしれません。
元になる生ストリームが呼び出された時点でデータを持っていなければ、 BlockingIOError が送出されます。
与えられた bytes または bytearray オブジェクト b を、 元になる生ストリームに書き込み、書き込まれたバイト数を返します (決して len(b) よりも小さくなることはありません。 なぜならはもし書き込みに失敗した場合は IOError が発生するからです)
バッファが満杯で元になる生ストリームが書き込み時点でさらなるデータを受け付けられない場合 BlockingIOError が送出されます。
インメモリの bytes バッファを利用したストリームの実装。 BufferedIOBase を継承します。
引数 initial_bytes は省略可能な bytearray の初期値です。
BytesIO は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供するかもしくはオーバーライドします:
バッファの全内容を保持した bytes を返します。
高々 size バイトまでバッファを切り詰めます。 size のデフォルトは tell() で返される現在のストリーム位置です。
読み込み可能でシーケンシャルな RawIOBase オブジェクトのバッファです。 BufferedIOBase を継承します。
このコンストラクタは与えられた raw ストリームと buffer_size に対し BufferedReader を生成します。 buffer_size が省略された場合 DEFAULT_BUFFER_SIZE が代わりに使われます。
BufferedReader は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供するかもしくはオーバーライドします:
1 (または指定されれば n) バイトをバッファから位置を変更せずに読んで返します。 これを果たすために生ストリームに対して行われる read はただ一度だけです。 返されるバイト数は、 最大でもバッファの現在の位置から最後までのバイト列なので、 要求されたより少なくなるかもしれません。
n バイトを読み込んで返します。 n が与えられないかまたは負の値ならば、EOF まで、 または非ブロッキングモード中で read 呼び出しがブロックされるまでを返します。
生ストリームに対しただ一度の呼び出しで最大 n バイトを読み込んで返します。 少なくとも 1 バイトがバッファされていれば、バッファされているバイト列だけが返されます。 それ以外の場合にはちょうど一回生ストリームに read 呼び出しが行われます。
書き込み可能でシーケンシャルな RawIOBase オブジェクトのバッファです。 BufferedIOBase を継承します。
このコンストラクタは与えられた書き込み可能な raw ストリームに対し BufferedWriter を生成します。 buffer_size が省略された場合 DEFAULT_BUFFER_SIZE がデフォルトになります。 max_buffer_size が省略された場合、バッファサイズの 2 倍がデフォルトになります。
BufferedWriter は BufferedIOBase または IOBase からのメソッドに加えて、以下のメソッドを提供するかもしくはオーバーライドします:
バッファに保持されたバイト列を生ストリームに流し込みます。 生ストリームがブロックした場合 BlockingIOError が送出されます。
bytes または bytearray オブジェクト b を生ストリームに書き込み、 書き込んだバイト数を返します。 生ストリームがブロックした場合 BlockingIOError が送出されます。
読み書きできる生ストリームのための組み合わされたバッファ付きライターとリーダーです。 read() 系、 write() 系メソッド両方ともサポートされます。 ソケットや両方向パイプに便利です。 BufferedIOBase を継承しています。
reader と writer はそれぞれ読み込み可能、書き込み可能な RawIOBase オブジェクトです。 buffer_size が省略された場合 DEFAULT_BUFFER_SIZE がデフォルトになります。 (バッファ付きライターのための) max_buffer_size が省略された場合、バッファサイズの 2 倍がデフォルトになります。
BufferedRWPair は BufferedIOBase の全てのメソッドを実装します。
ランダムアクセスストリームへのバッファ付きインタフェース。 BufferedReader および BufferedWriter を継承しています。
このコンストラクタは第一引数として与えられるシーク可能な生ストリームに対し、 リーダーおよびライターを作成します。 buffer_size が省略された場合 DEFAULT_BUFFER_SIZE がデフォルトになります。 (バッファ付きライターのための) max_buffer_size が省略された場合、バッファサイズの 2 倍がデフォルトになります。
BufferedRandom は BufferedReader や BufferedWriter にできることは何でもできます。
テキストストリームの基底クラスです。 このクラスはストリーム I/O への文字と行に基づいたインタフェースを提供します。 readinto() メソッドは Python の文字列が変更不可能なので存在しません。 IOBase を継承します。 パブリックなコンストラクタはありません。
IOBase から継承した属性とメソッドに加えて、 TextIOBase は以下のデータ属性とメソッドを提供しています:
エンコーディング名で、ストリームのバイト列を文字列にデコードするとき、 また文字列をバイト列にエンコードするときに使われます。
文字列、文字列のタプル、または None で、改行がどのように読み換えられるかを指定します。
最大 n 文字をストリームから読み込み、一つの文字列にして返します。 n が負の値または None ならば、 EOF まで読みます。
改行または EOF まで読み込み、一つの str を返します。 ストリームが既に EOF に到達している場合、空文字列が返されます。
文字列 s をストリームに書き込み、書き込まれた文字数を返します。
BufferedIOBase 生ストリーム buffer 上のバッファ付きテキストストリーム。 TextIOBase を継承します。
encoding にはストリームをデコードしたりそれを使ってエンコードしたりするエンコーディング名を渡します。 デフォルトは locale.getpreferredencoding() です。
errors はオプションの文字列でエンコードやデコードの際のエラーをどのように扱うかを指定します。 エンコードエラーがあったら ValueError 例外を送出させるには 'strict' を渡します(デフォルトの None でも同じです)。 エラーを無視させるには 'ignore' です。 (注意しなければならないのはエンコーディングエラーを無視するとデータ喪失につながる可能性があるということです。) 'replace' は正常に変換されなかった文字の代わりにマーカ (たとえば '?') を挿入させます。 書き込み時には 'xmlcharrefreplace' (適切な XML 文字参照に置き換え) や、 'backslashreplace' (バックスラッシュによるエスケープシーケンスに置き換え) も使えます。 他にも codecs.register_error() で登録されたエラー処理名が有効です。
newline は None, '', '\n', '\r', '\r\n' のいずれかです。 行末の扱いを制御します。 None では、ユニバーサルニューラインが有効になります。 これが有効になると、入力時、行末の '\n', '\r', '\r\n' は '\n' に変換されて呼び出し側に返されます。 逆に出力時は '\n' がシステムのデフォルト行区切り文字 (os.linesep) に変換されます。 newline が他の適切な値の場合には、ファイル読み込みの際にその改行で改行されるようになり、 変換は行われません。 出力時には '\n' が newline に変換されます。
line_buffering が True の場合、write への呼び出しが改行文字を含んでいれば flush() がそれに伴って呼び出されます。
TextIOBase およびその親クラスの属性に加えて、 TextIOWrapper は以下のデータ属性を提供しています:
エンコーディングおよびデコーディングエラーの設定。
行バッファリングが有効かどうか。
テキストのためのインメモリストリーム。 TextIOWrapper を継承します。
新しい StringIO ストリームを初期値、エンコーディング、エラーの扱い、改行設定から作成します。 より詳しい情報は TextIOWrapper のコンストラクタを参照して下さい。
TextIOWrapper およびその親クラスから継承したメソッドに加えて StringIO は以下のメソッドを提供しています:
バッファの全内容を保持した str を返します。
ユニバーサルニューラインモード向けに改行をデコードする補助コーデック。 codecs.IncrementalDecoder を継承します。