Python の組み込みファイルオブジェクトは、全て標準 C ライブラリの FILE* サポートの上に実装されています。以下の詳細説明は一実装に関するもので、将来の Python のリリースで変更されるかもしれません。
この PyTypeObject のインスタンスは Python のファイル型を表現します。このオブジェクトは file および types.FileType として Python プログラムで公開されています。
引数が PyFileObject か PyFileObject のサブタイプのときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
引数が PyFileObject 型で、かつ PyFileObject 型のサブタイプでないときに真を返します。
バージョン 2.2 で追加.
成功すると、 filename に指定した名前のファイルを mode に指定したファイルモードで開いて得た新たなファイルオブジェクトを返します。 mode のセマンティクスは標準 C ルーチン fopen() と同じです。失敗すると NULL を返します。
すでに開かれている標準 C ファイルポインタ fp から新たな PyFileObject を生成します。この関数で生成したファイルオブジェクトは、閉じる際に close に指定した関数を呼び出します。失敗すると NULL を返します。
p に関連付けられたファイルオブジェクトを FILE* で返します。
呼び出し側が GIL を開放している間もこの関数が返した FILE* オブジェクトを使うのであれば、以下に解説されている PyFile_IncUseCount() と PyFile_DecUseCount() 関数を適切に呼び出さなければなりません。
PyFileObject 内部の、 FILE* が使用中であることを示す使用数カウントをインクリメントします。これは、別のスレッドで使用中の FILE* に対して Python が fclose() を呼び出すことを防ぎます。この関数の呼び出し側は、 FILE* を使い終わったときに必ず PyFile_DecUseCount() を呼び出さなければなりません。そうしなければ、 Python はそのファイルオブジェクトを永遠に閉じません。
この関数を呼び出すときは、 GIL を取得していなければなりません。
例えば、 PyFile_AsFile() を呼び出した後、GILを開放する前にこの関数を呼び出します。
FILE *fp = PyFile_AsFile(p);
PyFile_IncUseCount(p);
/* ... */
Py_BEGIN_ALLOW_THREADS
do_something(fp);
Py_END_ALLOW_THREADS
/* ... */
PyFile_DecUseCount(p);
バージョン 2.6 で追加.
PyFileObject 内部の、 FILE* が使用中であることを示す unlocked_count メンバーをデクリメントして、呼び出し元が FILE* を使い終わったことを示します。これは、先に行った PyFile_IncUseCount() の呼び出しを取り消すためだけに呼び出されるでしょう。
この関数を呼び出すときは、 GIL を取得していなければなりません。 (上の例を参照してください)
バージョン 2.6 で追加.
p.readline([*n*]) と同じで、この関数はオブジェクト p の各行を読み出します。 p はファイルオブジェクトか、 readline() メソッドを持つ何らかのオブジェクトでかまいません。 n が 0 の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n が 0 より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を返します。 n が 0 より小さければ、長さに関わらず 1 行だけを読み出しますが、すぐにファイルの終端に到達した場合には EOFError を送出します。
setvbuf() があるシステムでのみ利用できます。この関数を呼び出してよいのはファイルオブジェクトの生成直後のみです。
Unicode オブジェクトをファイルに出力するときにのエンコーディングを enc にします。成功すると 1 を、失敗すると 0 を返します。
バージョン 2.3 で追加.
Unicode オブジェクトをファイルに出力するときにのエンコーディングを enc に設定し、そのエラーモードを err に設定します。
バージョン 2.6 で追加.
この関数はインタプリタの内部的な利用のために存在します。この関数は p の softspace 属性を newflag に設定し、以前の設定値を返します。この関数を正しく動作させるために、 p がファイルオブジェクトである必然性はありません; 任意のオブジェクトをサポートします (softspace 属性が設定されているかどうかのみが問題だと思ってください)。この関数は全てのエラーを解消し、属性値が存在しない場合や属性値を取得する際にエラーが生じると、 0 を以前の値として返します。この関数からはエラーを検出できませんが、そもそもそういう必要はありません。