# ファイルオブジェクト

これらの 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.

  オブジェクト obj をファイルオブジェクト p に書き込みます。 flags がサポートするフラグは `Py_PRINT_RAW` だけです; このフラグを指定すると、オブジェクトに `repr()` ではなく `str()` を適用した結果をファイルに書き出します。成功した場合には `0` を返し、失敗すると `-1` を返して適切な例外をセットします。

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

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

## Deprecated API

These are soft deprecated 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.