Changeset 391 for python/trunk/Doc/library/csv.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/csv.rst (modified) (14 diffs)

python/trunk/Doc/library/csv.rst

@@ -41 +41 @@
    there are currently some issues regarding ASCII NUL characters.  Accordingly,
    all input should be UTF-8 or printable ASCII to be safe; see the examples in
-   section :ref:`csv-examples`. These restrictions will be removed in the future.
+   section :ref:`csv-examples`.
 
 
@@ -58 +58 @@
 
 
-.. function:: reader(csvfile[, dialect='excel'][, fmtparam])
+.. function:: reader(csvfile, dialect='excel', **fmtparams)
 
    Return a reader object which will iterate over lines in the given *csvfile*.
@@ -68 +68 @@
    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
-   :func:`list_dialects` function.  The other optional *fmtparam* keyword arguments
+   :func:`list_dialects` function.  The other optional *fmtparams* keyword arguments
    can be given to override individual formatting parameters in the current
    dialect.  For full details about the dialect and formatting parameters, see
@@ -79 +79 @@
 
       >>> import csv
-      >>> spamReader = csv.reader(open('eggs.csv'), delimiter=' ', quotechar='|')
-      >>> for row in spamReader:
-      ...     print ', '.join(row)
+      >>> with open('eggs.csv', 'rb') as csvfile:
+      ...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
+      ...     for row in spamreader:
+      ...         print ', '.join(row)
       Spam, Spam, Spam, Spam, Spam, Baked Beans
       Spam, Lovely Spam, Wonderful Spam
@@ -95 +96 @@
 
 
-.. function:: writer(csvfile[, dialect='excel'][, fmtparam])
+.. function:: writer(csvfile, dialect='excel', **fmtparams)
 
    Return a writer object responsible for converting the user's data into delimited
@@ -104 +105 @@
    particular CSV dialect.  It may be an instance of a subclass of the
    :class:`Dialect` class or one of the strings returned by the
-   :func:`list_dialects` function.  The other optional *fmtparam* keyword arguments
+   :func:`list_dialects` function.  The other optional *fmtparams* keyword arguments
    can be given to override individual formatting parameters in the current
    dialect.  For full details about the dialect and formatting parameters, see
@@ -116 +117 @@
    A short usage example::
 
-      >>> import csv
-      >>> spamWriter = csv.writer(open('eggs.csv', 'w'), delimiter=' ',
-      ...                         quotechar='|', quoting=csv.QUOTE_MINIMAL)
-      >>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans'])
-      >>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
-
-
-.. function:: register_dialect(name[, dialect][, fmtparam])
+      import csv
+      with open('eggs.csv', 'wb') as csvfile:
+          spamwriter = csv.writer(csvfile, delimiter=' ',
+                                  quotechar='|', quoting=csv.QUOTE_MINIMAL)
+          spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
+          spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])
+
+
+.. function:: register_dialect(name[, dialect], **fmtparams)
 
    Associate *dialect* with *name*.  *name* must be a string or Unicode object. The
    dialect can be specified either by passing a sub-class of :class:`Dialect`, or
-   by *fmtparam* keyword arguments, or both, with keyword arguments overriding
+   by *fmtparams* keyword arguments, or both, with keyword arguments overriding
    parameters of the dialect. For full details about the dialect and formatting
    parameters, see section :ref:`csv-fmt-params`.
@@ -163 +165 @@
 
 
-.. class:: DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])
+.. class:: DictReader(csvfile, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)
 
    Create an object which operates like a regular reader but maps the information
@@ -176 +178 @@
 
 
-.. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]])
+.. class:: DictWriter(csvfile, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)
 
    Create an object which operates like a regular writer but maps dictionaries onto
@@ -220 +222 @@
    The :class:`Sniffer` class provides two methods:
 
-   .. method:: sniff(sample[, delimiters=None])
+   .. method:: sniff(sample, delimiters=None)
 
       Analyze the given *sample* and return a :class:`Dialect` subclass
@@ -235 +237 @@
 An example for :class:`Sniffer` use::
 
-   csvfile = open("example.csv")
-   dialect = csv.Sniffer().sniff(csvfile.read(1024))
-   csvfile.seek(0)
-   reader = csv.reader(csvfile, dialect)
-   # ... process CSV file contents here ...
+   with open('example.csv', 'rb') as csvfile:
+       dialect = csv.Sniffer().sniff(csvfile.read(1024))
+       csvfile.seek(0)
+       reader = csv.reader(csvfile, dialect)
+       # ... process CSV file contents here ...
 
 
@@ -354 +356 @@
 
 
+.. attribute:: Dialect.strict
+
+   When ``True``, raise exception :exc:`Error` on bad CSV input.
+   The default is ``False``.
+
 Reader Objects
 --------------
@@ -425 +432 @@
 
 
+DictWriter objects have the following public method:
+
+
+.. method:: DictWriter.writeheader()
+
+   Write a row with the field names (as specified in the constructor).
+
+   .. versionadded:: 2.7
+
+
 .. _csv-examples:
 
@@ -433 +450 @@
 
    import csv
-   reader = csv.reader(open("some.csv", "rb"))
-   for row in reader:
-       print row
-
-Reading a file with an alternate format::
-
-   import csv
-   reader = csv.reader(open("passwd", "rb"), delimiter=':', quoting=csv.QUOTE_NONE)
-   for row in reader:
-       print row
-
-The corresponding simplest possible writing example is::
-
-   import csv
-   writer = csv.writer(open("some.csv", "wb"))
-   writer.writerows(someiterable)
-
-Registering a new dialect::
-
-   import csv
-
-   csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
-
-   reader = csv.reader(open("passwd", "rb"), 'unixpwd')
-
-A slightly more advanced use of the reader --- catching and reporting errors::
-
-   import csv, sys
-   filename = "some.csv"
-   reader = csv.reader(open(filename, "rb"))
-   try:
+   with open('some.csv', 'rb') as f:
+       reader = csv.reader(f)
        for row in reader:
            print row
-   except csv.Error, e:
-       sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
+
+Reading a file with an alternate format::
+
+   import csv
+   with open('passwd', 'rb') as f:
+       reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
+       for row in reader:
+           print row
+
+The corresponding simplest possible writing example is::
+
+   import csv
+   with open('some.csv', 'wb') as f:
+       writer = csv.writer(f)
+       writer.writerows(someiterable)
+
+Registering a new dialect::
+
+   import csv
+   csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
+   with open('passwd', 'rb') as f:
+       reader = csv.reader(f, 'unixpwd')
+
+A slightly more advanced use of the reader --- catching and reporting errors::
+
+   import csv, sys
+   filename = 'some.csv'
+   with open(filename, 'rb') as f:
+       reader = csv.reader(f)
+       try:
+           for row in reader:
+               print row
+       except csv.Error as e:
+           sys.exit('file %s, line %d: %s' % (filename, reader.line_num, e))
 
 And while the module doesn't directly support parsing strings, it can easily be