(original) (raw)

changeset: 68747:fa0563f3b7f7 branch: 3.2 parent: 68744:5d4800b10acd parent: 68746:9201455f950b user: R David Murray rdmurray@bitdance.com date: Sun Mar 20 10:25:29 2011 -0400 files: Doc/library/csv.rst description: Really merge #7198 Changeset ab27f16f707a was messed up by a rebase (as were 959f666470cc and 9d1b1a95bc8f) and the patch only got applied to default. diff -r 5d4800b10acd -r fa0563f3b7f7 Doc/library/csv.rst --- a/Doc/library/csv.rst Sun Mar 20 15:31:26 2011 +0200 +++ b/Doc/library/csv.rst Sun Mar 20 10:25:29 2011 -0400 @@ -52,7 +52,7 @@ *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` 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ .. 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./rdmurray@bitdance.com