1.. highlight:: c 2 3.. _fileobjects: 4 5File Objects 6------------ 7 8.. index:: object: file 9 10These APIs are a minimal emulation of the Python 2 C API for built-in file 11objects, which used to rely on the buffered I/O (:c:type:`FILE*`) support 12from the C standard library. In Python 3, files and streams use the new 13:mod:`io` module, which defines several layers over the low-level unbuffered 14I/O of the operating system. The functions described below are 15convenience C wrappers over these new APIs, and meant mostly for internal 16error reporting in the interpreter; third-party code is advised to access 17the :mod:`io` APIs instead. 18 19 20.. c:function:: PyObject* PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd) 21 22 Create a Python file object from the file descriptor of an already 23 opened file *fd*. The arguments *name*, *encoding*, *errors* and *newline* 24 can be ``NULL`` to use the defaults; *buffering* can be *-1* to use the 25 default. *name* is ignored and kept for backward compatibility. Return 26 ``NULL`` on failure. For a more comprehensive description of the arguments, 27 please refer to the :func:`io.open` function documentation. 28 29 .. warning:: 30 31 Since Python streams have their own buffering layer, mixing them with 32 OS-level file descriptors can produce various issues (such as unexpected 33 ordering of data). 34 35 .. versionchanged:: 3.2 36 Ignore *name* attribute. 37 38 39.. c:function:: int PyObject_AsFileDescriptor(PyObject *p) 40 41 Return the file descriptor associated with *p* as an :c:type:`int`. If the 42 object is an integer, its value is returned. If not, the 43 object's :meth:`~io.IOBase.fileno` method is called if it exists; the 44 method must return an integer, which is returned as the file descriptor 45 value. Sets an exception and returns ``-1`` on failure. 46 47 48.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n) 49 50 .. index:: single: EOFError (built-in exception) 51 52 Equivalent to ``p.readline([n])``, this function reads one line from the 53 object *p*. *p* may be a file object or any object with a 54 :meth:`~io.IOBase.readline` 55 method. If *n* is ``0``, exactly one line is read, regardless of the length of 56 the line. If *n* is greater than ``0``, no more than *n* bytes will be read 57 from the file; a partial line can be returned. In both cases, an empty string 58 is returned if the end of the file is reached immediately. If *n* is less than 59 ``0``, however, one line is read regardless of length, but :exc:`EOFError` is 60 raised if the end of the file is reached immediately. 61 62 63.. c:function:: int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler) 64 65 Overrides the normal behavior of :func:`io.open_code` to pass its parameter 66 through the provided handler. 67 68 The handler is a function of type :c:type:`PyObject *(\*)(PyObject *path, 69 void *userData)`, where *path* is guaranteed to be :c:type:`PyUnicodeObject`. 70 71 The *userData* pointer is passed into the hook function. Since hook 72 functions may be called from different runtimes, this pointer should not 73 refer directly to Python state. 74 75 As this hook is intentionally used during import, avoid importing new modules 76 during its execution unless they are known to be frozen or available in 77 ``sys.modules``. 78 79 Once a hook has been set, it cannot be removed or replaced, and later calls to 80 :c:func:`PyFile_SetOpenCodeHook` will fail. On failure, the function returns 81 -1 and sets an exception if the interpreter has been initialized. 82 83 This function is safe to call before :c:func:`Py_Initialize`. 84 85 .. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook 86 87 .. versionadded:: 3.8 88 89 90 91.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags) 92 93 .. index:: single: Py_PRINT_RAW 94 95 Write object *obj* to file object *p*. The only supported flag for *flags* is 96 :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written 97 instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the 98 appropriate exception will be set. 99 100 101.. c:function:: int PyFile_WriteString(const char *s, PyObject *p) 102 103 Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on 104 failure; the appropriate exception will be set. 105