ファイルオブジェクト
********************

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

PyFileObject

   この "PyObject" のサブタイプは 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" を送出します。

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)

   この関数はインタプリタの内部的な利用のために存在します。この関数は
   *p* の "softspace" 属性を *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" を返して適切な例外をセットします。
