ファイルオブジェクト¶
Python の組み込みファイルオブジェクトは、全て標準 C ライブラリの FILE* サポートの上に実装されています。以下の詳細説明は一実装に関するもので、将来の Python のリリースで変更されるかもしれません。
-
PyTypeObject
PyFile_Type¶ この
PyTypeObjectのインスタンスは Python のファイル型を表現します。このオブジェクトはfileおよびtypes.FileTypeとして Python プログラムで公開されています。
-
int
PyFile_Check(PyObject *p)¶ 引数が
PyFileObjectかPyFileObjectのサブタイプのときに真を返します。バージョン 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()メソッドを持つ何らかのオブジェクトでかまいません。 n が0の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n が0より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。 どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を 返します。 n が0より小さければ、長さに関わらず 1 行だけを 読み出しますが、すぐにファイルの終端に到達した場合にはEOFErrorを送出します。
-
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)¶ この関数はインタプリタの内部的な利用のために存在します。この関数は p の
softspace属性を newflag に設定し、以前の設定値を返します。この関数を正しく動作させるために、 p がファイルオブジェクトである必然性はありません; 任意のオブジェクトをサポートします (softspace属性が設定されているかどうかのみが問題だと思ってください)。この関数は全てのエラーを解消し、属性値が存在しない場合や属性値を取得する際にエラーが生じると、0を以前の値として返します。この関数からはエラーを検出できませんが、そもそもそういう必要はありません。