# ファイルオブジェクト

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` を返して適切な例外をセットします。