[Python-checkins] GH-95880: Clarify StringIO append/overwrite behavior. (GH-96104) (GH-96156)

[rhettinger]

https://github.com/python/cpython/commit/58e1fe24c71a865a60bc9975c664dabba77f8588
commit: 58e1fe24c71a865a60bc9975c664dabba77f8588
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2022-08-21T09:55:50-05:00
summary:

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

files:
M Doc/library/io.rst

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 753e6c1e3b9..97a70646a93 100644
--- 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``,