| This version of the :mod:`csv` module doesn't support Unicode input. Also, |
| 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. |
| |
| |
| .. seealso:: |
| |
n | .. % \seemodule{array}{Arrays of uniformly types numeric values.} |
| |
| :pep:`305` - CSV File API |
| The Python Enhancement Proposal which proposed this addition to Python. |
| |
| |
| .. _csv-contents: |
| |
| Module Contents |
| --------------- |
| |
| The :mod:`csv` module defines the following functions: |
| |
| |
n | .. function:: reader(csvfile[, dialect=``'excel'``][, fmtparam]) |
n | .. function:: reader(csvfile[, dialect='excel'][, fmtparam]) |
| |
| Return a reader object which will iterate over lines in the given *csvfile*. |
n | *csvfile* can be any object which supports the iterator protocol and returns a |
n | *csvfile* can be any object which supports the :term:`iterator` protocol and returns a |
| string each time its :meth:`next` method is called --- file objects and list |
| objects are both suitable. If *csvfile* is a file object, it must be opened |
| with the 'b' flag on platforms where that makes a difference. 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 |
| :func:`list_dialects` function. The other optional *fmtparam* keyword arguments |
| can be given to override individual formatting parameters in the current |
n | dialect. For more information about the dialect and formatting parameters, see |
n | dialect. For full details about the dialect and formatting parameters, see |
| section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters" for details |
| section :ref:`csv-fmt-params`. |
| of these parameters. |
| |
| All data read are returned as strings. No automatic data type conversion is |
| performed. |
n | |
| A short usage example:: |
| |
| >>> import csv |
| >>> spamReader = csv.reader(open('eggs.csv'), delimiter=' ', quotechar='|') |
| >>> for row in spamReader: |
| ... print ', '.join(row) |
| Spam, Spam, Spam, Spam, Spam, Baked Beans |
| Spam, Lovely Spam, Wonderful Spam |
| |
| .. versionchanged:: 2.5 |
| The parser is now stricter with respect to multi-line quoted fields. Previously, |
| if a line ended within a quoted field without a terminating newline character, a |
| newline would be inserted into the returned field. This behavior caused problems |
| when reading files which contained carriage return characters within fields. |
| The behavior was changed to return the field without inserting newlines. As a |
| consequence, if newlines embedded within fields are important, the input should |
| be split into lines in a manner which preserves the newline characters. |
| |
| |
n | .. function:: writer(csvfile[, dialect=``'excel'``][, fmtparam]) |
n | .. function:: writer(csvfile[, dialect='excel'][, fmtparam]) |
| |
| 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. If *csvfile* is a file object, it must be opened with the |
| 'b' flag on platforms where that makes a difference. 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 |
| :func:`list_dialects` function. The other optional *fmtparam* keyword arguments |
| can be given to override individual formatting parameters in the current |
n | dialect. For more information about the dialect and formatting parameters, see |
n | dialect. For full details about the dialect and formatting parameters, see |
| section :ref:`csv-fmt-params`, "Dialects and Formatting Parameters" for details |
| section :ref:`csv-fmt-params`. To make it |
| of these parameters. To make it as easy as possible to interface with modules |
| as easy as possible to interface with modules which implement the DB API, the |
| which implement the DB API, the value :const:`None` is written as the empty |
| value :const:`None` is written as the empty string. While this isn't a |
| string. While this isn't a reversible transformation, it makes it easier to |
| reversible transformation, it makes it easier to dump SQL NULL data values to |
| dump SQL NULL data values to CSV files without preprocessing the data returned |
| CSV files without preprocessing the data returned from a ``cursor.fetch*`` call. |
| from a ``cursor.fetch*`` call. All other non-string data are stringified with |
| All other non-string data are stringified with :func:`str` before being written. |
| :func:`str` before being written. |
| |
| A short usage example:: |
| |
| >>> import csv |
| >>> spamWriter = csv.writer(open('eggs.csv', 'w'), delimiter=' ', |
| ... quotechar='|', quoting=QUOTE_MINIMAL) |
| >>> spamWriter.writerow(['Spam'] * 5 + ['Baked Beans']) |
| >>> spamWriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam']) |
| |
| |
| .. function:: register_dialect(name[, dialect][, fmtparam]) |
| |
| 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 |
n | parameters of the dialect. For more information about the dialect and formatting |
n | parameters of the dialect. For full details about the dialect and formatting |
| parameters, see section :ref:`csv-fmt-params`, "Dialects and Formatting |
| parameters, see section :ref:`csv-fmt-params`. |
| Parameters" for details of these parameters. |
| |
| |
| .. function:: unregister_dialect(name) |
| |
| Delete the dialect associated with *name* from the dialect registry. An |
| :exc:`Error` is raised if *name* is not a registered dialect name. |
| |
| |
| .. function:: get_dialect(name) |
| |
| Return the dialect associated with *name*. An :exc:`Error` is raised if *name* |
| is not a registered dialect name. |
| |
n | .. versionchanged:: 2.5 |
| This function now returns an immutable :class:`Dialect`. Previously an |
| instance of the requested dialect was returned. Users could modify the |
| underlying class, changing the behavior of active readers and writers. |
| |
| .. function:: list_dialects() |
| |
| Return the names of all registered dialects. |
| |
| |
| .. function:: field_size_limit([new_limit]) |
| |
| Returns the current maximum field size allowed by the parser. If *new_limit* is |
| given, this becomes the new limit. |
| |
| .. versionadded:: 2.5 |
| |
| The :mod:`csv` module defines the following classes: |
| |
| |
n | .. class:: DictReader(csvfile[, fieldnames=:const:`None`,[, restkey=:const:`None`[, restval=:const:`None`[, dialect=``'excel'``[, *args, **kwds]]]]]) |
n | .. 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 |
| read into a dict whose keys are given by the optional *fieldnames* parameter. |
| If the *fieldnames* parameter is omitted, the values in the first row of the |
| *csvfile* will be used as the fieldnames. If the row read has fewer fields than |
| the fieldnames sequence, the value of *restval* will be used as the default |
| value. If the row read has more fields than the fieldnames sequence, the |
| remaining data is added as a sequence keyed by the value of *restkey*. If the |
| row read has fewer fields than the fieldnames sequence, the remaining keys take |
| the value of the optional *restval* parameter. Any other optional or keyword |
| arguments are passed to the underlying :class:`reader` instance. |
| |
| |
n | .. class:: DictWriter(csvfile, fieldnames[, restval=""[, extrasaction=``'raise'``[, dialect=``'excel'``[, *args, **kwds]]]]) |
n | .. class:: DictWriter(csvfile, fieldnames[, restval=''[, extrasaction='raise'[, dialect='excel'[, *args, **kwds]]]]) |
| |
| Create an object which operates like a regular writer but maps dictionaries onto |
| output rows. The *fieldnames* parameter identifies the order in which values in |
| the dictionary passed to the :meth:`writerow` method are written to the |
| *csvfile*. The optional *restval* parameter specifies the value to be written |
| if the dictionary is missing a key in *fieldnames*. If the dictionary passed to |
| the :meth:`writerow` method contains a key not found in *fieldnames*, the |
| optional *extrasaction* parameter indicates what action to take. If it is set |
| The :class:`Dialect` class is a container class relied on primarily for its |
| attributes, which are used to define the parameters for a specific |
| :class:`reader` or :class:`writer` instance. |
| |
| |
| .. class:: excel() |
| |
| The :class:`excel` class defines the usual properties of an Excel-generated CSV |
n | file. |
n | file. It is registered with the dialect name ``'excel'``. |
| |
| |
| .. class:: excel_tab() |
| |
| The :class:`excel_tab` class defines the usual properties of an Excel-generated |
n | TAB-delimited file. |
n | TAB-delimited file. It is registered with the dialect name ``'excel-tab'``. |
| |
| |
| .. class:: Sniffer() |
| |
| The :class:`Sniffer` class is used to deduce the format of a CSV file. |
| |
n | The :class:`Sniffer` class provides two methods: |
n | The :class:`Sniffer` class provides two methods: |
| |
n | |
| .. method:: Sniffer.sniff(sample[,delimiters=None]) |
| .. method:: sniff(sample[, delimiters=None]) |
| |
n | Analyze the given *sample* and return a :class:`Dialect` subclass reflecting the |
n | Analyze the given *sample* and return a :class:`Dialect` subclass |
| parameters found. If the optional *delimiters* parameter is given, it is |
| reflecting the parameters found. If the optional *delimiters* parameter |
| interpreted as a string containing possible valid delimiter characters. |
| is given, it is interpreted as a string containing possible valid |
| delimiter characters. |
| |
| |
n | .. method:: Sniffer.has_header(sample) |
n | .. method:: has_header(sample) |
| |
n | Analyze the sample text (presumed to be in CSV format) and return :const:`True` |
n | Analyze the sample text (presumed to be in CSV format) and return |
| if the first row appears to be a series of column headers. |
| :const:`True` if the first row appears to be a series of column headers. |
| |
| 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 ... |
| |
| |
| The :mod:`csv` module defines the following constants: |
n | |
| |
| .. data:: QUOTE_ALL |
| |
| Instructs :class:`writer` objects to quote all fields. |
| |
| |
| .. data:: QUOTE_MINIMAL |
| |
| |
| Reader Objects |
| -------------- |
| |
| Reader objects (:class:`DictReader` instances and objects returned by the |
| :func:`reader` function) have the following public methods: |
| |
| |
n | .. method:: csv reader.next() |
n | .. method:: csvreader.next() |
| |
| Return the next row of the reader's iterable object as a list, parsed according |
| to the current dialect. |
| |
| Reader objects have the following public attributes: |
| |
| |
n | .. attribute:: csv reader.dialect |
n | .. attribute:: csvreader.dialect |
| |
| A read-only description of the dialect in use by the parser. |
| |
| |
n | .. attribute:: csv reader.line_num |
n | .. attribute:: csvreader.line_num |
| |
| The number of lines read from the source iterator. This is not the same as the |
| number of records returned, as records can span multiple lines. |
n | |
| .. versionadded:: 2.5 |
| |
| |
| DictReader objects have the following public attribute: |
| |
| |
| .. attribute:: csvreader.fieldnames |
| |
| If not passed as a parameter when creating the object, this attribute is |
| initialized upon first access or when the first record is read from the |
| file. |
| |
| .. versionchanged:: 2.6 |
| |
| |
| Writer Objects |
| -------------- |
| |
| :class:`Writer` objects (:class:`DictWriter` instances and objects returned by |
| the :func:`writer` function) have the following public methods. A *row* must be |
| a sequence of strings or numbers for :class:`Writer` objects and a dictionary |
| mapping fieldnames to strings or numbers (by passing them through :func:`str` |
| first) for :class:`DictWriter` objects. Note that complex numbers are written |
| out surrounded by parens. This may cause some problems for other programs which |
| read CSV files (assuming they support complex numbers at all). |
| |
| |
n | .. method:: csv writer.writerow(row) |
n | .. method:: csvwriter.writerow(row) |
| |
| Write the *row* parameter to the writer's file object, formatted according to |
| the current dialect. |
| |
| |
n | .. method:: csv writer.writerows(rows) |
n | .. method:: csvwriter.writerows(rows) |
| |
| Write all the *rows* parameters (a list of *row* objects as described above) to |
| the writer's file object, formatted according to the current dialect. |
| |
| Writer objects have the following public attribute: |
| |
| |
n | .. attribute:: csv writer.dialect |
n | .. attribute:: csvwriter.dialect |
| |
| A read-only description of the dialect in use by the writer. |
| |
| |
| .. _csv-examples: |
| |
| Examples |
| -------- |