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

これらの API は、 Python 2 の組み込みのファイルオブジェクトの C API を
最低限エミュレートするためのものです。それらは、標準 C ライブラリでサ
ポートされているバッファ付き I/O ("FILE*") に頼るために使われます。
Python 3 では、ファイルとストリームは新しい "io" モジュールを使用され
、そこに OS の低レベルなバッファ付き I/O の上にいくつかの層が定義され
ています。下で解説されている関数は、それらの新しい API の便利な C ラッ
パーであり、インタプリタでの内部的なエラー通知に向いています; サードパ
ーティーのコードは代わりに "io" の API を使うことが推奨されます。

PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
    *Return value: New reference.*

   既に開かれているファイル *fd* のファイルディスクリプタから Python
   のファイルオブジェクトを作成します。引数 *name* 、 *encoding* 、
   *errors* 、 *newline* には "NULL" を指定してデフォルトの値を使うこ
   とができます; *buffering* には *-1* を指定してデフォルトの値を使う
   ことができます。 *name* は無視されるのですが、後方互換性のために残
   されています。失敗すると "NULL" を返します。より包括的な引数の解説
   は、 "io.open()" 関数のドキュメントを参照してください。

   警告:

     Python ストリームは自身のバッファリング層を持つため、ファイル記述
     子のOSレベルのバッファリングと併用すると、様々な問題 (予期せぬデ
     ータ順) などを引き起こします。

   バージョン 3.2 で変更: *name* 属性の無視。

int PyObject_AsFileDescriptor(PyObject *p)

   *p* に関連づけられる ファイルディスクリプタを "int" として返します
   。オブジェクトが整数なら、その値を返します。 整数でない場合、オブジ
   ェクトに "fileno()" メソッドがあれば呼び出します; このメソッドの返
   り値は、ファイル記述子の値として返される整数でなければなりません。
   失敗すると例外を設定して "-1" を返します。

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" を送出します。

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