3.9 ファイルオブジェクト

ファイルオブジェクトは C のstdio パッケージを使って実装されており、 2.1 節の ``組み込み関数'' で解説されている組み込みのコンストラクタ file() で生成することができます。 ^3.6 ファイルオブジェクトはまた、os.popen() や os.fdopen() 、ソケットオブジェクトの makefile() メソッドのような、他の組み込み関数およびメソッドによっても返されます。

ファイル操作が I/O 関連の理由で失敗した場合例外 IOError が送出されます。この理由には例えば seek() を端末デバイスに行ったり、読み出し専用で開いたファイルに書き込みを行うといった、何らかの理由によってそのファイルで定義されていない操作を行ったような場合も含まれます。

ファイルは以下のメソッドを持ちます:

close( )

ファイルを閉じます。閉じられたファイルはそれ以後読み書きすることはできません。ファイルが開かれていることが必要な操作は、ファイルが閉じられた後はすべて ValueError を送出します。 close を一度以上呼び出してもかまいません。

Python 2.5 から with 文を使えばこのメソッドを直接呼び出す必要はなくなりました。たとえば、以下のコードは f を with ブロックを抜ける際に自動的に閉じます。

from __future__ import with_statement

with open("hello.txt") as f:
    for line in f:
        print line

古いバージョンの Python では同じ効果を得るために次のようにしなければいけませんでした。

f = open("hello.txt")
try:
    for line in f:
        print line
finally:
    f.close()

注意: 全ての Python の ``ファイル的'' 型が with 文用のコンテキスト・マネージャとして使えるわけではありません。もし、全てのファイル的オブジェクトで動くようにコードを書きたいのならば、オブジェクトを直接使うのではなく contextlib にある closing() を使うと良いでしょう。詳細はセクション 26.5 を参照してください。

flush( ): stdio の fflush() のように、内部バッファをフラッシュします。ファイル類似のオブジェクトによっては、この操作は何も行いません。

fileno( ): 背後にある実装系がオペレーティングシステムに I/O 操作を要求するために用いる、整数の ``ファイル記述子'' を返します。この値は他の用途として、 fcntl モジュールや os.read() やその仲間のような、ファイル記述子を必要とする低レベルのインタフェースで役に立ちます。 注意: ファイル類似のオブジェクトが実際のファイルに関連付けられていない場合、このメソッドを提供すべきではありません。

isatty( ): ファイルが tty (または類似の) デバイスに接続されている場合 True を返し、そうでない場合 False を返します。 注意: ファイル類似のオブジェクトが実際のファイルに関連付けられていない場合、このメソッドを実装すべきではありません。

next( ): ファイルオブジェクトはそれ自身がイテレータです。すなわち、 iter(f) は (f が閉じられていない限り) f を返します。for ループ (例えば for line in f: print line) のようにファイルがイテレータとして使われた場合、next() メソッドが繰り返し呼び出されます。個のメソッドは次の入力行を返すか、または EOF に到達したときに StopIteration を送出します。ファイル内の各行に対する for ループ (非常によくある操作です) を効率的な方法で行うために、next() メソッドは隠蔽された先読みバッファを使います。先読みバッファを使った結果として、(readline() のような) 他のファイルメソッドと next() を組み合わせて使うとうまく動作しません。しかし、seek() を使ってファイル位置を絶対指定しなおすと、先読みバッファはフラッシュされます。
バージョン 2.3 で新たに追加された仕様です。

read( [size]): 最大で size バイトをファイルから読み込みます (size バイトを取得する前に EOF に到達した場合、それ以下の長さになります) size 引数が負であるか省略された場合、EOF に到達するまでの全てのデータを読み込みます。読み出されたバイト列は文字列オブジェクトとして返されます。直後に EOF に到達した場合、空の文字列が返されます。 (端末のようなある種のファイルでは、 EOF に到達した後でファイルを読みつづけることにも意味があります。) このメソッドは、size バイトに可能な限り近くデータを取得するために、背後の C 関数 fread() を 1 度以上呼び出すかもしれないので注意してください。また、非ブロック・モードでは、size パラメータが与えられなくても、要求されたよりも少ないデータが返される場合があることに注意してください。

readline( [size]): ファイルから一行を読み出します。末尾の改行文字は文字列中に残されます（ですが、ファイルが不完全な行で終わっている場合は何も残らないかもしれません）。 ^3.7引数 size が指定されていて負数でない場合、 (末尾の改行を含めて) 読み込む最大のバイト数です。この場合、不完全な行が返されるかもしれません。空文字列が返されるのは、直後に EOF に到達した場合だけです。 注意: stdio の fgets() と違い、入力中にヌル文字 ('\0') が含まれていれば、ヌル文字を含んだ文字列が返されます。

readlines( [sizehint]): readline() を使ってに到達するまで読み出し、EOF 読み出された行を含むリストを返します。オプションの sizehint 引数が存在すれば、EOFまで読み出す代わりに完全な行を全体で大体 sizehint バイトになるように (おそらく内部バッファサイズを切り詰めて) 読み出します。ファイル類似のインタフェースを実装しているオブジェクトは、 sizehint を実装できないか効率的に実装できない場合には無視してもかまいません。

xreadlines( ): 個のメソッドは iter(f) と同じ結果を返します。バージョン 2.1 で新たに追加された仕様です。
リリース 2.3 で撤廃されました。 代わりに "for line in file" を使ってください。

