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