From 0c1c0d42dcc8fc223eb3aaa51d09d252b1738820 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Sat, 4 Aug 2012 00:55:38 +0200 Subject: [PATCH] Make TextIOWrapper's documentation clearer by copying the newline argument's description from open(). --- Doc/library/io.rst | 24 ++++++++++++++++-------- Modules/_io/textio.c | 25 ++++++++++++++++--------- 2 files changed, 32 insertions(+), 17 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 82f29cb1b3e..5f049c55202 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -757,14 +757,22 @@ Text I/O sequences) can be used. Any other error handling name that has been registered with :func:`codecs.register_error` is also valid. - *newline* can be ``None``, ``''``, ``'\n'``, ``'\r'``, or ``'\r\n'``. It - controls the handling of line endings. If it is ``None``, universal newlines - is enabled. With this enabled, on input, the lines endings ``'\n'``, - ``'\r'``, or ``'\r\n'`` are translated to ``'\n'`` before being returned to - the caller. Conversely, on output, ``'\n'`` is translated to the system - default line separator, :data:`os.linesep`. If *newline* is any other of its - legal values, that newline becomes the newline when the file is read and it - is returned untranslated. On output, ``'\n'`` is converted to the *newline*. + *newline* controls how line endings are handled. It can be ``None``, + ``''``, ``'\n'``, ``'\r'``, and ``'\r\n'``. It works as follows: + + * On input, if *newline* is ``None``, universal newlines mode is enabled. + Lines in the input can end in ``'\n'``, ``'\r'``, or ``'\r\n'``, and these + are translated into ``'\n'`` before being returned to the caller. If it is + ``''``, universal newline mode is enabled, but line endings are returned to + the caller untranslated. If it has any of the other legal values, input + lines are only terminated by the given string, and the line ending is + returned to the caller untranslated. + + * On output, if *newline* is ``None``, any ``'\n'`` characters written are + translated to the system default line separator, :data:`os.linesep`. If + *newline* is ``''``, no translation takes place. If *newline* is any of + the other legal values, any ``'\n'`` characters written are translated to + the given string. If *line_buffering* is ``True``, :meth:`flush` is implied when a call to write contains a newline character. diff --git a/Modules/_io/textio.c b/Modules/_io/textio.c index d86a1c7b6da..518108b00d5 100644 --- a/Modules/_io/textio.c +++ b/Modules/_io/textio.c @@ -622,15 +622,22 @@ PyDoc_STRVAR(textiowrapper_doc, "errors determines the strictness of encoding and decoding (see the\n" "codecs.register) and defaults to \"strict\".\n" "\n" - "newline can be None, '', '\\n', '\\r', or '\\r\\n'. It controls the\n" - "handling of line endings. If it is None, universal newlines is\n" - "enabled. With this enabled, on input, the lines endings '\\n', '\\r',\n" - "or '\\r\\n' are translated to '\\n' before being returned to the\n" - "caller. Conversely, on output, '\\n' is translated to the system\n" - "default line separator, os.linesep. If newline is any other of its\n" - "legal values, that newline becomes the newline when the file is read\n" - "and it is returned untranslated. On output, '\\n' is converted to the\n" - "newline.\n" + "newline controls how line endings are handled. It can be None, '',\n" + "'\\n', '\\r', and '\\r\\n'. It works as follows:\n" + "\n" + "* On input, if newline is None, universal newlines mode is\n" + " enabled. Lines in the input can end in '\\n', '\\r', or '\\r\\n', and\n" + " these are translated into '\\n' before being returned to the\n" + " caller. If it is '', universal newline mode is enabled, but line\n" + " endings are returned to the caller untranslated. If it has any of\n" + " the other legal values, input lines are only terminated by the given\n" + " string, and the line ending is returned to the caller untranslated.\n" + "\n" + "* On output, if newline is None, any '\\n' characters written are\n" + " translated to the system default line separator, os.linesep. If\n" + " newline is '', no translation takes place. If newline is any of the\n" + " other legal values, any '\\n' characters written are translated to\n" + " the given string.\n" "\n" "If line_buffering is True, a call to flush is implied when a call to\n" "write contains a newline character."