From f90099c3bd8ba74ac69ffd26cbc443ae3ce00e10 Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Mon, 28 Aug 2023 01:59:48 +0200
Subject: [PATCH] [3.12] gh-107801: Document io.TextIOWrapper.tell (#108265)
 (#108547)

(cherry picked from commit 38afa4af9bfc8297a5ee270c37f3f120a04297ea)
---
 Doc/library/io.rst            | 10 +++++++++-
 Modules/_io/clinic/textio.c.h |  8 ++++++--
 Modules/_io/textio.c          |  7 ++++++-
 3 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 792bf43d9811bb..25f4d0d5841333 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -1054,13 +1054,21 @@ 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 opaque number.
+      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/clinic/textio.c.h b/Modules/_io/clinic/textio.c.h
index 63ec56311e2a63..4a3c133068df1d 100644
--- a/Modules/_io/clinic/textio.c.h
+++ b/Modules/_io/clinic/textio.c.h
@@ -815,7 +815,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 opaque number.\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__},
@@ -978,4 +982,4 @@ _io_TextIOWrapper_close(textio *self, PyObject *Py_UNUSED(ignored))
 {
     return _io_TextIOWrapper_close_impl(self);
 }
-/*[clinic end generated code: output=fc02f9e59bfa9956 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=a3614e1c64747ff5 input=a9049054013a1b77]*/
diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c
index ff6023c8ef9283..e8bf6bebad5509 100644
--- a/Modules/_io/textio.c
+++ b/Modules/_io/textio.c
@@ -2650,11 +2650,16 @@ _io_TextIOWrapper_seek_impl(textio *self, PyObject *cookieObj, int whence)
 
 /*[clinic input]
 _io.TextIOWrapper.tell
+
+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.
 [clinic start generated code]*/
 
 static PyObject *
 _io_TextIOWrapper_tell_impl(textio *self)
-/*[clinic end generated code: output=4f168c08bf34ad5f input=9a2caf88c24f9ddf]*/
+/*[clinic end generated code: output=4f168c08bf34ad5f input=0852d627d76fb520]*/
 {
     PyObject *res;
     PyObject *posobj = NULL;