GH-95880: Clarify StringIO append/overwrite behavior. (GH-96104)

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 753e6c1e3b9b46a2afaa71754e3a54f0d8820a2f..97a70646a93cabc5a8d6b5e57e3b41dc7507665c 100644 (file)
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -1052,8 +1052,12 @@ Text I/O
 
    The initial value of the buffer can be set by providing *initial_value*.
    If newline translation is enabled, newlines will be encoded as if by
-   :meth:`~TextIOBase.write`.  The stream is positioned at the start of
-   the buffer.
+   :meth:`~TextIOBase.write`.  The stream is positioned at the start of the
+   buffer which emulates opening an existing file in a `w+` mode, making it
+   ready for an immediate write from the beginning or for a write that
+   would overwrite the initial value.  To emulate opening a file in an `a+`
+   mode ready for appending, use `f.seek(0, io.SEEK_END)` to reposition the
+   stream at the end of the buffer.
 
    The *newline* argument works like that of :class:`TextIOWrapper`,
    except that when writing output to the stream, if *newline* is ``None``,