Skip to content

Commit ccb2c0e

Browse files
committed
Issue python#23214: Implement optional BufferedReader, BytesIO read1() argument
1 parent ea8762c commit ccb2c0e

9 files changed

Lines changed: 81 additions & 39 deletions

File tree

‎Doc/library/io.rst‎

Lines changed: 15 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -477,14 +477,17 @@ I/O Base Classes
477477
A :exc:`BlockingIOError` is raised if the underlying raw stream is in
478478
non blocking-mode, and has no data available at the moment.
479479

480-
.. method:: read1(size=-1)
480+
.. method:: read1([size])
481481

482482
Read and return up to *size* bytes, with at most one call to the
483483
underlying raw stream's :meth:`~RawIOBase.read` (or
484484
:meth:`~RawIOBase.readinto`) method. This can be useful if you are
485485
implementing your own buffering on top of a :class:`BufferedIOBase`
486486
object.
487487

488+
If *size* is −1 (the default), an arbitrary number of bytes are
489+
returned (more than zero unless EOF is reached).
490+
488491
.. method:: readinto(b)
489492

490493
Read bytes into a pre-allocated, writable
@@ -628,13 +631,16 @@ than raw I/O does.
628631
Return :class:`bytes` containing the entire contents of the buffer.
629632

630633

