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

rhettinger · web-flow · commit 511dea0a3ea9 · 2022-08-21T09:42:15.000-05:00
diff --git 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``,
