檔案物件 (File Objects)
***********************

這些 API 是用於內建檔案物件的 Python 2 C API 的最小模擬 (minimal
emulation)，它過去依賴於 C 標準函式庫對於緩衝 I/O (FILE*) 的支援。在
Python 3 中，檔案和串流使用新的 "io" 模組，它在操作系統的低階無緩衝
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)
    *回傳值：新的參照。** 属于 稳定 ABI.*

   根据已打开文件 *fd* 的文件描述符创建一个 Python 文件对象。 参数
   *name*, *encoding*, *errors* 和 *newline* 可以为 "NULL" 表示使用默
   认值；*buffering* 可以为 *-1* 表示使用默认值。 *name* 会被忽略仅保
   留用于向下兼容。 失败时返回 "NULL"。 有关参数的更全面描述，请参阅
   "io.open()" 函数的文档。

   警告:

     由於 Python 串流有自己的緩衝層，將它們與操作系統層級檔案描述器混
     合使用會產生各種問題（例如資料的排序不符合預期）。

   在 3.2 版的變更: 忽略 *name* 屬性。

int PyObject_AsFileDescriptor(PyObject *p)
    * 属于 稳定 ABI.*

   回傳與 *p* 關聯的檔案描述器作為 int。如果物件是整數，則回傳其值。如
   果不是整數，則呼叫物件的 "fileno()" 方法（如果存在）；該方法必須回
   傳一個整數，它作為檔案描述器值回傳。設定例外並在失敗時回傳 "-1"。

PyObject *PyFile_GetLine(PyObject *p, int n)
    *回傳值：新的參照。** 属于 稳定 ABI.*

   等价于 "p.readline([n])" ，这个函数从对象 *p* 中读取一行。 *p* 可以
   是文件对象或具有 "readline()" 方法的任何对象。 如果 *n* 是 "0" ，则
   无论该行的长度如何，都会读取一行。 如果 *n* 大于 "0"，则从文件中读
   取不超过 *n* 个字节；可以返回行的一部分。 在这两种情况下，如果立即
   到达文件末尾，则返回空字符串。 但是，如果 *n* 小于 "0" ，则无论长度
   如何都会读取一行，但是如果立即到达文件末尾，则引发 "EOFError"。

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

   覆蓋 "io.open_code()" 的正常行為以透過提供的處理程式 (handler) 傳遞
   其參數。

   *handler* 函数的类型为：

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

      等价于 PyObject *(*)(PyObject *path, void *userData)，其中
      *path* 会确保为 "PyUnicodeObject"。

   *userData* 指標被傳遞到掛鉤函式 (hook function) 中。由於可能會從不
   同的執行環境 (runtime) 呼叫掛鉤函式，因此該指標不應直接指向 Python
   狀態。

   由於此掛鉤函式是在導入期間有意使用的，因此請避免在其執行期間導入新
   模組，除非它們已知有被凍結或在 "sys.modules" 中可用。

   一旦钩子被设定，它就不能被移除或替换，之后对
   "PyFile_SetOpenCodeHook()" 的调用也将失败，如果解释器已经被初始化，
   函数将返回 -1 并设置一个异常。

   在 "Py_Initialize()" 之前呼叫此函式是安全的。

   不帶引數地引發一個稽核事件 (auditing event) "setopencodehook"。

   在 3.8 版新加入.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
    * 属于 稳定 ABI.*

   将对象 *obj* 写入文件对象 *p*。 *flags* 唯一支持的旗标是
   "Py_PRINT_RAW"；如果给定，则写入对象的 "str()" 而不是 "repr()"。 成
   功时返回 "0"，失败时返回 "-1"；将设置适当的异常。

int PyFile_WriteString(const char *s, PyObject *p)
    * 属于 稳定 ABI.*

   寫入字串 *s* 到 檔案物件 *p*。當成功時回傳 0，而當失敗時回傳 -1，並
   會設定合適的例外狀況。
