Branch data Line data Source code
1 : : /*[clinic input]
2 : : preserve
3 : : [clinic start generated code]*/
4 : :
5 : : PyDoc_STRVAR(_io_open__doc__,
6 : : "open($module, /, file, mode=\'r\', buffering=-1, encoding=None,\n"
7 : : " errors=None, newline=None, closefd=True, opener=None)\n"
8 : : "--\n"
9 : : "\n"
10 : : "Open file and return a stream. Raise OSError upon failure.\n"
11 : : "\n"
12 : : "file is either a text or byte string giving the name (and the path\n"
13 : : "if the file isn\'t in the current working directory) of the file to\n"
14 : : "be opened or an integer file descriptor of the file to be\n"
15 : : "wrapped. (If a file descriptor is given, it is closed when the\n"
16 : : "returned I/O object is closed, unless closefd is set to False.)\n"
17 : : "\n"
18 : : "mode is an optional string that specifies the mode in which the file\n"
19 : : "is opened. It defaults to \'r\' which means open for reading in text\n"
20 : : "mode. Other common values are \'w\' for writing (truncating the file if\n"
21 : : "it already exists), \'x\' for creating and writing to a new file, and\n"
22 : : "\'a\' for appending (which on some Unix systems, means that all writes\n"
23 : : "append to the end of the file regardless of the current seek position).\n"
24 : : "In text mode, if encoding is not specified the encoding used is platform\n"
25 : : "dependent: locale.getencoding() is called to get the current locale encoding.\n"
26 : : "(For reading and writing raw bytes use binary mode and leave encoding\n"
27 : : "unspecified.) The available modes are:\n"
28 : : "\n"
29 : : "========= ===============================================================\n"
30 : : "Character Meaning\n"
31 : : "--------- ---------------------------------------------------------------\n"
32 : : "\'r\' open for reading (default)\n"
33 : : "\'w\' open for writing, truncating the file first\n"
34 : : "\'x\' create a new file and open it for writing\n"
35 : : "\'a\' open for writing, appending to the end of the file if it exists\n"
36 : : "\'b\' binary mode\n"
37 : : "\'t\' text mode (default)\n"
38 : : "\'+\' open a disk file for updating (reading and writing)\n"
39 : : "========= ===============================================================\n"
40 : : "\n"
41 : : "The default mode is \'rt\' (open for reading text). For binary random\n"
42 : : "access, the mode \'w+b\' opens and truncates the file to 0 bytes, while\n"
43 : : "\'r+b\' opens the file without truncation. The \'x\' mode implies \'w\' and\n"
44 : : "raises an `FileExistsError` if the file already exists.\n"
45 : : "\n"
46 : : "Python distinguishes between files opened in binary and text modes,\n"
47 : : "even when the underlying operating system doesn\'t. Files opened in\n"
48 : : "binary mode (appending \'b\' to the mode argument) return contents as\n"
49 : : "bytes objects without any decoding. In text mode (the default, or when\n"
50 : : "\'t\' is appended to the mode argument), the contents of the file are\n"
51 : : "returned as strings, the bytes having been first decoded using a\n"
52 : : "platform-dependent encoding or using the specified encoding if given.\n"
53 : : "\n"
54 : : "buffering is an optional integer used to set the buffering policy.\n"
55 : : "Pass 0 to switch buffering off (only allowed in binary mode), 1 to select\n"
56 : : "line buffering (only usable in text mode), and an integer > 1 to indicate\n"
57 : : "the size of a fixed-size chunk buffer. When no buffering argument is\n"
58 : : "given, the default buffering policy works as follows:\n"
59 : : "\n"
60 : : "* Binary files are buffered in fixed-size chunks; the size of the buffer\n"
61 : : " is chosen using a heuristic trying to determine the underlying device\'s\n"
62 : : " \"block size\" and falling back on `io.DEFAULT_BUFFER_SIZE`.\n"
63 : : " On many systems, the buffer will typically be 4096 or 8192 bytes long.\n"
64 : : "\n"
65 : : "* \"Interactive\" text files (files for which isatty() returns True)\n"
66 : : " use line buffering. Other text files use the policy described above\n"
67 : : " for binary files.\n"
68 : : "\n"
69 : : "encoding is the name of the encoding used to decode or encode the\n"
70 : : "file. This should only be used in text mode. The default encoding is\n"
71 : : "platform dependent, but any encoding supported by Python can be\n"
72 : : "passed. See the codecs module for the list of supported encodings.\n"
73 : : "\n"
74 : : "errors is an optional string that specifies how encoding errors are to\n"
75 : : "be handled---this argument should not be used in binary mode. Pass\n"
76 : : "\'strict\' to raise a ValueError exception if there is an encoding error\n"
77 : : "(the default of None has the same effect), or pass \'ignore\' to ignore\n"
78 : : "errors. (Note that ignoring encoding errors can lead to data loss.)\n"
79 : : "See the documentation for codecs.register or run \'help(codecs.Codec)\'\n"
80 : : "for a list of the permitted encoding error strings.\n"
81 : : "\n"
82 : : "newline controls how universal newlines works (it only applies to text\n"
83 : : "mode). It can be None, \'\', \'\\n\', \'\\r\', and \'\\r\\n\'. It works as\n"
84 : : "follows:\n"
85 : : "\n"
86 : : "* On input, if newline is None, universal newlines mode is\n"
87 : : " enabled. Lines in the input can end in \'\\n\', \'\\r\', or \'\\r\\n\', and\n"
88 : : " these are translated into \'\\n\' before being returned to the\n"
89 : : " caller. If it is \'\', universal newline mode is enabled, but line\n"
90 : : " endings are returned to the caller untranslated. If it has any of\n"
91 : : " the other legal values, input lines are only terminated by the given\n"
92 : : " string, and the line ending is returned to the caller untranslated.\n"
93 : : "\n"
94 : : "* On output, if newline is None, any \'\\n\' characters written are\n"
95 : : " translated to the system default line separator, os.linesep. If\n"
96 : : " newline is \'\' or \'\\n\', no translation takes place. If newline is any\n"
97 : : " of the other legal values, any \'\\n\' characters written are translated\n"
98 : : " to the given string.\n"
99 : : "\n"
100 : : "If closefd is False, the underlying file descriptor will be kept open\n"
101 : : "when the file is closed. This does not work when a file name is given\n"
102 : : "and must be True in that case.\n"
103 : : "\n"
104 : : "A custom opener can be used by passing a callable as *opener*. The\n"
105 : : "underlying file descriptor for the file object is then obtained by\n"
106 : : "calling *opener* with (*file*, *flags*). *opener* must return an open\n"
107 : : "file descriptor (passing os.open as *opener* results in functionality\n"
108 : : "similar to passing None).\n"
109 : : "\n"
110 : : "open() returns a file object whose type depends on the mode, and\n"
111 : : "through which the standard file operations such as reading and writing\n"
112 : : "are performed. When open() is used to open a file in a text mode (\'w\',\n"
113 : : "\'r\', \'wt\', \'rt\', etc.), it returns a TextIOWrapper. When used to open\n"
114 : : "a file in a binary mode, the returned class varies: in read binary\n"
115 : : "mode, it returns a BufferedReader; in write binary and append binary\n"
116 : : "modes, it returns a BufferedWriter, and in read/write mode, it returns\n"
117 : : "a BufferedRandom.\n"
118 : : "\n"
119 : : "It is also possible to use a string or bytearray as a file for both\n"
120 : : "reading and writing. For strings StringIO can be used like a file\n"
121 : : "opened in a text mode, and for bytes a BytesIO can be used like a file\n"
122 : : "opened in a binary mode.");
123 : :
124 : : #define _IO_OPEN_METHODDEF \
125 : : {"open", _PyCFunction_CAST(_io_open), METH_FASTCALL|METH_KEYWORDS, _io_open__doc__},
126 : :
127 : : static PyObject *
128 : : _io_open_impl(PyObject *module, PyObject *file, const char *mode,
129 : : int buffering, const char *encoding, const char *errors,
130 : : const char *newline, int closefd, PyObject *opener);
131 : :
132 : : static PyObject *
133 : 306940 : _io_open(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
134 : : {
135 : 306940 : PyObject *return_value = NULL;
136 : : static const char * const _keywords[] = {"file", "mode", "buffering", "encoding", "errors", "newline", "closefd", "opener", NULL};
137 : : static _PyArg_Parser _parser = {NULL, _keywords, "open", 0};
138 : : PyObject *argsbuf[8];
139 [ + + ]: 306940 : Py_ssize_t noptargs = nargs + (kwnames ? PyTuple_GET_SIZE(kwnames) : 0) - 1;
140 : : PyObject *file;
141 : 306940 : const char *mode = "r";
142 : 306940 : int buffering = -1;
143 : 306940 : const char *encoding = NULL;
144 : 306940 : const char *errors = NULL;
145 : 306940 : const char *newline = NULL;
146 : 306940 : int closefd = 1;
147 : 306940 : PyObject *opener = Py_None;
148 : :
149 [ + + + - : 306940 : args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 8, 0, argsbuf);
+ - - + ]
150 [ - + ]: 306940 : if (!args) {
151 : 0 : goto exit;
152 : : }
153 : 306940 : file = args[0];
154 [ + + ]: 306940 : if (!noptargs) {
155 : 307 : goto skip_optional_pos;
156 : : }
157 [ + + ]: 306633 : if (args[1]) {
158 [ - + ]: 299874 : if (!PyUnicode_Check(args[1])) {
159 : 0 : _PyArg_BadArgument("open", "argument 'mode'", "str", args[1]);
160 : 0 : goto exit;
161 : : }
162 : : Py_ssize_t mode_length;
163 : 299874 : mode = PyUnicode_AsUTF8AndSize(args[1], &mode_length);
164 [ - + ]: 299874 : if (mode == NULL) {
165 : 0 : goto exit;
166 : : }
167 [ - + ]: 299874 : if (strlen(mode) != (size_t)mode_length) {
168 : 0 : PyErr_SetString(PyExc_ValueError, "embedded null character");
169 : 0 : goto exit;
170 : : }
171 [ + + ]: 299874 : if (!--noptargs) {
172 : 270047 : goto skip_optional_pos;
173 : : }
174 : : }
175 [ + + ]: 36586 : if (args[2]) {
176 : 22729 : buffering = _PyLong_AsInt(args[2]);
177 [ + + - + ]: 22729 : if (buffering == -1 && PyErr_Occurred()) {
178 : 0 : goto exit;
179 : : }
180 [ + + ]: 22729 : if (!--noptargs) {
181 : 9687 : goto skip_optional_pos;
182 : : }
183 : : }
184 [ + + ]: 26899 : if (args[3]) {
185 [ + + ]: 25578 : if (args[3] == Py_None) {
186 : 11556 : encoding = NULL;
187 : : }
188 [ + - ]: 14022 : else if (PyUnicode_Check(args[3])) {
189 : : Py_ssize_t encoding_length;
190 : 14022 : encoding = PyUnicode_AsUTF8AndSize(args[3], &encoding_length);
191 [ - + ]: 14022 : if (encoding == NULL) {
192 : 0 : goto exit;
193 : : }
194 [ - + ]: 14022 : if (strlen(encoding) != (size_t)encoding_length) {
195 : 0 : PyErr_SetString(PyExc_ValueError, "embedded null character");
196 : 0 : goto exit;
197 : : }
198 : : }
199 : : else {
200 : 0 : _PyArg_BadArgument("open", "argument 'encoding'", "str or None", args[3]);
201 : 0 : goto exit;
202 : : }
203 [ + + ]: 25578 : if (!--noptargs) {
204 : 10577 : goto skip_optional_pos;
205 : : }
206 : : }
207 [ + + ]: 16322 : if (args[4]) {
208 [ + + ]: 13832 : if (args[4] == Py_None) {
209 : 13159 : errors = NULL;
210 : : }
211 [ + - ]: 673 : else if (PyUnicode_Check(args[4])) {
212 : : Py_ssize_t errors_length;
213 : 673 : errors = PyUnicode_AsUTF8AndSize(args[4], &errors_length);
214 [ - + ]: 673 : if (errors == NULL) {
215 : 0 : goto exit;
216 : : }
217 [ - + ]: 673 : if (strlen(errors) != (size_t)errors_length) {
218 : 0 : PyErr_SetString(PyExc_ValueError, "embedded null character");
219 : 0 : goto exit;
220 : : }
221 : : }
222 : : else {
223 : 0 : _PyArg_BadArgument("open", "argument 'errors'", "str or None", args[4]);
224 : 0 : goto exit;
225 : : }
226 [ + + ]: 13832 : if (!--noptargs) {
227 : 983 : goto skip_optional_pos;
228 : : }
229 : : }
230 [ + + ]: 15339 : if (args[5]) {
231 [ + + ]: 13100 : if (args[5] == Py_None) {
232 : 12110 : newline = NULL;
233 : : }
234 [ + - ]: 990 : else if (PyUnicode_Check(args[5])) {
235 : : Py_ssize_t newline_length;
236 : 990 : newline = PyUnicode_AsUTF8AndSize(args[5], &newline_length);
237 [ - + ]: 990 : if (newline == NULL) {
238 : 0 : goto exit;
239 : : }
240 [ - + ]: 990 : if (strlen(newline) != (size_t)newline_length) {
241 : 0 : PyErr_SetString(PyExc_ValueError, "embedded null character");
242 : 0 : goto exit;
243 : : }
244 : : }
245 : : else {
246 : 0 : _PyArg_BadArgument("open", "argument 'newline'", "str or None", args[5]);
247 : 0 : goto exit;
248 : : }
249 [ + + ]: 13100 : if (!--noptargs) {
250 : 1078 : goto skip_optional_pos;
251 : : }
252 : : }
253 [ + + ]: 14261 : if (args[6]) {
254 : 12198 : closefd = _PyLong_AsInt(args[6]);
255 [ - + - - ]: 12198 : if (closefd == -1 && PyErr_Occurred()) {
256 : 0 : goto exit;
257 : : }
258 [ + + ]: 12198 : if (!--noptargs) {
259 : 12197 : goto skip_optional_pos;
260 : : }
261 : : }
262 : 2064 : opener = args[7];
263 : 306940 : skip_optional_pos:
264 : 306940 : return_value = _io_open_impl(module, file, mode, buffering, encoding, errors, newline, closefd, opener);
265 : :
266 : 306939 : exit:
267 : 306939 : return return_value;
268 : : }
269 : :
270 : : PyDoc_STRVAR(_io_text_encoding__doc__,
271 : : "text_encoding($module, encoding, stacklevel=2, /)\n"
272 : : "--\n"
273 : : "\n"
274 : : "A helper function to choose the text encoding.\n"
275 : : "\n"
276 : : "When encoding is not None, this function returns it.\n"
277 : : "Otherwise, this function returns the default text encoding\n"
278 : : "(i.e. \"locale\" or \"utf-8\" depends on UTF-8 mode).\n"
279 : : "\n"
280 : : "This function emits an EncodingWarning if encoding is None and\n"
281 : : "sys.flags.warn_default_encoding is true.\n"
282 : : "\n"
283 : : "This can be used in APIs with an encoding=None parameter.\n"
284 : : "However, please consider using encoding=\"utf-8\" for new APIs.");
285 : :
286 : : #define _IO_TEXT_ENCODING_METHODDEF \
287 : : {"text_encoding", _PyCFunction_CAST(_io_text_encoding), METH_FASTCALL, _io_text_encoding__doc__},
288 : :
289 : : static PyObject *
290 : : _io_text_encoding_impl(PyObject *module, PyObject *encoding, int stacklevel);
291 : :
292 : : static PyObject *
293 : 2255 : _io_text_encoding(PyObject *module, PyObject *const *args, Py_ssize_t nargs)
294 : : {
295 : 2255 : PyObject *return_value = NULL;
296 : : PyObject *encoding;
297 : 2255 : int stacklevel = 2;
298 : :
299 [ + - - + : 2255 : if (!_PyArg_CheckPositional("text_encoding", nargs, 1, 2)) {
- - ]
300 : 0 : goto exit;
301 : : }
302 : 2255 : encoding = args[0];
303 [ + - ]: 2255 : if (nargs < 2) {
304 : 2255 : goto skip_optional;
305 : : }
306 : 0 : stacklevel = _PyLong_AsInt(args[1]);
307 [ # # # # ]: 0 : if (stacklevel == -1 && PyErr_Occurred()) {
308 : 0 : goto exit;
309 : : }
310 : 0 : skip_optional:
311 : 2255 : return_value = _io_text_encoding_impl(module, encoding, stacklevel);
312 : :
313 : 2255 : exit:
314 : 2255 : return return_value;
315 : : }
316 : :
317 : : PyDoc_STRVAR(_io_open_code__doc__,
318 : : "open_code($module, /, path)\n"
319 : : "--\n"
320 : : "\n"
321 : : "Opens the provided file with the intent to import the contents.\n"
322 : : "\n"
323 : : "This may perform extra validation beyond open(), but is otherwise interchangeable\n"
324 : : "with calling open(path, \'rb\').");
325 : :
326 : : #define _IO_OPEN_CODE_METHODDEF \
327 : : {"open_code", _PyCFunction_CAST(_io_open_code), METH_FASTCALL|METH_KEYWORDS, _io_open_code__doc__},
328 : :
329 : : static PyObject *
330 : : _io_open_code_impl(PyObject *module, PyObject *path);
331 : :
332 : : static PyObject *
333 : 178737 : _io_open_code(PyObject *module, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
334 : : {
335 : 178737 : PyObject *return_value = NULL;
336 : : static const char * const _keywords[] = {"path", NULL};
337 : : static _PyArg_Parser _parser = {NULL, _keywords, "open_code", 0};
338 : : PyObject *argsbuf[1];
339 : : PyObject *path;
340 : :
341 [ + - + - : 178737 : args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser, 1, 1, 0, argsbuf);
+ - - + ]
342 [ - + ]: 178737 : if (!args) {
343 : 0 : goto exit;
344 : : }
345 [ - + ]: 178737 : if (!PyUnicode_Check(args[0])) {
346 : 0 : _PyArg_BadArgument("open_code", "argument 'path'", "str", args[0]);
347 : 0 : goto exit;
348 : : }
349 [ - + ]: 178737 : if (PyUnicode_READY(args[0]) == -1) {
350 : 0 : goto exit;
351 : : }
352 : 178737 : path = args[0];
353 : 178737 : return_value = _io_open_code_impl(module, path);
354 : :
355 : 178737 : exit:
356 : 178737 : return return_value;
357 : : }
358 : : /*[clinic end generated code: output=c4d7e4ef878985f8 input=a9049054013a1b77]*/
|
