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