File Objects

Python 的内置文件对象完全在 C 标准库的FILE*支持下实现。这是一个实现细节，在将来的 Python 版本中可能会更改。

• PyFileObject

  • PyObject的此子类型表示 Python 文件对象。

• PyTypeObject PyFile_Type

  • PyTypeObject的此实例表示 Python 文件类型。这对于file和types.FileType暴露给 Python 程序。

• int PyFile_Check(PyObject ** p *)
  • 如果其参数是PyFileObject或PyFileObject的子类型，则返回 true。

在版本 2.2 中更改：接受允许的子类型。

• int PyFile_CheckExact(PyObject ** p *)
  • 如果其参数是PyFileObject，而不是PyFileObject的子类型，则返回 true。

2.2 版中的新Function。

• PyObject * PyFile_FromString(char 文件名，char* mode *)
  • 返回值：新参考.

成功后，返回一个新文件对象，该对象在* filename 给定的文件上打开，文件模式由 mode 给定，其中 mode 具有与标准 C 例程fopen()相同的语义。失败时，返回 NULL *。

• PyObject * PyFile_FromFile(FILE *fp ，char name *，char *mode ，int( close *)(FILE *))
  • 返回值：新参考.

从已经打开的标准 C 文件指针* fp 创建一个新的PyFileObject。当应该关闭文件时，将调用 close 函数。返回 NULL 并在失败时使用 close *关闭文件。 * close 是可选的，可以设置为 NULL *。

• FILE * PyFile_AsFile(PyObject ** p *)
  • 返回与* p *关联的文件对象为FILE*。

如果在释放GIL时调用方将使用返回的FILE*对象，则它还必须适当地调用下面介绍的PyFile_IncUseCount()和PyFile_DecUseCount()函数。

• 无效PyFile_IncUseCount(PyFileObject ** p *)
  • 增加 PyFileObject 的内部使用计数，以指示正在使用基础FILE*。这样可以防止 Python 从另一个线程对其调用 f_close()。调用者完成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 版的新Function。

• 无效PyFile_DecUseCount(PyFileObject ** p *)
  • 减少 PyFileObject 的内部 unlocked_count 成员，以指示调用者使用自己的FILE*完成。只能调用此方法来撤消先前对PyFile_IncUseCount()的调用。

调用此函数时，必须按住GIL(请参见上面的示例)。

2.6 版的新Function。

• PyObject * PyFile_GetLine(PyObject ** p *，int * n *)
  • 返回值：新参考.

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

• PyObject * PyFile_Name(PyObject ** p *)
  • *返回值：借用参考。

返回* p *指定的文件名作为字符串对象。

• 无效PyFile_SetBufSize(PyFileObject ** p *，int * n *)
  • 仅在具有setvbuf()的系统上可用。仅应在创建文件对象后立即调用此方法。

• int PyFile_SetEncoding(PyFileObject *p ，const char enc *)
  • 将 Unicode 输出的文件编码设置为* enc *。成功返回1，失败返回0。

2.3 版的新Function。

• int PyFile_SetEncodingAndErrors(PyFileObject *p ，const char enc ， errors)
  • 将 Unicode 输出的文件编码设置为* enc ，并将其错误模式设置为 err *。成功返回1，失败返回0。

2.6 版的新Function。

• int PyFile_SoftSpace(PyObject ** p *，int * newflag *)
  • 存在此Function供解释器内部使用。将* p 的softspace属性设置为 newflag *并返回前一个值。 * p *不一定是该Function正常工作的文件对象；支持任何对象(只有可以设置softspace属性，这才是有趣的)。此函数清除所有错误，如果该属性不存在或在检索它时出错，则将返回0作为前一个值。无法pass此Function检测错误，但不需要这样做。

• int PyFile_WriteObject(PyObject *obj ，PyObject p *，int * flags *)
  • 将对象* obj 写入文件对象 p *。 * flags *支持的唯一标志是Py_PRINT_RAW；如果给出，则写入对象的str()而不是repr()。如果成功则返回0，如果失败则返回-1；将设置适当的 exception。

• int PyFile_WriteString(const char *s ，PyObject p *)
  • 将字符串* s 写入文件对象 p *。成功返回0或失败返回-1；将设置适当的 exception。