2 An implementation of the I/O abstract base classes hierarchy
3 as defined by PEP 3116 - "New I/O"
5 Classes defined here: IOBase, RawIOBase.
7 Written by Amaury Forgeot d'Arc and Antoine Pitrou
11 #define PY_SSIZE_T_CLEAN
13 #include "structmember.h"
14 #include "_iomodule.h"
17 * IOBase class, an abstract class
24 PyObject
*weakreflist
;
27 PyDoc_STRVAR(iobase_doc
,
28 "The abstract base class for all I/O classes, acting on streams of\n"
29 "bytes. There is no public constructor.\n"
31 "This class provides dummy implementations for many methods that\n"
32 "derived classes can override selectively; the default implementations\n"
33 "represent a file that cannot be read, written or seeked.\n"
35 "Even though IOBase does not declare read, readinto, or write because\n"
36 "their signatures will vary, implementations and clients should\n"
37 "consider those methods part of the interface. Also, implementations\n"
38 "may raise a IOError when operations they do not support are called.\n"
40 "The basic type used for binary data read from or written to a file is\n"
41 "bytes. bytearrays are accepted too, and in some cases (such as\n"
42 "readinto) needed. Text I/O classes work with str data.\n"
44 "Note that calling any method (even inquiries) on a closed stream is\n"
45 "undefined. Implementations may raise IOError in this case.\n"
47 "IOBase (and its subclasses) support the iterator protocol, meaning\n"
48 "that an IOBase object can be iterated over yielding the lines in a\n"
51 "IOBase also supports the :keyword:`with` statement. In this example,\n"
52 "fp is closed after the suite of the with statment is complete:\n"
54 "with open('spam.txt', 'r') as fp:\n"
55 " fp.write('Spam and eggs!')\n");
57 /* Use this macro whenever you want to check the internal `closed` status
58 of the IOBase object rather than the virtual `closed` attribute as returned
59 by whatever subclass. */
61 #define IS_CLOSED(self) \
62 PyObject_HasAttrString(self, "__IOBase_closed")
64 /* Internal methods */
66 iobase_unsupported(const char *message
)
68 PyErr_SetString(_PyIO_unsupported_operation
, message
);
74 PyDoc_STRVAR(iobase_seek_doc
,
75 "Change stream position.\n"
77 "Change the stream position to byte offset offset. offset is\n"
78 "interpreted relative to the position indicated by whence. Values\n"
81 "* 0 -- start of stream (the default); offset should be zero or positive\n"
82 "* 1 -- current stream position; offset may be negative\n"
83 "* 2 -- end of stream; offset is usually negative\n"
85 "Return the new absolute position.");
88 iobase_seek(PyObject
*self
, PyObject
*args
)
90 return iobase_unsupported("seek");
93 PyDoc_STRVAR(iobase_tell_doc
,
94 "Return current stream position.");
97 iobase_tell(PyObject
*self
, PyObject
*args
)
99 return PyObject_CallMethod(self
, "seek", "ii", 0, 1);
102 PyDoc_STRVAR(iobase_truncate_doc
,
103 "Truncate file to size bytes.\n"
105 "Size defaults to the current IO position as reported by tell(). Return\n"
109 iobase_truncate(PyObject
*self
, PyObject
*args
)
111 return iobase_unsupported("truncate");
114 /* Flush and close methods */
116 PyDoc_STRVAR(iobase_flush_doc
,
117 "Flush write buffers, if applicable.\n"
119 "This is not implemented for read-only and non-blocking streams.\n");
122 iobase_flush(PyObject
*self
, PyObject
*args
)
124 /* XXX Should this return the number of bytes written??? */
125 if (IS_CLOSED(self
)) {
126 PyErr_SetString(PyExc_ValueError
, "I/O operation on closed file.");
132 PyDoc_STRVAR(iobase_close_doc
,
133 "Flush and close the IO object.\n"
135 "This method has no effect if the file is already closed.\n");
138 iobase_closed(PyObject
*self
)
142 /* This gets the derived attribute, which is *not* __IOBase_closed
144 res
= PyObject_GetAttr(self
, _PyIO_str_closed
);
147 closed
= PyObject_IsTrue(res
);
153 iobase_closed_get(PyObject
*self
, void *context
)
155 return PyBool_FromLong(IS_CLOSED(self
));
159 _PyIOBase_check_closed(PyObject
*self
, PyObject
*args
)
161 if (iobase_closed(self
)) {
162 PyErr_SetString(PyExc_ValueError
, "I/O operation on closed file.");
171 /* XXX: IOBase thinks it has to maintain its own internal state in
172 `__IOBase_closed` and call flush() by itself, but it is redundant with
173 whatever behaviour a non-trivial derived class will implement. */
176 iobase_close(PyObject
*self
, PyObject
*args
)
183 res
= PyObject_CallMethodObjArgs(self
, _PyIO_str_flush
, NULL
);
184 PyObject_SetAttrString(self
, "__IOBase_closed", Py_True
);
186 /* If flush() fails, just give up */
187 if (PyErr_ExceptionMatches(PyExc_IOError
))
196 /* Finalization and garbage collection support */
199 _PyIOBase_finalize(PyObject
*self
)
202 PyObject
*tp
, *v
, *tb
;
206 /* If _PyIOBase_finalize() is called from a destructor, we need to
207 resurrect the object as calling close() can invoke arbitrary code. */
208 is_zombie
= (Py_REFCNT(self
) == 0);
212 PyErr_Fetch(&tp
, &v
, &tb
);
213 /* If `closed` doesn't exist or can't be evaluated as bool, then the
214 object is probably in an unusable state, so ignore. */
215 res
= PyObject_GetAttr(self
, _PyIO_str_closed
);
219 closed
= PyObject_IsTrue(res
);
225 res
= PyObject_CallMethodObjArgs((PyObject
*) self
, _PyIO_str_close
,
227 /* Silencing I/O errors is bad, but printing spurious tracebacks is
228 equally as bad, and potentially more frequent (because of
235 PyErr_Restore(tp
, v
, tb
);
237 if (--Py_REFCNT(self
) != 0) {
238 /* The object lives again. The following code is taken from
239 slot_tp_del in typeobject.c. */
240 Py_ssize_t refcnt
= Py_REFCNT(self
);
241 _Py_NewReference(self
);
242 Py_REFCNT(self
) = refcnt
;
243 /* If Py_REF_DEBUG, _Py_NewReference bumped _Py_RefTotal, so
244 * we need to undo that. */
246 /* If Py_TRACE_REFS, _Py_NewReference re-added self to the object
247 * chain, so no more to do there.
248 * If COUNT_ALLOCS, the original decref bumped tp_frees, and
249 * _Py_NewReference bumped tp_allocs: both of those need to be
253 --Py_TYPE(self
)->tp_frees
;
254 --Py_TYPE(self
)->tp_allocs
;
263 iobase_traverse(iobase
*self
, visitproc visit
, void *arg
)
265 Py_VISIT(self
->dict
);
270 iobase_clear(iobase
*self
)
272 if (_PyIOBase_finalize((PyObject
*) self
) < 0)
274 Py_CLEAR(self
->dict
);
281 iobase_dealloc(iobase
*self
)
283 /* NOTE: since IOBaseObject has its own dict, Python-defined attributes
284 are still available here for close() to use.
285 However, if the derived class declares a __slots__, those slots are
288 if (_PyIOBase_finalize((PyObject
*) self
) < 0) {
289 /* When called from a heap type's dealloc, the type will be
290 decref'ed on return (see e.g. subtype_dealloc in typeobject.c). */
291 if (PyType_HasFeature(Py_TYPE(self
), Py_TPFLAGS_HEAPTYPE
))
292 Py_INCREF(Py_TYPE(self
));
295 _PyObject_GC_UNTRACK(self
);
296 if (self
->weakreflist
!= NULL
)
297 PyObject_ClearWeakRefs((PyObject
*) self
);
298 Py_CLEAR(self
->dict
);
299 Py_TYPE(self
)->tp_free((PyObject
*) self
);
302 /* Inquiry methods */
304 PyDoc_STRVAR(iobase_seekable_doc
,
305 "Return whether object supports random access.\n"
307 "If False, seek(), tell() and truncate() will raise IOError.\n"
308 "This method may need to do a test seek().");
311 iobase_seekable(PyObject
*self
, PyObject
*args
)
317 _PyIOBase_check_seekable(PyObject
*self
, PyObject
*args
)
319 PyObject
*res
= PyObject_CallMethodObjArgs(self
, _PyIO_str_seekable
, NULL
);
322 if (res
!= Py_True
) {
324 PyErr_SetString(PyExc_IOError
, "File or stream is not seekable.");
327 if (args
== Py_True
) {
333 PyDoc_STRVAR(iobase_readable_doc
,
334 "Return whether object was opened for reading.\n"
336 "If False, read() will raise IOError.");
339 iobase_readable(PyObject
*self
, PyObject
*args
)
344 /* May be called with any object */
346 _PyIOBase_check_readable(PyObject
*self
, PyObject
*args
)
348 PyObject
*res
= PyObject_CallMethodObjArgs(self
, _PyIO_str_readable
, NULL
);
351 if (res
!= Py_True
) {
353 PyErr_SetString(PyExc_IOError
, "File or stream is not readable.");
356 if (args
== Py_True
) {
362 PyDoc_STRVAR(iobase_writable_doc
,
363 "Return whether object was opened for writing.\n"
365 "If False, read() will raise IOError.");
368 iobase_writable(PyObject
*self
, PyObject
*args
)
373 /* May be called with any object */
375 _PyIOBase_check_writable(PyObject
*self
, PyObject
*args
)
377 PyObject
*res
= PyObject_CallMethodObjArgs(self
, _PyIO_str_writable
, NULL
);
380 if (res
!= Py_True
) {
382 PyErr_SetString(PyExc_IOError
, "File or stream is not writable.");
385 if (args
== Py_True
) {
391 /* Context manager */
394 iobase_enter(PyObject
*self
, PyObject
*args
)
396 if (_PyIOBase_check_closed(self
, Py_True
) == NULL
)
404 iobase_exit(PyObject
*self
, PyObject
*args
)
406 return PyObject_CallMethodObjArgs(self
, _PyIO_str_close
, NULL
);
409 /* Lower-level APIs */
411 /* XXX Should these be present even if unimplemented? */
413 PyDoc_STRVAR(iobase_fileno_doc
,
414 "Returns underlying file descriptor if one exists.\n"
416 "An IOError is raised if the IO object does not use a file descriptor.\n");
419 iobase_fileno(PyObject
*self
, PyObject
*args
)
421 return iobase_unsupported("fileno");
424 PyDoc_STRVAR(iobase_isatty_doc
,
425 "Return whether this is an 'interactive' stream.\n"
427 "Return False if it can't be determined.\n");
430 iobase_isatty(PyObject
*self
, PyObject
*args
)
432 if (_PyIOBase_check_closed(self
, Py_True
) == NULL
)
437 /* Readline(s) and writelines */
439 PyDoc_STRVAR(iobase_readline_doc
,
440 "Read and return a line from the stream.\n"
442 "If limit is specified, at most limit bytes will be read.\n"
444 "The line terminator is always b'\n' for binary files; for text\n"
445 "files, the newlines argument to open can be used to select the line\n"
446 "terminator(s) recognized.\n");
449 iobase_readline(PyObject
*self
, PyObject
*args
)
451 /* For backwards compatibility, a (slowish) readline(). */
453 Py_ssize_t limit
= -1;
455 PyObject
*buffer
, *result
;
456 Py_ssize_t old_size
= -1;
458 if (!PyArg_ParseTuple(args
, "|O&:readline", &_PyIO_ConvertSsize_t
, &limit
)) {
462 if (PyObject_HasAttrString(self
, "peek"))
465 buffer
= PyByteArray_FromStringAndSize(NULL
, 0);
469 while (limit
< 0 || Py_SIZE(buffer
) < limit
) {
470 Py_ssize_t nreadahead
= 1;
474 PyObject
*readahead
= PyObject_CallMethod(self
, "peek", "i", 1);
475 if (readahead
== NULL
)
477 if (!PyBytes_Check(readahead
)) {
478 PyErr_Format(PyExc_IOError
,
479 "peek() should have returned a bytes object, "
480 "not '%.200s'", Py_TYPE(readahead
)->tp_name
);
481 Py_DECREF(readahead
);
484 if (PyBytes_GET_SIZE(readahead
) > 0) {
486 const char *buf
= PyBytes_AS_STRING(readahead
);
489 if (n
>= PyBytes_GET_SIZE(readahead
) || n
>= limit
)
491 if (buf
[n
++] == '\n')
497 if (n
>= PyBytes_GET_SIZE(readahead
))
499 if (buf
[n
++] == '\n')
505 Py_DECREF(readahead
);
508 b
= PyObject_CallMethod(self
, "read", "n", nreadahead
);
511 if (!PyBytes_Check(b
)) {
512 PyErr_Format(PyExc_IOError
,
513 "read() should have returned a bytes object, "
514 "not '%.200s'", Py_TYPE(b
)->tp_name
);
518 if (PyBytes_GET_SIZE(b
) == 0) {
523 old_size
= PyByteArray_GET_SIZE(buffer
);
524 PyByteArray_Resize(buffer
, old_size
+ PyBytes_GET_SIZE(b
));
525 memcpy(PyByteArray_AS_STRING(buffer
) + old_size
,
526 PyBytes_AS_STRING(b
), PyBytes_GET_SIZE(b
));
530 if (PyByteArray_AS_STRING(buffer
)[PyByteArray_GET_SIZE(buffer
) - 1] == '\n')
534 result
= PyBytes_FromStringAndSize(PyByteArray_AS_STRING(buffer
),
535 PyByteArray_GET_SIZE(buffer
));
544 iobase_iter(PyObject
*self
)
546 if (_PyIOBase_check_closed(self
, Py_True
) == NULL
)
554 iobase_iternext(PyObject
*self
)
556 PyObject
*line
= PyObject_CallMethodObjArgs(self
, _PyIO_str_readline
, NULL
);
561 if (PyObject_Size(line
) == 0) {
569 PyDoc_STRVAR(iobase_readlines_doc
,
570 "Return a list of lines from the stream.\n"
572 "hint can be specified to control the number of lines read: no more\n"
573 "lines will be read if the total size (in bytes/characters) of all\n"
574 "lines so far exceeds hint.");
577 iobase_readlines(PyObject
*self
, PyObject
*args
)
579 Py_ssize_t hint
= -1, length
= 0;
582 if (!PyArg_ParseTuple(args
, "|O&:readlines", &_PyIO_ConvertSsize_t
, &hint
)) {
586 result
= PyList_New(0);
591 /* XXX special-casing this made sense in the Python version in order
592 to remove the bytecode interpretation overhead, but it could
593 probably be removed here. */
594 PyObject
*ret
= PyObject_CallMethod(result
, "extend", "O", self
);
604 PyObject
*line
= PyIter_Next(self
);
606 if (PyErr_Occurred()) {
611 break; /* StopIteration raised */
614 if (PyList_Append(result
, line
) < 0) {
619 length
+= PyObject_Size(line
);
629 iobase_writelines(PyObject
*self
, PyObject
*args
)
631 PyObject
*lines
, *iter
, *res
;
633 if (!PyArg_ParseTuple(args
, "O:writelines", &lines
)) {
637 if (_PyIOBase_check_closed(self
, Py_True
) == NULL
)
640 iter
= PyObject_GetIter(lines
);
645 PyObject
*line
= PyIter_Next(iter
);
647 if (PyErr_Occurred()) {
652 break; /* Stop Iteration */
655 res
= PyObject_CallMethodObjArgs(self
, _PyIO_str_write
, line
, NULL
);
667 static PyMethodDef iobase_methods
[] = {
668 {"seek", iobase_seek
, METH_VARARGS
, iobase_seek_doc
},
669 {"tell", iobase_tell
, METH_NOARGS
, iobase_tell_doc
},
670 {"truncate", iobase_truncate
, METH_VARARGS
, iobase_truncate_doc
},
671 {"flush", iobase_flush
, METH_NOARGS
, iobase_flush_doc
},
672 {"close", iobase_close
, METH_NOARGS
, iobase_close_doc
},
674 {"seekable", iobase_seekable
, METH_NOARGS
, iobase_seekable_doc
},
675 {"readable", iobase_readable
, METH_NOARGS
, iobase_readable_doc
},
676 {"writable", iobase_writable
, METH_NOARGS
, iobase_writable_doc
},
678 {"_checkClosed", _PyIOBase_check_closed
, METH_NOARGS
},
679 {"_checkSeekable", _PyIOBase_check_seekable
, METH_NOARGS
},
680 {"_checkReadable", _PyIOBase_check_readable
, METH_NOARGS
},
681 {"_checkWritable", _PyIOBase_check_writable
, METH_NOARGS
},
683 {"fileno", iobase_fileno
, METH_NOARGS
, iobase_fileno_doc
},
684 {"isatty", iobase_isatty
, METH_NOARGS
, iobase_isatty_doc
},
686 {"__enter__", iobase_enter
, METH_NOARGS
},
687 {"__exit__", iobase_exit
, METH_VARARGS
},
689 {"readline", iobase_readline
, METH_VARARGS
, iobase_readline_doc
},
690 {"readlines", iobase_readlines
, METH_VARARGS
, iobase_readlines_doc
},
691 {"writelines", iobase_writelines
, METH_VARARGS
},
696 static PyGetSetDef iobase_getset
[] = {
697 {"closed", (getter
)iobase_closed_get
, NULL
, NULL
},
702 PyTypeObject PyIOBase_Type
= {
703 PyVarObject_HEAD_INIT(NULL
, 0)
704 "_io._IOBase", /*tp_name*/
705 sizeof(iobase
), /*tp_basicsize*/
707 (destructor
)iobase_dealloc
, /*tp_dealloc*/
714 0, /*tp_as_sequence*/
722 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
723 | Py_TPFLAGS_HAVE_GC
, /*tp_flags*/
724 iobase_doc
, /* tp_doc */
725 (traverseproc
)iobase_traverse
, /* tp_traverse */
726 (inquiry
)iobase_clear
, /* tp_clear */
727 0, /* tp_richcompare */
728 offsetof(iobase
, weakreflist
), /* tp_weaklistoffset */
729 iobase_iter
, /* tp_iter */
730 iobase_iternext
, /* tp_iternext */
731 iobase_methods
, /* tp_methods */
733 iobase_getset
, /* tp_getset */
736 0, /* tp_descr_get */
737 0, /* tp_descr_set */
738 offsetof(iobase
, dict
), /* tp_dictoffset */
741 PyType_GenericNew
, /* tp_new */
746 * RawIOBase class, Inherits from IOBase.
748 PyDoc_STRVAR(rawiobase_doc
,
749 "Base class for raw binary I/O.");
752 * The read() method is implemented by calling readinto(); derived classes
753 * that want to support read() only need to implement readinto() as a
754 * primitive operation. In general, readinto() can be more efficient than
757 * (It would be tempting to also provide an implementation of readinto() in
758 * terms of read(), in case the latter is a more suitable primitive operation,
759 * but that would lead to nasty recursion in case a subclass doesn't implement
764 rawiobase_read(PyObject
*self
, PyObject
*args
)
769 if (!PyArg_ParseTuple(args
, "|n:read", &n
)) {
774 return PyObject_CallMethod(self
, "readall", NULL
);
776 /* TODO: allocate a bytes object directly instead and manually construct
777 a writable memoryview pointing to it. */
778 b
= PyByteArray_FromStringAndSize(NULL
, n
);
782 res
= PyObject_CallMethodObjArgs(self
, _PyIO_str_readinto
, b
, NULL
);
788 n
= PyNumber_AsSsize_t(res
, PyExc_ValueError
);
790 if (n
== -1 && PyErr_Occurred()) {
795 res
= PyBytes_FromStringAndSize(PyByteArray_AsString(b
), n
);
801 PyDoc_STRVAR(rawiobase_readall_doc
,
802 "Read until EOF, using multiple read() call.");
805 rawiobase_readall(PyObject
*self
, PyObject
*args
)
808 PyObject
*chunks
= PyList_New(0);
815 PyObject
*data
= PyObject_CallMethod(self
, "read",
816 "i", DEFAULT_BUFFER_SIZE
);
821 if (!PyBytes_Check(data
)) {
824 PyErr_SetString(PyExc_TypeError
, "read() should return bytes");
827 if (PyBytes_GET_SIZE(data
) == 0) {
832 r
= PyList_Append(chunks
, data
);
839 result
= _PyBytes_Join(_PyIO_empty_bytes
, chunks
);
844 static PyMethodDef rawiobase_methods
[] = {
845 {"read", rawiobase_read
, METH_VARARGS
},
846 {"readall", rawiobase_readall
, METH_NOARGS
, rawiobase_readall_doc
},
850 PyTypeObject PyRawIOBase_Type
= {
851 PyVarObject_HEAD_INIT(NULL
, 0)
852 "_io._RawIOBase", /*tp_name*/
862 0, /*tp_as_sequence*/
870 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_BASETYPE
, /*tp_flags*/
871 rawiobase_doc
, /* tp_doc */
874 0, /* tp_richcompare */
875 0, /* tp_weaklistoffset */
878 rawiobase_methods
, /* tp_methods */
881 &PyIOBase_Type
, /* tp_base */
883 0, /* tp_descr_get */
884 0, /* tp_descr_set */
885 0, /* tp_dictoffset */