Coverage Report

Created: 2026-04-12 06:14

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