From 488a76c4649fe1197c1a47a88c593040a936b2e2 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 22 Aug 2023 10:10:13 +0200 Subject: [PATCH 1/4] gh-107801: Document io.TextIOWrapper.tell --- Doc/library/io.rst | 11 ++++++++++- Modules/_io/textio.c | 5 +++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 792bf43d9811bb..1914bb137ae0b2 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1054,13 +1054,22 @@ Text I/O * ``seek(0, SEEK_SET)``: Rewind to the start of the stream. * ``seek(cookie, SEEK_SET)``: Restore a previous position; - *cookie* **must be** a number returned by :meth:`!tell`. + *cookie* **must be** a number returned by :meth:`tell`. * ``seek(0, SEEK_END)``: Fast-forward to the end of the stream. * ``seek(0, SEEK_CUR)``: Leave the current stream position unchanged. Any other argument combinations are invalid, and may raise exceptions. + .. method:: tell() + + Return the stream position as an encoded :class:`int`, + referred to as a "cookie". + The return value of :meth:`!tell` can be given as input to :meth:`seek`, + to restore a previous stream position. + + + .. class:: StringIO(initial_value='', newline='\n') A text stream using an in-memory text buffer. It inherits diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c index d87bd0054d4438..d5d6eefda0c219 100644 --- a/Modules/_io/textio.c +++ b/Modules/_io/textio.c @@ -2640,6 +2640,11 @@ _io_TextIOWrapper_seek_impl(textio *self, PyObject *cookieObj, int whence) /*[clinic input] _io.TextIOWrapper.tell + +Return the stream position as an encoded int, referred to as a "cookie". + +The return value of tell() can be given as input to seek(), to restore a +previous stream position. [clinic start generated code]*/ static PyObject * From f3f669029df5f8b55eadec13c18704332053e359 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Tue, 22 Aug 2023 10:25:02 +0200 Subject: [PATCH 2/4] Regen clinic --- Modules/_io/clinic/textio.c.h | 8 ++++++-- Modules/_io/textio.c | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/Modules/_io/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h index 9bccd71e1d3ea6..e30b4734eb608f 100644 --- a/Modules/_io/clinic/textio.c.h +++ b/Modules/_io/clinic/textio.c.h @@ -812,7 +812,11 @@ _io_TextIOWrapper_seek(textio *self, PyObject *const *args, Py_ssize_t nargs) PyDoc_STRVAR(_io_TextIOWrapper_tell__doc__, "tell($self, /)\n" "--\n" -"\n"); +"\n" +"Return the stream position as an encoded int, referred to as a \"cookie\".\n" +"\n" +"The return value of tell() can be given as input to seek(), to restore a\n" +"previous stream position."); #define _IO_TEXTIOWRAPPER_TELL_METHODDEF \ {"tell", (PyCFunction)_io_TextIOWrapper_tell, METH_NOARGS, _io_TextIOWrapper_tell__doc__}, @@ -975,4 +979,4 @@ _io_TextIOWrapper_close(textio *self, PyObject *Py_UNUSED(ignored)) { return _io_TextIOWrapper_close_impl(self); } -/*[clinic end generated code: output=6bd981a58fcbc778 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=476074297480c8ad input=a9049054013a1b77]*/ diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c index d5d6eefda0c219..ea34ac121c8cea 100644 --- a/Modules/_io/textio.c +++ b/Modules/_io/textio.c @@ -2649,7 +2649,7 @@ previous stream position. static PyObject * _io_TextIOWrapper_tell_impl(textio *self) -/*[clinic end generated code: output=4f168c08bf34ad5f input=9a2caf88c24f9ddf]*/ +/*[clinic end generated code: output=4f168c08bf34ad5f input=9ad104776ed95ada]*/ { PyObject *res; PyObject *posobj = NULL; From 709e467efad38ea73a0ceee98f8e827ed63eef25 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 27 Aug 2023 22:02:19 +0200 Subject: [PATCH 3/4] Update Doc/library/io.rst --- Doc/library/io.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 1914bb137ae0b2..25f4d0d5841333 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -1063,8 +1063,7 @@ Text I/O .. method:: tell() - Return the stream position as an encoded :class:`int`, - referred to as a "cookie". + Return the stream position as an opaque number. The return value of :meth:`!tell` can be given as input to :meth:`seek`, to restore a previous stream position. From 9dacc0d73481f1f95661bc16ae5f84bb5b50b590 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 27 Aug 2023 22:04:35 +0200 Subject: [PATCH 4/4] Update docstring also --- Modules/_io/clinic/textio.c.h | 4 ++-- Modules/_io/textio.c | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Modules/_io/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h index d820ac8fd0562f..ce6efbe20b6bba 100644 --- a/Modules/_io/clinic/textio.c.h +++ b/Modules/_io/clinic/textio.c.h @@ -814,7 +814,7 @@ PyDoc_STRVAR(_io_TextIOWrapper_tell__doc__, "tell($self, /)\n" "--\n" "\n" -"Return the stream position as an encoded int, referred to as a \"cookie\".\n" +"Return the stream position as an opaque number.\n" "\n" "The return value of tell() can be given as input to seek(), to restore a\n" "previous stream position."); @@ -980,4 +980,4 @@ _io_TextIOWrapper_close(textio *self, PyObject *Py_UNUSED(ignored)) { return _io_TextIOWrapper_close_impl(self); } -/*[clinic end generated code: output=392e2375041a70a2 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=390af0e65a0d02c0 input=a9049054013a1b77]*/ diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c index ea34ac121c8cea..8e44d453269a71 100644 --- a/Modules/_io/textio.c +++ b/Modules/_io/textio.c @@ -2641,7 +2641,7 @@ _io_TextIOWrapper_seek_impl(textio *self, PyObject *cookieObj, int whence) /*[clinic input] _io.TextIOWrapper.tell -Return the stream position as an encoded int, referred to as a "cookie". +Return the stream position as an opaque number. The return value of tell() can be given as input to seek(), to restore a previous stream position. @@ -2649,7 +2649,7 @@ previous stream position. static PyObject * _io_TextIOWrapper_tell_impl(textio *self) -/*[clinic end generated code: output=4f168c08bf34ad5f input=9ad104776ed95ada]*/ +/*[clinic end generated code: output=4f168c08bf34ad5f input=0852d627d76fb520]*/ { PyObject *res; PyObject *posobj = NULL;