Debian Codegraph @

Doc/c-api/file.rst

raw
1 .. highlight:: c
2
3 .. _fileobjects:
4
5 File objects
6 ------------
7
8 .. index:: pair: object; file
9
10 These APIs are a minimal emulation of the Python 2 C API for built-in file
11 objects, which used to rely on the buffered I/O (:c:expr:`FILE*`) support
12 from 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
14 I/O of the operating system. The functions described below are
15 convenience C wrappers over these new APIs, and meant mostly for internal
16 error reporting in the interpreter; third-party code is advised to access
17 the :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:expr:`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:
69
70 .. c:namespace:: NULL
71 .. c:type:: PyObject * (*Py_OpenCodeHookFunction)(PyObject *, void *)
72
73 Equivalent of :c:expr:`PyObject *(\*)(PyObject *path,
74 void *userData)`, where *path* is guaranteed to be
75 :c:type:`PyUnicodeObject`.
76
77 The *userData* pointer is passed into the hook function. Since hook
78 functions may be called from different runtimes, this pointer should not
79 refer directly to Python state.
80
81 As this hook is intentionally used during import, avoid importing new modules
82 during its execution unless they are known to be frozen or available in
83 ``sys.modules``.
84
85 Once a hook has been set, it cannot be removed or replaced, and later calls to
86 :c:func:`PyFile_SetOpenCodeHook` will fail. On failure, the function returns
87 -1 and sets an exception if the interpreter has been initialized.
88
89 This function is safe to call before :c:func:`Py_Initialize`.
90
91 .. audit-event:: setopencodehook "" c.PyFile_SetOpenCodeHook
92
93 .. versionadded:: 3.8
94
95
96 .. c:function:: PyObject *PyFile_OpenCodeObject(PyObject *path)
97
98 Open *path* with the mode ``'rb'``. *path* must be a Python :class:`str`
99 object. The behavior of this function may be overridden by
100 :c:func:`PyFile_SetOpenCodeHook` to allow for some preprocessing of the
101 text.
102
103 This is analogous to :func:`io.open_code` in Python.
104
105 On success, this function returns a :term:`strong reference` to a Python
106 file object. On failure, this function returns ``NULL`` with an exception
107 set.
108
109 .. versionadded:: 3.8
110
111
112 .. c:function:: PyObject *PyFile_OpenCode(const char *path)
113
114 Similar to :c:func:`PyFile_OpenCodeObject`, but *path* is a
115 UTF-8 encoded :c:expr:`const char*`.
116
117 .. versionadded:: 3.8
118
119
120 .. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
121
122 .. index:: single: Py_PRINT_RAW (C macro)
123
124 Write object *obj* to file object *p*. The only supported flag for *flags* is
125 :c:macro:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
126 instead of the :func:`repr`.
127
128 If *obj* is ``NULL``, write the string ``"<NULL>"``.
129
130 Return ``0`` on success or ``-1`` on failure; the
131 appropriate exception will be set.
132
133 .. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
134
135 Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
136 failure; the appropriate exception will be set.
137
138
139 Soft-deprecated API
140 ^^^^^^^^^^^^^^^^^^^
141
142 .. soft-deprecated:: 3.15
143
144 These are APIs that were included in Python's C API
145 by mistake. They are documented solely for completeness; use other
146 ``PyFile*`` APIs instead.
147
148 .. c:function:: PyObject *PyFile_NewStdPrinter(int fd)
149
150 Use :c:func:`PyFile_FromFd` with defaults (``fd, NULL, "w", -1, NULL, NULL, NULL, 0``) instead.
151
152 .. c:var:: PyTypeObject PyStdPrinter_Type
153
154 Type of file-like objects used internally at Python startup when :py:mod:`io` is
155 not yet available.
156 Use Python :py:func:`open` or :c:func:`PyFile_FromFd` to create file objects instead.