ファイルオブジェクト

Python の組み込みファイルオブジェクトは、全て標準 C ライブラリの FILE* サポートの上に実装されています。以下の詳細説明は一実装に関するもので、将来の Python のリリースで変更されるかもしれません。

PyFileObject

この PyObject のサブタイプは Python のファイル型オブジェクトを表現します。

PyTypeObject PyFile_Type

この PyTypeObject のインスタンスは Python のファイル型を表現します。このオブジェクトは file および types.FileType として Python プログラムで公開されています。

int PyFile_Check(PyObject *p)

引数が PyFileObjectPyFileObject のサブタイプのときに真を返します。

バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.

int PyFile_CheckExact(PyObject *p)

引数が PyFileObject 型で、かつ PyFileObject 型のサブタイプでないときに真を返します。

バージョン 2.2 で追加.

PyObject* PyFile_FromString(char *filename, char *mode)
Return value: New reference.

成功すると、 filename に指定した名前のファイルを mode に指定したファイルモードで開いて得た新たなファイルオブジェクトを返します。 mode のセマンティクスは標準 C ルーチン fopen() と同じです。失敗すると NULL を返します。

PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
Return value: New reference.

すでに開かれている標準 C ファイルポインタ fp から新たな PyFileObject を生成します。この関数で生成したファイルオブジェクトは、閉じる際に close に指定した関数を呼び出します。失敗すると close を使ってファイルをクローズし、 NULL を返します。 close の指定は任意で、 NULL にもできます。(—訳注: 失敗時に close を呼び出すのは issue #7732 に関係した仕様です。今ここで説明している「失敗時」はコードを読む限り PyString_FromString の失敗時だけです、今のところ。 —)

FILE* PyFile_AsFile(PyObject *p)

p に関連付けられたファイルオブジェクトを FILE* で返します。

呼び出し側が GIL を解放している間もこの関数が返した FILE* オブジェクトを使うのであれば、以下に解説されている PyFile_IncUseCount()PyFile_DecUseCount() 関数を適切に呼び出さなければなりません。

void PyFile_IncUseCount(PyFileObject *p)

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 で追加.

void PyFile_DecUseCount(PyFileObject *p)

PyFileObject 内部の、 FILE* が使用中であることを示す unlocked_count メンバーをデクリメントして、呼び出し元が FILE* を使い終わったことを示します。これは、先に行った PyFile_IncUseCount() の呼び出しを取り消すためだけに呼び出されるでしょう。

この関数を呼び出すときは、 GIL を取得していなければなりません。 (上の例を参照してください)

バージョン 2.6 で追加.

PyObject* PyFile_GetLine(PyObject *p, int n)
Return value: New reference.

p.readline([n]) と同じで、この関数はオブジェクト p の各行を読み出します。 p はファイルオブジェクトか、 readline() メソッドを持つ何らかのオブジェクトでかまいません。 n0 の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n0 より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。 どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を 返します。 n0 より小さければ、長さに関わらず 1 行だけを 読み出しますが、すぐにファイルの終端に到達した場合には EOFError を送出します。

PyObject* PyFile_Name(PyObject *p)
Return value: Borrowed reference.

p に指定したファイルの名前を文字列オブジェクトで返します。

void PyFile_SetBufSize(PyFileObject *p, int n)

setvbuf() があるシステムでのみ利用できます。この関数を呼び出してよいのはファイルオブジェクトの生成直後のみです。

int PyFile_SetEncoding(PyFileObject *p, const char *enc)

Unicode オブジェクトをファイルに出力するときにのエンコーディングを enc にします。成功すると 1 を、失敗すると 0 を返します。

バージョン 2.3 で追加.

int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)

Unicode オブジェクトをファイルに出力するときにのエンコーディングを enc に設定し、そのエラーモードを err に設定します。成功すると 1 を、失敗すると 0 を返します。

バージョン 2.6 で追加.

int PyFile_SoftSpace(PyObject *p, int newflag)

この関数はインタプリタの内部的な利用のために存在します。この関数は psoftspace 属性を newflag に設定し、以前の設定値を返します。この関数を正しく動作させるために、 p がファイルオブジェクトである必然性はありません; 任意のオブジェクトをサポートします (softspace 属性が設定されているかどうかのみが問題だと思ってください)。この関数は全てのエラーを解消し、属性値が存在しない場合や属性値を取得する際にエラーが生じると、 0 を以前の値として返します。この関数からはエラーを検出できませんが、そもそもそういう必要はありません。

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

オブジェクト obj をファイルオブジェクト p に書き込みます。 flags がサポートするフラグは Py_PRINT_RAW だけです; このフラグを指定すると、オブジェクトに repr() ではなく str() を適用した結果をファイルに書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。

int PyFile_WriteString(const char *s, PyObject *p)

文字列 s をファイルオブジェクト p に書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。