seek( offset[, whence]): stdio の fseek() と同様に、ファイルの現在位置を返します。whence 引数はオプションで、標準の値は 0 (絶対位置指定) です; 他に取り得る値は 1 (現在のファイル位置から相対的に seek する) および 2 (ファイルの末端から相対的に seek する) です。戻り値はありません。ファイルを追記モード (モード 'a' または 'a+') で開いた場合、書き込みを行うまでに行ったseek() 操作はすべて元に戻されるので注意してください。ファイルが追記のみの書き込みモード ('a') で開かれた場合、このメソッドは実質何も行いませんが、読み込みが可能な追記モード ('a+') で開かれたファイルでは役に立ちます。ファイルをテキストモードで ('b' なしで) 開いた場合、 tell() が返すオフセットのみが正しい値になります。他のオフセット値を使った場合、その振る舞いは未定義です。
全てのファイルオブジェクトが seek できるとは限らないので注意してください。

tell( ): stdio の ftell() と同様、ファイルの現在位置を返します。
注意: Windows では、(fgets() の後で) Unix-スタイルの改行のファイルを読むときにtell() が不正な値を返すことがあります。この問題に遭遇しないためにはバイナリーモード ('rb') を使うようにしてください。

truncate( [size]): ファイルのサイズを切り詰めます。オプションの size が存在すれば、ファイルは (最大で) 指定されたサイズに切り詰められます。標準設定のサイズの値は、現在のファイル位置までのファイルサイズです。現在のファイル位置は変更されません。指定されたサイズがファイルの現在のサイズを越える場合、その結果はプラットフォーム依存なので注意してください: 可能性としては、ファイルは変更されないか、指定されたサイズまでゼロで埋められるか、指定されたサイズまで未定義の新たな内容で埋められるか、があります。利用可能な環境: Windows, 多くの Unix 系。

write( str): 文字列をファイルに書き込みます。戻り値はありません。バッファリングによって、flush() または close() が呼び出されるまで実際にファイル中に文字列が書き込まれないこともあります。

writelines( sequence): 文字列からなるシーケンスをファイルに書き込みます。シーケンスは文字列を生成する反復可能なオブジェクトなら何でもかまいません。よくあるのは文字列からなるリストです。戻り値はありません。 (関数の名前は readlines() と対応づけてつけられました; writelines() は行間の区切りを追加しません)

ファイルはイテレータプロトコルをサポートします。各反復操作では file.readline() と同じ結果を返し、反復は readline() メソッドが空文字列を返した際に終了します。

ファイルオブジェクトはまた、多くの興味深い属性を提供します。これらはファイル類似オブジェクトでは必要ではありませんが、特定のオブジェクトにとって意味を持たせたいなら実装しなければなりません。

closed: 現在のファイルオブジェクトの状態を示すブール値です。この値は読み出し専用の属性です; close() メソッドがこの値を変更します。全てのファイル類似オブジェクトで利用可能とは限りません。

encoding: このファイルが使っているエンコーディングです。Unicode 文字列がファイルに書き込まれる際、Unicode 文字列はこのエンコーディングを使ってバイト文字列に変換されます。さらに、ファイルが端末に接続されている場合、この属性は端末が使っているとおぼしきエンコーディング (この情報は端末がうまく設定されていない場合には不正確なこともあります) を与えます。この属性は読み出し専用で、すべてのファイル類似オブジェクトにあるとは限りません。またこの値は None のこともあり、この場合、ファイルはUnicode 文字列の変換のためにシステムのデフォルトエンコーディングを使います。
バージョン 2.3 で新たに追加された仕様です。

mode: ファイルの I/O モードです。ファイルが組み込み関数 open() で作成された場合、この値は引数 mode の値になります。この値は読み出し専用の属性で、全てのファイル類似オブジェクトに存在するとは限りません。

name: ファイルオブジェクトが open() を使って生成された時のファイルの名前です。そうでなければ、ファイルオブジェクト生成の起源を示す何らかの文字列になり、"<...>" の形式をとります。この値は読み出し専用の属性で、全てのファイル類似オブジェクトに存在するとは限りません。

newlines: Python をビルドするとき、--with-universal-newlines オプションがconfigure に指定された場合（デフォルト）、この読み出し専用の属性が存在します。一般的な改行に変換する読み出しモードで開かれたファイルにおいて、この属性はファイルの読み出し中に遭遇した改行コードを追跡します。取り得る値は '\ r'、'\n'、'\r\n'、None (不明または、まだ改行していない）、見つかった全ての改行文字を含むタプルのいずれかです。最後のタプルは、複数の改行慣例に遭遇したことを示します。一般的な改行文字を使う読み出しモードで開かれていないファイルの場合、この属性の値は None です。

softspace: print 文を使った場合、他の値を出力する前にスペース文字を出力する必要があるかどうかを示すブール値です。ファイルオブジェクトをシミュレート仕様とするクラスは書き込み可能な softspace 属性を持たなければならず、この値はゼロに初期化されなければなりません。この値は Python で実装されているほとんどのクラスで自動的に初期化されます (属性へのアクセス手段を上書きするようなオブジェクトでは注意が必要です); C で実装された型では、書き込み可能な softspace 属性を提供しなければなりません。 注意: この属性は print 文を制御するために用いられますが、 print の内部状態を乱さないために、その実装を行うことはできません。

脚注

... で生成することができます。^3.6: file() は Python 2.2 で新しく追加されました。古いバージョンの組み込み関数 open() は file() の別名です。
... 何も残らないかもしれません）。^3.7: 改行を残す利点は、空の文字列が返ると EOF を示し、紛らわしくなくなるからです。また、ファイルの最後の行が改行で終わっているかそうでない (ありえることです！) か (例えば、ファイルを行単位で読みながらその完全なコピーを作成した場合には問題になります) を調べることができます。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。