From: Raymond Hettinger Date: Sun, 21 Aug 2022 14:42:15 +0000 (-0500) Subject: GH-95880: Clarify StringIO append/overwrite behavior. (GH-96104) X-Git-Tag: v3.12.0a1~596 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=511dea0a3ea9beb2fd72c7c689e2b1cb1636a6fa;p=thirdparty%2FPython%2Fcpython.git GH-95880: Clarify StringIO append/overwrite behavior. (GH-96104) --- diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 753e6c1e3b9b..97a70646a93c 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``,