From: Martin Panter <vadmium+py@gmail.com>
Date: Sat, 10 Oct 2015 02:52:30 +0000 (+0000)
Subject: Issue #22413: Document newline effect on StringIO initializer and getvalue
X-Git-Tag: v2.7.11rc1~71
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=dab305ef059434366e3a0c46533ff3b206e70463;p=python

Issue #22413: Document newline effect on StringIO initializer and getvalue

Also add to comment in the C code.
---

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 33cbb7e781..6743b2711b 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -803,10 +803,16 @@ Text I/O
 
    An in-memory stream for unicode text.  It inherits :class:`TextIOWrapper`.
 
-   The initial value of the buffer (an empty unicode string by default) can
-   be set by providing *initial_value*.  The *newline* argument works like
-   that of :class:`TextIOWrapper`.  The default is to consider only ``\n``
-   characters as end of lines and to do no newline translation.
+   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.
+
+   The *newline* argument works like that of :class:`TextIOWrapper`.
+   The default is to consider only ``\n`` characters as ends of lines and
+   to do no newline translation.  If *newline* is set to ``None``,
+   newlines are written as ``\n`` on all platforms, but universal
+   newline decoding is still performed when reading.
 
    :class:`StringIO` provides this method in addition to those from
    :class:`TextIOWrapper` and its parents:
@@ -815,7 +821,8 @@ Text I/O
 
       Return a ``unicode`` containing the entire contents of the buffer at any
       time before the :class:`StringIO` object's :meth:`close` method is
-      called.
+      called.  Newlines are decoded as if by :meth:`~TextIOBase.read`,
+      although the stream position is not changed.
 
    Example usage::
 
diff --git a/Modules/_io/_iomodule.h b/Modules/_io/_iomodule.h
index c282e61217..79aaa90e8a 100644
--- a/Modules/_io/_iomodule.h
+++ b/Modules/_io/_iomodule.h
@@ -52,7 +52,12 @@ extern PyObject *_PyIncrementalNewlineDecoder_decode(
    which can be safely put aside until another search.
    
    NOTE: for performance reasons, `end` must point to a NUL character ('\0'). 
-   Otherwise, the function will scan further and return garbage. */
+   Otherwise, the function will scan further and return garbage.
+
+   There are three modes, in order of priority:
+   * translated: Only find \n (assume newlines already translated)
+   * universal: Use universal newlines algorithm
+   * Otherwise, the line ending is specified by readnl, a str object */
 extern Py_ssize_t _PyIO_find_line_ending(
     int translated, int universal, PyObject *readnl,
     Py_UNICODE *start, Py_UNICODE *end, Py_ssize_t *consumed);