Really merge #7198

Changeset ab27f16f707a was messed up by a rebase (as were
959f666470cc and 9d1b1a95bc8f) and the patch only got applied
to default.

Doc/library/csv.rst

@@ -52,7 +52,7 @@ The :mod:`csv` module defines the following functions:
    *csvfile* can be any object which supports the :term:`iterator` protocol and returns a
    string each time its :meth:`!__next__` method is called --- :term:`file objects
    <file object>` and list objects are both suitable.   If *csvfile* is a file object,
-   it should be opened with ``newline=''``. [#]_  An optional
+   it should be opened with ``newline=''``. [1]_  An optional
    *dialect* parameter can be given which is used to define a set of parameters
    specific to a particular CSV dialect.  It may be an instance of a subclass of
    the :class:`Dialect` class or one of the strings returned by the
@@ -79,7 +79,8 @@ The :mod:`csv` module defines the following functions:
 
    Return a writer object responsible for converting the user's data into delimited
    strings on the given file-like object.  *csvfile* can be any object with a
-   :func:`write` method.  An optional *dialect*
+   :func:`write` method.  If csvfile is a file object, it should be opened with
+   newline='' [1]_.  An optional *dialect*
    parameter can be given which is used to define a set of parameters specific to a
    particular CSV dialect.  It may be an instance of a subclass of the
    :class:`Dialect` class or one of the strings returned by the
@@ -96,7 +97,7 @@ The :mod:`csv` module defines the following functions:
    A short usage example::
 
       >>> import csv
-      >>> spamWriter = csv.writer(open('eggs.csv', 'w'), delimiter=' ',
+      >>> spamWriter = csv.writer(open('eggs.csv', 'w', newline=''), delimiter=' ',
       ...                         quotechar='|', quoting=csv.QUOTE_MINIMAL)
       >>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans'])
       >>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
@@ -427,7 +428,7 @@ The simplest example of reading a CSV file::
 Reading a file with an alternate format::
 
    import csv
-   with open('passwd') as f:
+   with open('passwd', newline='') as f:
        reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
        for row in reader:
            print(row)
@@ -435,7 +436,7 @@ Reading a file with an alternate format::
 The corresponding simplest possible writing example is::
 
    import csv
-   with open('some.csv', 'w') as f:
+   with open('some.csv', 'w', newline='') as f:
        writer = csv.writer(f)
        writer.writerows(someiterable)
 
@@ -457,7 +458,7 @@ Registering a new dialect::
 
    import csv
    csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
-   with open('passwd') as f:
+   with open('passwd', newline='') as f:
        reader = csv.reader(f, 'unixpwd')
 
 A slightly more advanced use of the reader --- catching and reporting errors::
@@ -482,7 +483,7 @@ done::
 
 .. rubric:: Footnotes
 
-.. [#] If ``newline=''`` is not specified, newlines embedded inside quoted fields
-   will not be interpreted correctly.  It should always be safe to specify
-   ``newline=''``, since the csv module does its own universal newline handling
-   on input.
+.. [1] If ``newline=''`` is not specified, newlines embedded inside quoted fields
+   will not be interpreted correctly, and on platforms that use ``\r\n`` linendings
+   on write an extra `\\r` will be added.  It should always be safe to specify
+   ``newline=''``, since the csv module does its own (universal) newline handling.