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(intfd,constchar*name,constchar*mode,intbuffering,constchar*encoding,constchar*errors,constchar*newline,intclosefd)¶

Return value: New reference. Part of theStable ABI.

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)¶

Part of theStable ABI.

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,intn)¶

Return value: New reference. Part of theStable ABI.

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_OpenCodeHookFunctionhandler)¶

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

Thehandler is a function of type:

typedefPyObject*(*Py_OpenCodeHookFunction)(PyObject*,void*)¶

Equivalent ofPyObject*(*)(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.

Added in version 3.8.

intPyFile_WriteObject(PyObject*obj,PyObject*p,intflags)¶

Part of theStable ABI.

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(constchar*s,PyObject*p)¶

Part of theStable ABI.

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