1.. highlightlang:: c 2 3.. _fileobjects: 4 5File Objects 6------------ 7 8.. index:: object: file 9 10Python's built-in file objects are implemented entirely on the :c:type:`FILE\*` 11support from the C standard library. This is an implementation detail and may 12change in future releases of Python. 13 14 15.. c:type:: PyFileObject 16 17 This subtype of :c:type:`PyObject` represents a Python file object. 18 19 20.. c:var:: PyTypeObject PyFile_Type 21 22 .. index:: single: FileType (in module types) 23 24 This instance of :c:type:`PyTypeObject` represents the Python file type. This is 25 exposed to Python programs as ``file`` and ``types.FileType``. 26 27 28.. c:function:: int PyFile_Check(PyObject *p) 29 30 Return true if its argument is a :c:type:`PyFileObject` or a subtype of 31 :c:type:`PyFileObject`. 32 33 .. versionchanged:: 2.2 34 Allowed subtypes to be accepted. 35 36 37.. c:function:: int PyFile_CheckExact(PyObject *p) 38 39 Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of 40 :c:type:`PyFileObject`. 41 42 .. versionadded:: 2.2 43 44 45.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode) 46 47 .. index:: single: fopen() 48 49 On success, return a new file object that is opened on the file given by 50 *filename*, with a file mode given by *mode*, where *mode* has the same 51 semantics as the standard C routine :c:func:`fopen`. On failure, return *NULL*. 52 53 54.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*)) 55 56 Create a new :c:type:`PyFileObject` from the already-open standard C file 57 pointer, *fp*. The function *close* will be called when the file should be 58 closed. Return *NULL* and close the file using *close* on failure. 59 *close* is optional and can be set to *NULL*. 60 61 62.. c:function:: FILE* PyFile_AsFile(PyObject \*p) 63 64 Return the file object associated with *p* as a :c:type:`FILE\*`. 65 66 If the caller will ever use the returned :c:type:`FILE\*` object while 67 the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and 68 :c:func:`PyFile_DecUseCount` functions described below as appropriate. 69 70 71.. c:function:: void PyFile_IncUseCount(PyFileObject \*p) 72 73 Increments the PyFileObject's internal use count to indicate 74 that the underlying :c:type:`FILE\*` is being used. 75 This prevents Python from calling f_close() on it from another thread. 76 Callers of this must call :c:func:`PyFile_DecUseCount` when they are 77 finished with the :c:type:`FILE\*`. Otherwise the file object will 78 never be closed by Python. 79 80 The :term:`GIL` must be held while calling this function. 81 82 The suggested use is to call this after :c:func:`PyFile_AsFile` and before 83 you release the GIL:: 84 85 FILE *fp = PyFile_AsFile(p); 86 PyFile_IncUseCount(p); 87 /* ... */ 88 Py_BEGIN_ALLOW_THREADS 89 do_something(fp); 90 Py_END_ALLOW_THREADS 91 /* ... */ 92 PyFile_DecUseCount(p); 93 94 .. versionadded:: 2.6 95 96 97.. c:function:: void PyFile_DecUseCount(PyFileObject \*p) 98 99 Decrements the PyFileObject's internal unlocked_count member to 100 indicate that the caller is done with its own use of the :c:type:`FILE\*`. 101 This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`. 102 103 The :term:`GIL` must be held while calling this function (see the example 104 above). 105 106 .. versionadded:: 2.6 107 108 109.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n) 110 111 .. index:: single: EOFError (built-in exception) 112 113 Equivalent to ``p.readline([n])``, this function reads one line from the 114 object *p*. *p* may be a file object or any object with a 115 :meth:`~io.IOBase.readline` 116 method. If *n* is ``0``, exactly one line is read, regardless of the length of 117 the line. If *n* is greater than ``0``, no more than *n* bytes will be read 118 from the file; a partial line can be returned. In both cases, an empty string 119 is returned if the end of the file is reached immediately. If *n* is less than 120 ``0``, however, one line is read regardless of length, but :exc:`EOFError` is 121 raised if the end of the file is reached immediately. 122 123 124.. c:function:: PyObject* PyFile_Name(PyObject *p) 125 126 Return the name of the file specified by *p* as a string object. 127 128 129.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n) 130 131 .. index:: single: setvbuf() 132 133 Available on systems with :c:func:`setvbuf` only. This should only be called 134 immediately after file object creation. 135 136 137.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc) 138 139 Set the file's encoding for Unicode output to *enc*. Return ``1`` on success and ``0`` 140 on failure. 141 142 .. versionadded:: 2.3 143 144 145.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors) 146 147 Set the file's encoding for Unicode output to *enc*, and its error 148 mode to *err*. Return ``1`` on success and ``0`` on failure. 149 150 .. versionadded:: 2.6 151 152 153.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag) 154 155 .. index:: single: softspace (file attribute) 156 157 This function exists for internal use by the interpreter. Set the 158 :attr:`softspace` attribute of *p* to *newflag* and return the previous value. 159 *p* does not have to be a file object for this function to work properly; any 160 object is supported (thought its only interesting if the :attr:`softspace` 161 attribute can be set). This function clears any errors, and will return ``0`` 162 as the previous value if the attribute either does not exist or if there were 163 errors in retrieving it. There is no way to detect errors from this function, 164 but doing so should not be needed. 165 166 167.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags) 168 169 .. index:: single: Py_PRINT_RAW 170 171 Write object *obj* to file object *p*. The only supported flag for *flags* is 172 :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written 173 instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the 174 appropriate exception will be set. 175 176 177.. c:function:: int PyFile_WriteString(const char *s, PyObject *p) 178 179 Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on 180 failure; the appropriate exception will be set. 181