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