631-
.. method:: read1()
634+
.. method:: read1([size])
635+
636+
In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.read`.
632637

633-
In :class:`BytesIO`, this is the same as :meth:`read`.
638+
.. versionchanged:: 3.7
639+
The *size* argument is now optional.
634640

635-
.. method:: readinto1()
641+
.. method:: readinto1(b)
636642

637-
In :class:`BytesIO`, this is the same as :meth:`readinto`.
643+
In :class:`BytesIO`, this is the same as :meth:`~BufferedIOBase.readinto`.
638644

639645
.. versionadded:: 3.5
640646

@@ -664,12 +670,15 @@ than raw I/O does.
664670
Read and return *size* bytes, or if *size* is not given or negative, until
665671
EOF or if the read call would block in non-blocking mode.
666672

667-
.. method:: read1(size)
673+
.. method:: read1([size])
668674

669675
Read and return up to *size* bytes with only one call on the raw stream.
670676
If at least one byte is buffered, only buffered bytes are returned.
671677
Otherwise, one raw stream read call is made.
672678

679+
.. versionchanged:: 3.7
680+
The *size* argument is now optional.
681+
673682

674683
.. class:: BufferedWriter(raw, buffer_size=DEFAULT_BUFFER_SIZE)
675684

‎Lib/_pyio.py‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -635,7 +635,7 @@ class BufferedIOBase(IOBase):
635635
implementation, but wrap one.
636636
"""
637637

638-
def read(self, size=None):
638+
def read(self, size=-1):
639639
"""Read and return up to size bytes, where size is an int.
640640
641641
If the argument is omitted, None, or negative, reads and
@@ -655,7 +655,7 @@ def read(self, size=None):
655655
"""
656656
self._unsupported("read")
657657

658-
def read1(self, size=None):
658+
def read1(self, size=-1):
659659
"""Read up to size bytes with at most one read() system call,
660660
where size is an int.
661661
"""
@@ -863,7 +863,7 @@ def close(self):
863863
self._buffer.clear()
864864
super().close()
865865

866-
def read(self, size=None):
866+
def read(self, size=-1):
867867
if self.closed:
868868
raise ValueError("read from closed file")
869869
if size is None:
@@ -877,7 +877,7 @@ def read(self, size=None):
877877
self._pos = newpos
878878
return bytes(b)
879879

880-
def read1(self, size):
880+
def read1(self, size=-1):
881881
"""This is the same as read.
882882
"""
883883
return self.read(size)
@@ -1073,12 +1073,12 @@ def _peek_unlocked(self, n=0):
10731073
self._read_pos = 0
10741074
return self._read_buf[self._read_pos:]
10751075

1076-
def read1(self, size):
1076+
def read1(self, size=-1):
10771077
"""Reads up to size bytes, with at most one read() system call."""
10781078
# Returns up to size bytes. If at least one byte is buffered, we
10791079
# only return buffered bytes. Otherwise, we do one raw read.
10801080
if size < 0:
1081-
raise ValueError("number of bytes to read must be positive")
1081+
size = self.buffer_size
10821082
if size == 0:
10831083
return b""
10841084
with self._read_lock:
@@ -1270,7 +1270,7 @@ def __init__(self, reader, writer, buffer_size=DEFAULT_BUFFER_SIZE):
12701270
self.reader = BufferedReader(reader, buffer_size)
12711271
self.writer = BufferedWriter(writer, buffer_size)
12721272

1273-
def read(self, size=None):
1273+
def read(self, size=-1):
12741274
if size is None:
12751275
size = -1
12761276
return self.reader.read(size)
@@ -1284,7 +1284,7 @@ def write(self, b):
12841284
def peek(self, size=0):
12851285
return self.reader.peek(size)
12861286

1287-
def read1(self, size):
1287+
def read1(self, size=-1):
12881288
return self.reader.read1(size)
12891289

12901290
def readinto1(self, b):
@@ -1370,7 +1370,7 @@ def peek(self, size=0):
13701370
self.flush()
13711371
return BufferedReader.peek(self, size)
13721372

1373-
def read1(self, size):
1373+
def read1(self, size=-1):
13741374
self.flush()
13751375
return BufferedReader.read1(self, size)
13761376

‎Lib/test/test_io.py‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1146,6 +1146,7 @@ def test_read1(self):
11461146
self.assertEqual(b"a", bufio.read(1))
11471147
self.assertEqual(b"b", bufio.read1(1))
11481148
self.assertEqual(rawio._reads, 1)
1149+
self.assertEqual(b"", bufio.read1(0))
11491150
self.assertEqual(b"c", bufio.read1(100))
11501151
self.assertEqual(rawio._reads, 1)
11511152
self.assertEqual(b"d", bufio.read1(100))
@@ -1154,8 +1155,17 @@ def test_read1(self):
11541155
self.assertEqual(rawio._reads, 3)
11551156
self.assertEqual(b"", bufio.read1(100))
11561157
self.assertEqual(rawio._reads, 4)
1157-
# Invalid args
1158-
self.assertRaises(ValueError, bufio.read1, -1)
1158+
1159+
def test_read1_arbitrary(self):
1160+
rawio = self.MockRawIO((b"abc", b"d", b"efg"))
1161+
bufio = self.tp(rawio)
1162+
self.assertEqual(b"a", bufio.read(1))
1163+
self.assertEqual(b"bc", bufio.read1())
1164+
self.assertEqual(b"d", bufio.read1())
1165+
self.assertEqual(b"efg", bufio.read1(-1))
1166+
self.assertEqual(rawio._reads, 3)
1167+
self.assertEqual(b"", bufio.read1())
1168+
self.assertEqual(rawio._reads, 4)
11591169

11601170
def test_readinto(self):
11611171
rawio = self.MockRawIO((b"abc", b"d", b"efg"))
@@ -1806,6 +1816,7 @@ def test_read1(self):
18061816
pair = self.tp(self.BytesIO(b"abcdef"), self.MockRawIO())
18071817

18081818
self.assertEqual(pair.read1(3), b"abc")
1819+
self.assertEqual(pair.read1(), b"def")
18091820

18101821
def test_readinto(self):
18111822
for method in ("readinto", "readinto1"):
@@ -3467,6 +3478,7 @@ def test_io_after_close(self):
34673478
self.assertRaises(ValueError, f.read)
34683479
if hasattr(f, "read1"):
34693480
self.assertRaises(ValueError, f.read1, 1024)
3481+
self.assertRaises(ValueError, f.read1)
34703482
if hasattr(f, "readall"):
34713483
self.assertRaises(ValueError, f.readall)
34723484
if hasattr(f, "readinto"):

‎Lib/test/test_memoryio.py‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -437,10 +437,8 @@ def test_getbuffer(self):
437437

438438
def test_read1(self):
439439
buf = self.buftype("1234567890")
440-
memio = self.ioclass(buf)
441-
442-
self.assertRaises(TypeError, memio.read1)
443-
self.assertEqual(memio.read(), buf)
440+
self.assertEqual(self.ioclass(buf).read1(), buf)
441+
self.assertEqual(self.ioclass(buf).read1(-1), buf)
444442

445443
def test_readinto(self):
446444
buf = self.buftype("1234567890")

‎Misc/NEWS‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,10 @@ Core and Builtins
8888
Library
8989
-------
9090

91+
- Issue #23214: In the "io" module, the argument to BufferedReader and
92+
BytesIO's read1() methods is now optional and can be -1, matching the
93+
BufferedIOBase specification.
94+
9195
- Issue #28480: Fix error building socket module when multithreading is
9296
disabled.
9397

‎Modules/_io/bufferedio.c‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -904,7 +904,7 @@ _io__Buffered_read_impl(buffered *self, Py_ssize_t n)
904904
CHECK_INITIALIZED(self)
905905
if (n < -1) {
906906
PyErr_SetString(PyExc_ValueError,
907-
"read length must be positive or -1");
907+
"read length must be non-negative or -1");
908908
return NULL;
909909
}
910910

@@ -932,22 +932,20 @@ _io__Buffered_read_impl(buffered *self, Py_ssize_t n)
932932

933933
/*[clinic input]
934934
_io._Buffered.read1
935-
size as n: Py_ssize_t
935+
size as n: Py_ssize_t = -1
936936
/
937937
[clinic start generated code]*/
938938

939939
static PyObject *
940940
_io__Buffered_read1_impl(buffered *self, Py_ssize_t n)
941-
/*[clinic end generated code: output=bcc4fb4e54d103a3 input=8d2869c18b983184]*/
941+
/*[clinic end generated code: output=bcc4fb4e54d103a3 input=7d22de9630b61774]*/
942942
{
943943
Py_ssize_t have, r;
944944
PyObject *res = NULL;
945945

946946
CHECK_INITIALIZED(self)
947947
if (n < 0) {
948-
PyErr_SetString(PyExc_ValueError,
949-
"read length must be positive");
950-
return NULL;
948+
n = self->buffer_size;
951949
}
952950

953951
CHECK_CLOSED(self, "read of closed file")

‎Modules/_io/bytesio.c‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -420,7 +420,7 @@ _io_BytesIO_read_impl(bytesio *self, PyObject *arg)
420420

421421
/*[clinic input]
422422
_io.BytesIO.read1
423-
size: object
423+
size: object(c_default="Py_None") = -1
424424
/
425425
426426
Read at most size bytes, returned as a bytes object.
@@ -430,8 +430,8 @@ Return an empty bytes object at EOF.
430430
[clinic start generated code]*/
431431

432432
static PyObject *
433-
_io_BytesIO_read1(bytesio *self, PyObject *size)
434-
/*[clinic end generated code: output=16021f5d0ac3d4e2 input=d4f40bb8f2f99418]*/
433+
_io_BytesIO_read1_impl(bytesio *self, PyObject *size)
434+
/*[clinic end generated code: output=a60d80c84c81a6b8 input=0951874bafee8e80]*/
435435
{
436436
return _io_BytesIO_read_impl(self, size);
437437
}

‎Modules/_io/clinic/bufferedio.c.h‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -140,23 +140,24 @@ _io__Buffered_read(buffered *self, PyObject *args)
140140
}
141141

142142
PyDoc_STRVAR(_io__Buffered_read1__doc__,
143-
"read1($self, size, /)\n"
143+
"read1($self, size=-1, /)\n"
144144
"--\n"
145145
"\n");
146146

147147
#define _IO__BUFFERED_READ1_METHODDEF \
148-
{"read1", (PyCFunction)_io__Buffered_read1, METH_O, _io__Buffered_read1__doc__},
148+
{"read1", (PyCFunction)_io__Buffered_read1, METH_VARARGS, _io__Buffered_read1__doc__},
149149

150150
static PyObject *
151151
_io__Buffered_read1_impl(buffered *self, Py_ssize_t n);
152152

153153
static PyObject *
154-
_io__Buffered_read1(buffered *self, PyObject *arg)
154+
_io__Buffered_read1(buffered *self, PyObject *args)
155155
{
156156
PyObject *return_value = NULL;
157-
Py_ssize_t n;
157+
Py_ssize_t n = -1;
158158

159-
if (!PyArg_Parse(arg, "n:read1", &n)) {
159+
if (!PyArg_ParseTuple(args, "|n:read1",
160+
&n)) {
160161
goto exit;
161162
}
162163
return_value = _io__Buffered_read1_impl(self, n);
@@ -475,4 +476,4 @@ _io_BufferedRandom___init__(PyObject *self, PyObject *args, PyObject *kwargs)
475476
exit:
476477
return return_value;
477478
}
478-
/*[clinic end generated code: output=a956f394ecde4cf9 input=a9049054013a1b77]*/
479+
/*[clinic end generated code: output=490c97bfcfd92c51 input=a9049054013a1b77]*/

‎Modules/_io/clinic/bytesio.c.h‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ _io_BytesIO_read(bytesio *self, PyObject *args)
181181
}
182182

183183
PyDoc_STRVAR(_io_BytesIO_read1__doc__,
184-
"read1($self, size, /)\n"
184+
"read1($self, size=-1, /)\n"
185185
"--\n"
186186
"\n"
187187
"Read at most size bytes, returned as a bytes object.\n"
@@ -190,7 +190,27 @@ PyDoc_STRVAR(_io_BytesIO_read1__doc__,
190190
"Return an empty bytes object at EOF.");
191191

192192
#define _IO_BYTESIO_READ1_METHODDEF \
193-
{"read1", (PyCFunction)_io_BytesIO_read1, METH_O, _io_BytesIO_read1__doc__},
193+
{"read1", (PyCFunction)_io_BytesIO_read1, METH_VARARGS, _io_BytesIO_read1__doc__},
194+
195+
static PyObject *
196+
_io_BytesIO_read1_impl(bytesio *self, PyObject *size);
197+
198+
static PyObject *
199+
_io_BytesIO_read1(bytesio *self, PyObject *args)
200+
{
201+
PyObject *return_value = NULL;
202+
PyObject *size = Py_None;
203+
204+
if (!PyArg_UnpackTuple(args, "read1",
205+
0, 1,
206+
&size)) {
207+
goto exit;
208+
}
209+
return_value = _io_BytesIO_read1_impl(self, size);
210+
211+
exit:
212+
return return_value;
213+
}
194214

195215
PyDoc_STRVAR(_io_BytesIO_readline__doc__,
196216
"readline($self, size=None, /)\n"
@@ -428,4 +448,4 @@ _io_BytesIO___init__(PyObject *self, PyObject *args, PyObject *kwargs)
428448
exit:
429449
return return_value;
430450
}
431-
/*[clinic end generated code: output=6382e8eb578eea64 input=a9049054013a1b77]*/
451+
/*[clinic end generated code: output=8f469431da1b3857 input=a9049054013a1b77]*/

0 commit comments

Comments
 (0)