File objects
************

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

PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

   警告:

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

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

int PyObject_AsFileDescriptor(PyObject *p)
    * 次に属します: Stable ABI.*

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

PyObject *PyFile_GetLine(PyObject *p, int n)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

   "io.open_code()" の通常の振る舞いを上書きして、そのパラメーターを提
   供されたハンドラで渡します。

   ハンドラーは次の型の関数です。

   typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)

      PyObject *(*)(PyObject *path, void *userData) と等価で、 *path*
      は "PyUnicodeObject" であることが保証されています。

   *userData* ポインタはフック関数に渡されます。 フック関数は別なラン
   タイムから呼び出されるかもしれないので、このポインタは直接 Python
   の状態を参照すべきではありません。

   このフック関数はインポート中に使われることを意図しているため、モジ
   ュールが frozen なモジュールであるか "sys.modules" にある利用可能な
   モジュールであることが分かっている場合を除いては、フック関数の実行
   中に新しいモジュールをインポートするのは避けてください。

   いったんフック関数が設定されたら、削除や置き換えもできず、後からの
   "PyFile_SetOpenCodeHook()" の呼び出しは失敗します。 この関数が失敗
   したときは、インタープリタが初期化されていた場合、 -1 を返して例外
   をセットします。

   この関数は "Py_Initialize()" より前に呼び出しても安全です。

   引数無しで 監査イベント "setopencodehook" を送出します。

   Added in version 3.8.

PyObject *PyFile_OpenCodeObject(PyObject *path)

   Open *path* with the mode "'rb'". *path* must be a Python "str"
   object. The behavior of this function may be overridden by
   "PyFile_SetOpenCodeHook()" to allow for some preprocessing of the
   text.

   This is analogous to "io.open_code()" in Python.

   On success, this function returns a *strong reference* to a Python
   file object. On failure, this function returns "NULL" with an
   exception set.

   Added in version 3.8.

PyObject *PyFile_OpenCode(const char *path)

   Similar to "PyFile_OpenCodeObject()", but *path* is a UTF-8 encoded
   const char*.

   Added in version 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
    * 次に属します: Stable ABI.*

   Write object *obj* to file object *p*.  The only supported flag for
   *flags* is "Py_PRINT_RAW"; if given, the "str()" of the object is
   written instead of the "repr()".

   If *obj* is "NULL", write the string ""<NULL>"".

   Return "0" on success or "-1" on failure; the appropriate exception
   will be set.

int PyFile_WriteString(const char *s, PyObject *p)
    * 次に属します: Stable ABI.*

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


Soft-deprecated API
===================

Soft deprecated since version 3.15.

These are APIs that were included in Python's C API by mistake. They
are documented solely for completeness; use other "PyFile*" APIs
instead.

PyObject *PyFile_NewStdPrinter(int fd)

   Use "PyFile_FromFd()" with defaults ("fd, NULL, "w", -1, NULL,
   NULL, NULL, 0") instead.

PyTypeObject PyStdPrinter_Type

   Type of file-like objects used internally at Python startup when
   "io" is not yet available. Use Python "open()" or "PyFile_FromFd()"
   to create file objects instead.
