File Objects

These APIs are a minimal emulation of the Python 2 C API for built-in fileobjects, which used to rely on the buffered I/O (FILE*) supportfrom the C standard library. In Python 3, files and streams use the newio module, which defines several layers over the low-level unbufferedI/O of the operating system. The functions described below areconvenience C wrappers over these new APIs, and meant mostly for internalerror reporting in the interpreter; third-party code is advised to accesstheio APIs instead.

PyObject*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.

Create a Python file object from the file descriptor of an alreadyopened filefd. The argumentsname,encoding,errors andnewlinecan beNULL to use the defaults;buffering can be-1 to use thedefault.name is ignored and kept for backward compatibility. ReturnNULL on failure. For a more comprehensive description of the arguments,please refer to theio.open() function documentation.

Warning

Since Python streams have their own buffering layer, mixing them withOS-level file descriptors can produce various issues (such as unexpectedordering of data).

Changed in version 3.2:Ignorename attribute.

intPyObject_AsFileDescriptor(PyObject *p)

Return the file descriptor associated withp as anint. If theobject is an integer, its value is returned. If not, theobject’sfileno() method is called if it exists; themethod must return an integer, which is returned as the file descriptorvalue. Sets an exception and returns-1 on failure.

PyObject*PyFile_GetLine(PyObject *p, int n)
Return value: New reference.

Equivalent top.readline([n]), this function reads one line from theobjectp.p may be a file object or any object with areadline()method. Ifn is0, exactly one line is read, regardless of the length ofthe line. Ifn is greater than0, no more thann bytes will be readfrom the file; a partial line can be returned. In both cases, an empty stringis returned if the end of the file is reached immediately. Ifn is less than0, however, one line is read regardless of length, butEOFError israised if the end of the file is reached immediately.

intPyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

Overrides the normal behavior ofio.open_code() to pass its parameterthrough the provided handler.

The handler is a function of typePyObject*(*)(PyObject*path,void*userData), wherepath is guaranteed to bePyUnicodeObject.

TheuserData pointer is passed into the hook function. Since hookfunctions may be called from different runtimes, this pointer should notrefer directly to Python state.

As this hook is intentionally used during import, avoid importing new modulesduring its execution unless they are known to be frozen or available insys.modules.

Once a hook has been set, it cannot be removed or replaced, and later calls toPyFile_SetOpenCodeHook() will fail. On failure, the function returns-1 and sets an exception if the interpreter has been initialized.

This function is safe to call beforePy_Initialize().

Raises anauditing eventsetopencodehook with no arguments.

New in version 3.8.

intPyFile_WriteObject(PyObject *obj,PyObject *p, int flags)

Write objectobj to file objectp. The only supported flag forflags isPy_PRINT_RAW; if given, thestr() of the object is writteninstead of therepr(). Return0 on success or-1 on failure; theappropriate exception will be set.

intPyFile_WriteString(const char *s,PyObject *p)

Write strings to file objectp. Return0 on success or-1 onfailure; the appropriate exception will be set.