From 42eae5bd05579c636a328c630fbdbb4835d9de74 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Fri, 19 Aug 2022 00:57:47 -0500 Subject: [PATCH] GH-95880: Clarify StringIO append/overwrite behavior. --- Doc/library/io.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 753e6c1e3b9b46..97a70646a93cab 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``,