[Python-checkins] cpython (2.7): Issue #22413: Document newline effect on StringIO initializer and getvalue
martin.panter
python-checkins at python.org
Sat Oct 10 06:31:20 EDT 2015
https://hg.python.org/cpython/rev/57fc950298bb
changeset: 98637:57fc950298bb
branch: 2.7
user: Martin Panter <vadmium+py at gmail.com>
date: Sat Oct 10 02:52:30 2015 +0000
summary:
Issue #22413: Document newline effect on StringIO initializer and getvalue
Also add to comment in the C code.
files:
Doc/library/io.rst | 17 ++++++++++++-----
Modules/_io/_iomodule.h | 7 ++++++-
2 files changed, 18 insertions(+), 6 deletions(-)
diff --git a/Doc/library/io.rst b/Doc/library/io.rst
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -803,10 +803,16 @@
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 @@
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
--- a/Modules/_io/_iomodule.h
+++ b/Modules/_io/_iomodule.h
@@ -52,7 +52,12 @@
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);
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list