implement a detach() method for BufferedIOBase and TextIOBase #5883
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index c839691..4f6ee5a 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -361,6 +361,17 @@
:class:`BufferedIOBase` provides or overrides these methods in addition to
those from :class:`IOBase`:
+ .. method:: detach()
+
+ Separate the underlying raw stream from the buffer and return it.
+
+ After the raw stream has been detached, the buffer is in an unusable
+ state.
+
+ Some buffers, like :class:`BytesIO`, do not have the concept of a single
+ raw stream to return from this method. They raise
+ :exc:`UnsupportedOperation`.
+
.. method:: read([n])
Read and return up to *n* bytes. If the argument is omitted, ``None``, or
@@ -547,7 +558,9 @@
*max_buffer_size* is unused and deprecated.
- :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods.
+ :class:`BufferedRWPair` implements all of :class:`BufferedIOBase`\'s methods
+ except for :meth:`~BufferedIOBase.detach`, which raises
+ :exc:`UnsupportedOperation`.
.. class:: BufferedRandom(raw[, buffer_size[, max_buffer_size]])
@@ -588,6 +601,17 @@
A string, a tuple of strings, or ``None``, indicating the newlines
translated so far.
+ .. method:: detach()
+
+ Separate the underlying buffer from the :class:`TextIOBase` and return it.
+
+ After the underlying buffer has been detached, the :class:`TextIOBase` is
+ in an unusable state.
+
+ Some :class:`TextIOBase` implementations, like :class:`StringIO`, may not
+ have the concept of an underlying buffer and calling this method will
+ raise :exc:`UnsupportedOperation`.
+
.. method:: read(n)
Read and return at most *n* characters from the stream as a single
diff --git a/Lib/_pyio.py b/Lib/_pyio.py
index e580366..e3e7c3d 100644
--- a/Lib/_pyio.py
+++ b/Lib/_pyio.py
@@ -642,6 +642,15 @@
"""
self._unsupported("write")
+ def detach(self) -> None:
+ """
+ Separate the underlying raw stream from the buffer and return it.
+
+ After the raw stream has been detached, the buffer is in an unusable
+ state.
+ """
+ self._unsupported("detach")
+
io.BufferedIOBase.register(BufferedIOBase)
@@ -689,13 +698,21 @@
self.raw.flush()
def close(self):
- if not self.closed:
+ if not self.closed and self.raw is not None:
try:
self.flush()
except IOError:
pass # If flush() fails, just give up
self.raw.close()
+ def detach(self):
+ if self.raw is None:
+ raise ValueError("raw stream already detached")
+ self.flush()
+ raw = self.raw
+ self.raw = None
+ return raw
+
### Inquiries ###
def seekable(self):
@@ -1236,6 +1253,15 @@
"""
self._unsupported("readline")
+ def detach(self) -> None:
+ """
+ Separate the underlying buffer from the TextIOBase and return it.
+
+ After the underlying buffer has been detached, the TextIO is in an
+ unusable state.
+ """
+ self._unsupported("detach")
+
@property
def encoding(self):
"""Subclasses should override."""
@@ -1448,11 +1474,12 @@
self._telling = self._seekable
def close(self):
- try:
- self.flush()
- except IOError:
- pass # If flush() fails, just give up
- self.buffer.close()
+ if self.buffer is not None:
+ try:
+ self.flush()
+ except IOError:
+ pass # If flush() fails, just give up
+ self.buffer.close()
@property
def closed(self):
@@ -1647,6 +1674,14 @@
self.seek(pos)
return self.buffer.truncate()
+ def detach(self):
+ if self.buffer is None:
+ raise ValueError("buffer is already detached")
+ self.flush()
+ buffer = self.buffer
+ self.buffer = None
+ return buffer
+
def seek(self, cookie, whence=0):
if self.closed:
raise ValueError("tell on closed file")
@@ -1865,3 +1900,7 @@
@property
def encoding(self):
return None
+
+ def detach(self):
+ # This doesn't make sense on StringIO.
+ self._unsupported("detach")
diff --git a/Lib/test/test_io.py b/Lib/test/test_io.py
index a8c878e..1a525dc 100644
--- a/Lib/test/test_io.py
+++ b/Lib/test/test_io.py
@@ -526,6 +526,12 @@
class CommonBufferedTests:
# Tests common to BufferedReader, BufferedWriter and BufferedRandom
+ def test_detach(self):
+ raw = self.MockRawIO()
+ buf = self.tp(raw)
+ self.assertIs(buf.detach(), raw)
+ self.assertRaises(ValueError, buf.detach)
+
def test_fileno(self):
rawio = self.MockRawIO()
bufio = self.tp(rawio)
@@ -811,6 +817,14 @@
bufio.flush()
self.assertEquals(b"".join(rawio._write_stack), b"abcghi")
+ def test_detach_flush(self):
+ raw = self.MockRawIO()
+ buf = self.tp(raw)
+ buf.write(b"howdy!")
+ self.assertFalse(raw._write_stack)
+ buf.detach()
+ self.assertEqual(raw._write_stack, [b"howdy!"])
+
def test_write(self):
# Write to the buffered IO but don't overflow the buffer.
writer = self.MockRawIO()
@@ -1052,6 +1066,10 @@
pair = self.tp(self.MockRawIO(), self.MockRawIO())
self.assertFalse(pair.closed)
+ def test_detach(self):
+ pair = self.tp(self.MockRawIO(), self.MockRawIO())
+ self.assertRaises(self.UnsupportedOperation, pair.detach)
+
def test_constructor_max_buffer_size_deprecation(self):
with support.check_warnings() as w:
warnings.simplefilter("always", DeprecationWarning)
@@ -1480,6 +1498,19 @@
self.assertRaises(TypeError, t.__init__, b, newline=42)
self.assertRaises(ValueError, t.__init__, b, newline='xyzzy')
+ def test_detach(self):
+ r = self.BytesIO()
+ b = self.BufferedWriter(r)
+ t = self.TextIOWrapper(b)
+ self.assertIs(t.detach(), b)
+
+ t = self.TextIOWrapper(b, encoding="ascii")
+ t.write("howdy")
+ self.assertFalse(r.getvalue())
+ t.detach()
+ self.assertEqual(r.getvalue(), b"howdy")
+ self.assertRaises(ValueError, t.detach)
+
def test_repr(self):
raw = self.BytesIO("hello".encode("utf-8"))
b = self.BufferedReader(raw)
diff --git a/Lib/test/test_memoryio.py b/Lib/test/test_memoryio.py
index ad04613..d94d9dd 100644
--- a/Lib/test/test_memoryio.py
+++ b/Lib/test/test_memoryio.py
@@ -57,6 +57,10 @@
class MemoryTestMixin:
+ def test_detach(self):
+ buf = self.ioclass()
+ self.assertRaises(self.UnsupportedOperation, buf.detach)
+
def write_ops(self, f, t):
self.assertEqual(f.write(t("blah.")), 5)
self.assertEqual(f.seek(0), 0)
@@ -336,6 +340,9 @@
class PyBytesIOTest(MemoryTestMixin, MemorySeekTestMixin, unittest.TestCase):
+
+ UnsupportedOperation = pyio.UnsupportedOperation
+
@staticmethod
def buftype(s):
return s.encode("ascii")
@@ -413,6 +420,7 @@
class PyStringIOTest(MemoryTestMixin, MemorySeekTestMixin, unittest.TestCase):
buftype = str
ioclass = pyio.StringIO
+ UnsupportedOperation = pyio.UnsupportedOperation
EOF = ""
# TextIO-specific behaviour.
@@ -518,9 +526,11 @@
class CBytesIOTest(PyBytesIOTest):
ioclass = io.BytesIO
+ UnsupportedOperation = io.UnsupportedOperation
class CStringIOTest(PyStringIOTest):
ioclass = io.StringIO
+ UnsupportedOperation = io.UnsupportedOperation
# XXX: For the Python version of io.StringIO, this is highly
# dependent on the encoding used for the underlying buffer.
diff --git a/Misc/NEWS b/Misc/NEWS
index d6ea209..4319a4a 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -12,6 +12,10 @@
Core and Builtins
-----------------
+- Issue #5883: In the io module, the BufferedIOBase and TextIOBase ABCs have
+ received a new method, detach(). detach() disconnects the underlying stream
+ from the buffer or text IO and returns it.
+
- Issue #5859: Remove switch from '%f' to '%g'-style formatting for
floats with absolute value over 1e50. Also remove length
restrictions for float formatting: '%.67f' % 12.34 and '%.120e' %
diff --git a/Modules/_io/bufferedio.c b/Modules/_io/bufferedio.c
index 3d175c7..2c65207 100644
--- a/Modules/_io/bufferedio.c
+++ b/Modules/_io/bufferedio.c
@@ -73,6 +73,18 @@
return NULL;
}
+PyDoc_STRVAR(BufferedIOBase_detach_doc,
+ "Disconnect this buffer from its underlying raw stream and return it.\n"
+ "\n"
+ "After the raw stream has been detached, the buffer is in an unusable\n"
+ "state.\n");
+
+static PyObject *
+BufferedIOBase_detach(PyObject *self)
+{
+ return BufferedIOBase_unsupported("detach");
+}
+
PyDoc_STRVAR(BufferedIOBase_read_doc,
"Read and return up to n bytes.\n"
"\n"
@@ -127,6 +139,7 @@
static PyMethodDef BufferedIOBase_methods[] = {
+ {"detach", (PyCFunction)BufferedIOBase_detach, METH_NOARGS, BufferedIOBase_detach_doc},
{"read", BufferedIOBase_read, METH_VARARGS, BufferedIOBase_read_doc},
{"read1", BufferedIOBase_read1, METH_VARARGS, BufferedIOBase_read1_doc},
{"readinto", BufferedIOBase_readinto, METH_VARARGS, NULL},
@@ -181,6 +194,7 @@
PyObject *raw;
int ok; /* Initialized? */
+ int detached;
int readable;
int writable;
@@ -260,15 +274,25 @@
#define CHECK_INITIALIZED(self) \
if (self->ok <= 0) { \
- PyErr_SetString(PyExc_ValueError, \
- "I/O operation on uninitialized object"); \
+ if (self->detached) { \
+ PyErr_SetString(PyExc_ValueError, \
+ "raw stream has been detached"); \
+ } else { \
+ PyErr_SetString(PyExc_ValueError, \
+ "I/O operation on uninitialized object"); \
+ } \
return NULL; \
}
#define CHECK_INITIALIZED_INT(self) \
if (self->ok <= 0) { \
- PyErr_SetString(PyExc_ValueError, \
- "I/O operation on uninitialized object"); \
+ if (self->detached) { \
+ PyErr_SetString(PyExc_ValueError, \
+ "raw stream has been detached"); \
+ } else { \
+ PyErr_SetString(PyExc_ValueError, \
+ "I/O operation on uninitialized object"); \
+ } \
return -1; \
}
@@ -430,6 +454,24 @@
return res;
}
+/* detach */
+
+static PyObject *
+BufferedIOMixin_detach(BufferedObject *self, PyObject *args)
+{
+ PyObject *raw, *res;
+ CHECK_INITIALIZED(self)
+ res = PyObject_CallMethodObjArgs((PyObject *)self, _PyIO_str_flush, NULL);
+ if (res == NULL)
+ return NULL;
+ Py_DECREF(res);
+ raw = self->raw;
+ self->raw = NULL;
+ self->detached = 1;
+ self->ok = 0;
+ return raw;
+}
+
/* Inquiries */
static PyObject *
@@ -1101,6 +1143,7 @@
PyObject *raw;
self->ok = 0;
+ self->detached = 0;
if (!PyArg_ParseTupleAndKeywords(args, kwds, "O|n:BufferedReader", kwlist,
&raw, &buffer_size)) {
@@ -1387,6 +1430,7 @@
static PyMethodDef BufferedReader_methods[] = {
/* BufferedIOMixin methods */
+ {"detach", (PyCFunction)BufferedIOMixin_detach, METH_NOARGS},
{"flush", (PyCFunction)BufferedIOMixin_flush, METH_NOARGS},
{"close", (PyCFunction)BufferedIOMixin_close, METH_NOARGS},
{"seekable", (PyCFunction)BufferedIOMixin_seekable, METH_NOARGS},
@@ -1499,6 +1543,7 @@
PyObject *raw;
self->ok = 0;
+ self->detached = 0;
if (!PyArg_ParseTupleAndKeywords(args, kwds, "O|nn:BufferedReader", kwlist,
&raw, &buffer_size, &max_buffer_size)) {
@@ -1745,6 +1790,7 @@
static PyMethodDef BufferedWriter_methods[] = {
/* BufferedIOMixin methods */
{"close", (PyCFunction)BufferedIOMixin_close, METH_NOARGS},
+ {"detach", (PyCFunction)BufferedIOMixin_detach, METH_NOARGS},
{"seekable", (PyCFunction)BufferedIOMixin_seekable, METH_NOARGS},
{"readable", (PyCFunction)BufferedIOMixin_readable, METH_NOARGS},
{"writable", (PyCFunction)BufferedIOMixin_writable, METH_NOARGS},
@@ -2089,6 +2135,7 @@
PyObject *raw;
self->ok = 0;
+ self->detached = 0;
if (!PyArg_ParseTupleAndKeywords(args, kwds, "O|nn:BufferedReader", kwlist,
&raw, &buffer_size, &max_buffer_size)) {
@@ -2128,6 +2175,7 @@
static PyMethodDef BufferedRandom_methods[] = {
/* BufferedIOMixin methods */
{"close", (PyCFunction)BufferedIOMixin_close, METH_NOARGS},
+ {"detach", (PyCFunction)BufferedIOMixin_detach, METH_NOARGS},
{"seekable", (PyCFunction)BufferedIOMixin_seekable, METH_NOARGS},
{"readable", (PyCFunction)BufferedIOMixin_readable, METH_NOARGS},
{"writable", (PyCFunction)BufferedIOMixin_writable, METH_NOARGS},
diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c
index 26fc68d..f201ba7 100644
--- a/Modules/_io/textio.c
+++ b/Modules/_io/textio.c
@@ -28,6 +28,19 @@
return NULL;
}
+PyDoc_STRVAR(TextIOBase_detach_doc,
+ "Separate the underlying buffer from the TextIOBase and return it.\n"
+ "\n"
+ "After the underlying buffer has been detached, the TextIO is in an\n"
+ "unusable state.\n"
+ );
+
+static PyObject *
+TextIOBase_detach(PyObject *self)
+{
+ return _unsupported("detach");
+}
+
PyDoc_STRVAR(TextIOBase_read_doc,
"Read at most n characters from stream.\n"
"\n"
@@ -93,6 +106,7 @@
static PyMethodDef TextIOBase_methods[] = {
+ {"detach", (PyCFunction)TextIOBase_detach, METH_NOARGS, TextIOBase_detach_doc},
{"read", TextIOBase_read, METH_VARARGS, TextIOBase_read_doc},
{"readline", TextIOBase_readline, METH_VARARGS, TextIOBase_readline_doc},
{"write", TextIOBase_write, METH_VARARGS, TextIOBase_write_doc},
@@ -616,6 +630,7 @@
{
PyObject_HEAD
int ok; /* initialized? */
+ int detached;
Py_ssize_t chunk_size;
PyObject *buffer;
PyObject *encoding;
@@ -759,6 +774,7 @@
int r;
self->ok = 0;
+ self->detached = 0;
if (!PyArg_ParseTupleAndKeywords(args, kwds, "O|zzzi:fileio",
kwlist, &buffer, &encoding, &errors,
&newline, &line_buffering))
@@ -1059,19 +1075,45 @@
#define CHECK_INITIALIZED(self) \
if (self->ok <= 0) { \
- PyErr_SetString(PyExc_ValueError, \
- "I/O operation on uninitialized object"); \
+ if (self->detached) { \
+ PyErr_SetString(PyExc_ValueError, \
+ "underlying buffer has been detached"); \
+ } else { \
+ PyErr_SetString(PyExc_ValueError, \
+ "I/O operation on uninitialized object"); \
+ } \
return NULL; \
}
#define CHECK_INITIALIZED_INT(self) \
if (self->ok <= 0) { \
- PyErr_SetString(PyExc_ValueError, \
- "I/O operation on uninitialized object"); \
+ if (self->detached) { \
+ PyErr_SetString(PyExc_ValueError, \
+ "underlying buffer has been detached"); \
+ } else { \
+ PyErr_SetString(PyExc_ValueError, \
+ "I/O operation on uninitialized object"); \
+ } \
return -1; \
}
+static PyObject *
+TextIOWrapper_detach(PyTextIOWrapperObject *self)
+{
+ PyObject *buffer, *res;
+ CHECK_INITIALIZED(self);
+ res = PyObject_CallMethodObjArgs((PyObject *)self, _PyIO_str_flush, NULL);
+ if (res == NULL)
+ return NULL;
+ Py_DECREF(res);
+ buffer = self->buffer;
+ self->buffer = NULL;
+ self->detached = 1;
+ self->ok = 0;
+ return buffer;
+}
+
Py_LOCAL_INLINE(const Py_UNICODE *)
findchar(const Py_UNICODE *s, Py_ssize_t size, Py_UNICODE ch)
{
@@ -2341,6 +2383,7 @@
}
static PyMethodDef TextIOWrapper_methods[] = {
+ {"detach", (PyCFunction)TextIOWrapper_detach, METH_NOARGS},
{"write", (PyCFunction)TextIOWrapper_write, METH_VARARGS},
{"read", (PyCFunction)TextIOWrapper_read, METH_VARARGS},
{"readline", (PyCFunction)TextIOWrapper_readline, METH_VARARGS},