Debian Codegraph @

Modules/_io/clinic/fileio.c.h

raw
1 /*[clinic input]
2 preserve
3 [clinic start generated code]*/
4
5 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
6 # include "pycore_gc.h" // PyGC_Head
7 # include "pycore_runtime.h" // _Py_ID()
8 #endif
9 #include "pycore_abstract.h" // _Py_convert_optional_to_ssize_t()
10 #include "pycore_modsupport.h" // _PyArg_UnpackKeywords()
11
12 PyDoc_STRVAR(_io_FileIO_close__doc__,
13 "close($self, /)\n"
14 "--\n"
15 "\n"
16 "Close the file.\n"
17 "\n"
18 "A closed file cannot be used for further I/O operations. close()\n"
19 "may be called more than once without error.");
20
21 #define _IO_FILEIO_CLOSE_METHODDEF \
22 {"close", _PyCFunction_CAST(_io_FileIO_close), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_close__doc__},
23
24 static PyObject *
25 _io_FileIO_close_impl(fileio *self, PyTypeObject *cls);
26
27 static PyObject *
28 _io_FileIO_close(PyObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
29 {
30 if (nargs || (kwnames && PyTuple_GET_SIZE(kwnames))) {
31 PyErr_SetString(PyExc_TypeError, "close() takes no arguments");
32 return NULL;
33 }
34 return _io_FileIO_close_impl((fileio *)self, cls);
35 }
36
37 PyDoc_STRVAR(_io_FileIO___init____doc__,
38 "FileIO(file, mode=\'r\', closefd=True, opener=None)\n"
39 "--\n"
40 "\n"
41 "Open a file.\n"
42 "\n"
43 "The mode can be \'r\' (default), \'w\', \'x\' or \'a\' for reading,\n"
44 "writing, exclusive creation or appending. The file will be created\n"
45 "if it doesn\'t exist when opened for writing or appending; it will be\n"
46 "truncated when opened for writing. A FileExistsError will be raised\n"
47 "if it already exists when opened for creating. Opening a file for\n"
48 "creating implies writing so this mode behaves in a similar way to\n"
49 "\'w\'. Add a \'+\' to the mode to allow simultaneous reading and\n"
50 "writing.\n"
51 "\n"
52 "A custom opener can be used by passing a callable as *opener*.\n"
53 "The underlying file descriptor for the file object is then obtained\n"
54 "by calling opener with (*name*, *flags*). *opener* must return\n"
55 "an open file descriptor (passing os.open as *opener* results in\n"
56 "functionality similar to passing None).");
57
58 static int
59 _io_FileIO___init___impl(fileio *self, PyObject *nameobj, const char *mode,
60 int closefd, PyObject *opener);
61
62 static int
63 _io_FileIO___init__(PyObject *self, PyObject *args, PyObject *kwargs)
64 {
65 int return_value = -1;
66 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
67
68 #define NUM_KEYWORDS 4
69 static struct {
70 PyGC_Head _this_is_not_used;
71 PyObject_VAR_HEAD
72 Py_hash_t ob_hash;
73 PyObject *ob_item[NUM_KEYWORDS];
74 } _kwtuple = {
75 .ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
76 .ob_hash = -1,
77 .ob_item = { &_Py_ID(file), &_Py_ID(mode), &_Py_ID(closefd), &_Py_ID(opener), },
78 };
79 #undef NUM_KEYWORDS
80 #define KWTUPLE (&_kwtuple.ob_base.ob_base)
81
82 #else // !Py_BUILD_CORE
83 # define KWTUPLE NULL
84 #endif // !Py_BUILD_CORE
85
86 static const char * const _keywords[] = {"file", "mode", "closefd", "opener", NULL};
87 static _PyArg_Parser _parser = {
88 .keywords = _keywords,
89 .fname = "FileIO",
90 .kwtuple = KWTUPLE,
91 };
92 #undef KWTUPLE
93 PyObject *argsbuf[4];
94 PyObject * const *fastargs;
95 Py_ssize_t nargs = PyTuple_GET_SIZE(args);
96 Py_ssize_t noptargs = nargs + (kwargs ? PyDict_GET_SIZE(kwargs) : 0) - 1;
97 PyObject *nameobj;
98 const char *mode = "r";
99 int closefd = 1;
100 PyObject *opener = Py_None;
101
102 fastargs = _PyArg_UnpackKeywords(_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL, &_parser,
103 /*minpos*/ 1, /*maxpos*/ 4, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
104 if (!fastargs) {
105 goto exit;
106 }
107 nameobj = fastargs[0];
108 if (!noptargs) {
109 goto skip_optional_pos;
110 }
111 if (fastargs[1]) {
112 if (!PyUnicode_Check(fastargs[1])) {
113 _PyArg_BadArgument("FileIO", "argument 'mode'", "str", fastargs[1]);
114 goto exit;
115 }
116 Py_ssize_t mode_length;
117 mode = PyUnicode_AsUTF8AndSize(fastargs[1], &mode_length);
118 if (mode == NULL) {
119 goto exit;
120 }
121 if (strlen(mode) != (size_t)mode_length) {
122 PyErr_SetString(PyExc_ValueError, "embedded null character");
123 goto exit;
124 }
125 if (!--noptargs) {
126 goto skip_optional_pos;
127 }
128 }
129 if (fastargs[2]) {
130 closefd = PyObject_IsTrue(fastargs[2]);
131 if (closefd < 0) {
132 goto exit;
133 }
134 if (!--noptargs) {
135 goto skip_optional_pos;
136 }
137 }
138 opener = fastargs[3];
139 skip_optional_pos:
140 return_value = _io_FileIO___init___impl((fileio *)self, nameobj, mode, closefd, opener);
141
142 exit:
143 return return_value;
144 }
145
146 PyDoc_STRVAR(_io_FileIO_fileno__doc__,
147 "fileno($self, /)\n"
148 "--\n"
149 "\n"
150 "Return the underlying file descriptor (an integer).");
151
152 #define _IO_FILEIO_FILENO_METHODDEF \
153 {"fileno", (PyCFunction)_io_FileIO_fileno, METH_NOARGS, _io_FileIO_fileno__doc__},
154
155 static PyObject *
156 _io_FileIO_fileno_impl(fileio *self);
157
158 static PyObject *
159 _io_FileIO_fileno(PyObject *self, PyObject *Py_UNUSED(ignored))
160 {
161 return _io_FileIO_fileno_impl((fileio *)self);
162 }
163
164 PyDoc_STRVAR(_io_FileIO_readable__doc__,
165 "readable($self, /)\n"
166 "--\n"
167 "\n"
168 "True if file was opened in a read mode.");
169
170 #define _IO_FILEIO_READABLE_METHODDEF \
171 {"readable", (PyCFunction)_io_FileIO_readable, METH_NOARGS, _io_FileIO_readable__doc__},
172
173 static PyObject *
174 _io_FileIO_readable_impl(fileio *self);
175
176 static PyObject *
177 _io_FileIO_readable(PyObject *self, PyObject *Py_UNUSED(ignored))
178 {
179 return _io_FileIO_readable_impl((fileio *)self);
180 }
181
182 PyDoc_STRVAR(_io_FileIO_writable__doc__,
183 "writable($self, /)\n"
184 "--\n"
185 "\n"
186 "True if file was opened in a write mode.");
187
188 #define _IO_FILEIO_WRITABLE_METHODDEF \
189 {"writable", (PyCFunction)_io_FileIO_writable, METH_NOARGS, _io_FileIO_writable__doc__},
190
191 static PyObject *
192 _io_FileIO_writable_impl(fileio *self);
193
194 static PyObject *
195 _io_FileIO_writable(PyObject *self, PyObject *Py_UNUSED(ignored))
196 {
197 return _io_FileIO_writable_impl((fileio *)self);
198 }
199
200 PyDoc_STRVAR(_io_FileIO_seekable__doc__,
201 "seekable($self, /)\n"
202 "--\n"
203 "\n"
204 "True if file supports random-access.");
205
206 #define _IO_FILEIO_SEEKABLE_METHODDEF \
207 {"seekable", (PyCFunction)_io_FileIO_seekable, METH_NOARGS, _io_FileIO_seekable__doc__},
208
209 static PyObject *
210 _io_FileIO_seekable_impl(fileio *self);
211
212 static PyObject *
213 _io_FileIO_seekable(PyObject *self, PyObject *Py_UNUSED(ignored))
214 {
215 return _io_FileIO_seekable_impl((fileio *)self);
216 }
217
218 PyDoc_STRVAR(_io_FileIO_readinto__doc__,
219 "readinto($self, buffer, /)\n"
220 "--\n"
221 "\n"
222 "Same as RawIOBase.readinto().");
223
224 #define _IO_FILEIO_READINTO_METHODDEF \
225 {"readinto", _PyCFunction_CAST(_io_FileIO_readinto), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_readinto__doc__},
226
227 static PyObject *
228 _io_FileIO_readinto_impl(fileio *self, PyTypeObject *cls, Py_buffer *buffer);
229
230 static PyObject *
231 _io_FileIO_readinto(PyObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
232 {
233 PyObject *return_value = NULL;
234 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
235 # define KWTUPLE (PyObject *)&_Py_SINGLETON(tuple_empty)
236 #else
237 # define KWTUPLE NULL
238 #endif
239
240 static const char * const _keywords[] = {"", NULL};
241 static _PyArg_Parser _parser = {
242 .keywords = _keywords,
243 .fname = "readinto",
244 .kwtuple = KWTUPLE,
245 };
246 #undef KWTUPLE
247 PyObject *argsbuf[1];
248 Py_buffer buffer = {NULL, NULL};
249
250 args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser,
251 /*minpos*/ 1, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
252 if (!args) {
253 goto exit;
254 }
255 if (PyObject_GetBuffer(args[0], &buffer, PyBUF_WRITABLE) < 0) {
256 _PyArg_BadArgument("readinto", "argument 1", "read-write bytes-like object", args[0]);
257 goto exit;
258 }
259 return_value = _io_FileIO_readinto_impl((fileio *)self, cls, &buffer);
260
261 exit:
262 /* Cleanup for buffer */
263 if (buffer.obj) {
264 PyBuffer_Release(&buffer);
265 }
266
267 return return_value;
268 }
269
270 PyDoc_STRVAR(_io_FileIO_readall__doc__,
271 "readall($self, /)\n"
272 "--\n"
273 "\n"
274 "Read all data from the file, returned as bytes.\n"
275 "\n"
276 "Reads until either there is an error or read() returns size 0\n"
277 "(indicates EOF). If the file is already at EOF, returns an empty\n"
278 "bytes object.\n"
279 "\n"
280 "In non-blocking mode, returns as much data as could be read before\n"
281 "EAGAIN. If no data is available (EAGAIN is returned before bytes\n"
282 "are read) returns None.");
283
284 #define _IO_FILEIO_READALL_METHODDEF \
285 {"readall", (PyCFunction)_io_FileIO_readall, METH_NOARGS, _io_FileIO_readall__doc__},
286
287 static PyObject *
288 _io_FileIO_readall_impl(fileio *self);
289
290 static PyObject *
291 _io_FileIO_readall(PyObject *self, PyObject *Py_UNUSED(ignored))
292 {
293 return _io_FileIO_readall_impl((fileio *)self);
294 }
295
296 PyDoc_STRVAR(_io_FileIO_read__doc__,
297 "read($self, size=-1, /)\n"
298 "--\n"
299 "\n"
300 "Read at most size bytes, returned as bytes.\n"
301 "\n"
302 "If size is less than 0, read all bytes in the file making multiple\n"
303 "read calls. See ``FileIO.readall``.\n"
304 "\n"
305 "Attempts to make only one system call, retrying only per PEP 475\n"
306 "(EINTR). This means less data may be returned than requested.\n"
307 "\n"
308 "In non-blocking mode, returns None if no data is available. Return\n"
309 "an empty bytes object at EOF.");
310
311 #define _IO_FILEIO_READ_METHODDEF \
312 {"read", _PyCFunction_CAST(_io_FileIO_read), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_read__doc__},
313
314 static PyObject *
315 _io_FileIO_read_impl(fileio *self, PyTypeObject *cls, Py_ssize_t size);
316
317 static PyObject *
318 _io_FileIO_read(PyObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
319 {
320 PyObject *return_value = NULL;
321 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
322 # define KWTUPLE (PyObject *)&_Py_SINGLETON(tuple_empty)
323 #else
324 # define KWTUPLE NULL
325 #endif
326
327 static const char * const _keywords[] = {"", NULL};
328 static _PyArg_Parser _parser = {
329 .keywords = _keywords,
330 .fname = "read",
331 .kwtuple = KWTUPLE,
332 };
333 #undef KWTUPLE
334 PyObject *argsbuf[1];
335 Py_ssize_t size = -1;
336
337 args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser,
338 /*minpos*/ 0, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
339 if (!args) {
340 goto exit;
341 }
342 if (nargs < 1) {
343 goto skip_optional_posonly;
344 }
345 if (!_Py_convert_optional_to_ssize_t(args[0], &size)) {
346 goto exit;
347 }
348 skip_optional_posonly:
349 return_value = _io_FileIO_read_impl((fileio *)self, cls, size);
350
351 exit:
352 return return_value;
353 }
354
355 PyDoc_STRVAR(_io_FileIO_write__doc__,
356 "write($self, b, /)\n"
357 "--\n"
358 "\n"
359 "Write buffer b to file, return number of bytes written.\n"
360 "\n"
361 "Only makes one system call, so not all of the data may be written.\n"
362 "The number of bytes actually written is returned. In non-blocking\n"
363 "mode, returns None if the write would block.");
364
365 #define _IO_FILEIO_WRITE_METHODDEF \
366 {"write", _PyCFunction_CAST(_io_FileIO_write), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_write__doc__},
367
368 static PyObject *
369 _io_FileIO_write_impl(fileio *self, PyTypeObject *cls, Py_buffer *b);
370
371 static PyObject *
372 _io_FileIO_write(PyObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
373 {
374 PyObject *return_value = NULL;
375 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
376 # define KWTUPLE (PyObject *)&_Py_SINGLETON(tuple_empty)
377 #else
378 # define KWTUPLE NULL
379 #endif
380
381 static const char * const _keywords[] = {"", NULL};
382 static _PyArg_Parser _parser = {
383 .keywords = _keywords,
384 .fname = "write",
385 .kwtuple = KWTUPLE,
386 };
387 #undef KWTUPLE
388 PyObject *argsbuf[1];
389 Py_buffer b = {NULL, NULL};
390
391 args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser,
392 /*minpos*/ 1, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
393 if (!args) {
394 goto exit;
395 }
396 if (PyObject_GetBuffer(args[0], &b, PyBUF_SIMPLE) != 0) {
397 goto exit;
398 }
399 return_value = _io_FileIO_write_impl((fileio *)self, cls, &b);
400
401 exit:
402 /* Cleanup for b */
403 if (b.obj) {
404 PyBuffer_Release(&b);
405 }
406
407 return return_value;
408 }
409
410 PyDoc_STRVAR(_io_FileIO_seek__doc__,
411 "seek($self, pos, whence=0, /)\n"
412 "--\n"
413 "\n"
414 "Move to new file position and return the file position.\n"
415 "\n"
416 "Argument offset is a byte count. Optional argument whence defaults\n"
417 "to SEEK_SET or 0 (offset from start of file, offset should be >= 0);\n"
418 "other values are SEEK_CUR or 1 (move relative to current position,\n"
419 "positive or negative), and SEEK_END or 2 (move relative to end of\n"
420 "file, usually negative, although many platforms allow seeking beyond\n"
421 "the end of a file).\n"
422 "\n"
423 "Note that not all file objects are seekable.");
424
425 #define _IO_FILEIO_SEEK_METHODDEF \
426 {"seek", _PyCFunction_CAST(_io_FileIO_seek), METH_FASTCALL, _io_FileIO_seek__doc__},
427
428 static PyObject *
429 _io_FileIO_seek_impl(fileio *self, PyObject *pos, int whence);
430
431 static PyObject *
432 _io_FileIO_seek(PyObject *self, PyObject *const *args, Py_ssize_t nargs)
433 {
434 PyObject *return_value = NULL;
435 PyObject *pos;
436 int whence = 0;
437
438 if (!_PyArg_CheckPositional("seek", nargs, 1, 2)) {
439 goto exit;
440 }
441 pos = args[0];
442 if (nargs < 2) {
443 goto skip_optional;
444 }
445 whence = PyLong_AsInt(args[1]);
446 if (whence == -1 && PyErr_Occurred()) {
447 goto exit;
448 }
449 skip_optional:
450 return_value = _io_FileIO_seek_impl((fileio *)self, pos, whence);
451
452 exit:
453 return return_value;
454 }
455
456 PyDoc_STRVAR(_io_FileIO_tell__doc__,
457 "tell($self, /)\n"
458 "--\n"
459 "\n"
460 "Current file position.\n"
461 "\n"
462 "Can raise OSError for non seekable files.");
463
464 #define _IO_FILEIO_TELL_METHODDEF \
465 {"tell", (PyCFunction)_io_FileIO_tell, METH_NOARGS, _io_FileIO_tell__doc__},
466
467 static PyObject *
468 _io_FileIO_tell_impl(fileio *self);
469
470 static PyObject *
471 _io_FileIO_tell(PyObject *self, PyObject *Py_UNUSED(ignored))
472 {
473 return _io_FileIO_tell_impl((fileio *)self);
474 }
475
476 #if defined(HAVE_FTRUNCATE)
477
478 PyDoc_STRVAR(_io_FileIO_truncate__doc__,
479 "truncate($self, size=None, /)\n"
480 "--\n"
481 "\n"
482 "Truncate the file to at most size bytes and return the truncated size.\n"
483 "\n"
484 "Size defaults to the current file position, as returned by tell().\n"
485 "The current file position is changed to the value of size.");
486
487 #define _IO_FILEIO_TRUNCATE_METHODDEF \
488 {"truncate", _PyCFunction_CAST(_io_FileIO_truncate), METH_METHOD|METH_FASTCALL|METH_KEYWORDS, _io_FileIO_truncate__doc__},
489
490 static PyObject *
491 _io_FileIO_truncate_impl(fileio *self, PyTypeObject *cls, PyObject *posobj);
492
493 static PyObject *
494 _io_FileIO_truncate(PyObject *self, PyTypeObject *cls, PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames)
495 {
496 PyObject *return_value = NULL;
497 #if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
498 # define KWTUPLE (PyObject *)&_Py_SINGLETON(tuple_empty)
499 #else
500 # define KWTUPLE NULL
501 #endif
502
503 static const char * const _keywords[] = {"", NULL};
504 static _PyArg_Parser _parser = {
505 .keywords = _keywords,
506 .fname = "truncate",
507 .kwtuple = KWTUPLE,
508 };
509 #undef KWTUPLE
510 PyObject *argsbuf[1];
511 PyObject *posobj = Py_None;
512
513 args = _PyArg_UnpackKeywords(args, nargs, NULL, kwnames, &_parser,
514 /*minpos*/ 0, /*maxpos*/ 1, /*minkw*/ 0, /*varpos*/ 0, argsbuf);
515 if (!args) {
516 goto exit;
517 }
518 if (nargs < 1) {
519 goto skip_optional_posonly;
520 }
521 posobj = args[0];
522 skip_optional_posonly:
523 return_value = _io_FileIO_truncate_impl((fileio *)self, cls, posobj);
524
525 exit:
526 return return_value;
527 }
528
529 #endif /* defined(HAVE_FTRUNCATE) */
530
531 PyDoc_STRVAR(_io_FileIO_isatty__doc__,
532 "isatty($self, /)\n"
533 "--\n"
534 "\n"
535 "True if the file is connected to a TTY device.");
536
537 #define _IO_FILEIO_ISATTY_METHODDEF \
538 {"isatty", (PyCFunction)_io_FileIO_isatty, METH_NOARGS, _io_FileIO_isatty__doc__},
539
540 static PyObject *
541 _io_FileIO_isatty_impl(fileio *self);
542
543 static PyObject *
544 _io_FileIO_isatty(PyObject *self, PyObject *Py_UNUSED(ignored))
545 {
546 return _io_FileIO_isatty_impl((fileio *)self);
547 }
548
549 #ifndef _IO_FILEIO_TRUNCATE_METHODDEF
550 #define _IO_FILEIO_TRUNCATE_METHODDEF
551 #endif /* !defined(_IO_FILEIO_TRUNCATE_METHODDEF) */
552 /*[clinic end generated code: output=3be887af000af7ce input=a9049054013a1b77]*/