735 lines
67 KiB
HTML
735 lines
67 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>csv — CSV File Reading and Writing — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="configparser — Configuration file parser" href="configparser.html" />
|
||
<link rel="prev" title="File Formats" href="fileformats.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/csv.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="configparser.html" title="configparser — Configuration file parser"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="fileformats.html" title="File Formats"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">File Formats</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-csv">
|
||
<span id="csv-csv-file-reading-and-writing"></span><h1><a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> — CSV File Reading and Writing<a class="headerlink" href="#module-csv" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/csv.py">Lib/csv.py</a></p>
|
||
<hr class="docutils" id="index-0" />
|
||
<p>The so-called CSV (Comma Separated Values) format is the most common import and
|
||
export format for spreadsheets and databases. CSV format was used for many
|
||
years prior to attempts to describe the format in a standardized way in
|
||
<span class="target" id="index-1"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc4180.html"><strong>RFC 4180</strong></a>. The lack of a well-defined standard means that subtle differences
|
||
often exist in the data produced and consumed by different applications. These
|
||
differences can make it annoying to process CSV files from multiple sources.
|
||
Still, while the delimiters and quoting characters vary, the overall format is
|
||
similar enough that it is possible to write a single module which can
|
||
efficiently manipulate such data, hiding the details of reading and writing the
|
||
data from the programmer.</p>
|
||
<p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module implements classes to read and write tabular data in CSV
|
||
format. It allows programmers to say, “write this data in the format preferred
|
||
by Excel,” or “read data from this file which was generated by Excel,” without
|
||
knowing the precise details of the CSV format used by Excel. Programmers can
|
||
also describe the CSV formats understood by other applications or define their
|
||
own special-purpose CSV formats.</p>
|
||
<p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module’s <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> and <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects read and
|
||
write sequences. Programmers can also read and write data in dictionary form
|
||
using the <a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a> and <a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> classes.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><span class="target" id="index-2"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0305"><strong>PEP 305</strong></a> - CSV File API</dt><dd><p>The Python Enhancement Proposal which proposed this addition to Python.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="module-contents">
|
||
<span id="csv-contents"></span><h2>Module Contents<a class="headerlink" href="#module-contents" title="Permalink to this headline">¶</a></h2>
|
||
<p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following functions:</p>
|
||
<span class="target" id="index-3"></span><dl class="function">
|
||
<dt id="csv.reader">
|
||
<code class="descclassname">csv.</code><code class="descname">reader</code><span class="sig-paren">(</span><em>csvfile</em>, <em>dialect='excel'</em>, <em>**fmtparams</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.reader" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a reader object which will iterate over lines in the given <em>csvfile</em>.
|
||
<em>csvfile</em> can be any object which supports the <a class="reference internal" href="../glossary.html#term-iterator"><span class="xref std std-term">iterator</span></a> protocol and returns a
|
||
string each time its <code class="xref py py-meth docutils literal notranslate"><span class="pre">__next__()</span></code> method is called — <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file objects</span></a> and list objects are both suitable. If <em>csvfile</em> is a file object,
|
||
it should be opened with <code class="docutils literal notranslate"><span class="pre">newline=''</span></code>. <a class="footnote-reference brackets" href="#id3" id="id1">1</a> An optional
|
||
<em>dialect</em> 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 <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class or one of the strings returned by the
|
||
<a class="reference internal" href="#csv.list_dialects" title="csv.list_dialects"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_dialects()</span></code></a> function. The other optional <em>fmtparams</em> keyword arguments
|
||
can be given to override individual formatting parameters in the current
|
||
dialect. For full details about the dialect and formatting parameters, see
|
||
section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>.</p>
|
||
<p>Each row read from the csv file is returned as a list of strings. No
|
||
automatic data type conversion is performed unless the <code class="docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code> format
|
||
option is specified (in which case unquoted fields are transformed into floats).</p>
|
||
<p>A short usage example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'eggs.csv'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">spamreader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">csvfile</span><span class="p">,</span> <span class="n">delimiter</span><span class="o">=</span><span class="s1">' '</span><span class="p">,</span> <span class="n">quotechar</span><span class="o">=</span><span class="s1">'|'</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">spamreader</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s1">', '</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">row</span><span class="p">))</span>
|
||
<span class="go">Spam, Spam, Spam, Spam, Spam, Baked Beans</span>
|
||
<span class="go">Spam, Lovely Spam, Wonderful Spam</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="csv.writer">
|
||
<code class="descclassname">csv.</code><code class="descname">writer</code><span class="sig-paren">(</span><em>csvfile</em>, <em>dialect='excel'</em>, <em>**fmtparams</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.writer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a writer object responsible for converting the user’s data into delimited
|
||
strings on the given file-like object. <em>csvfile</em> can be any object with a
|
||
<code class="xref py py-func docutils literal notranslate"><span class="pre">write()</span></code> method. If <em>csvfile</em> is a file object, it should be opened with
|
||
<code class="docutils literal notranslate"><span class="pre">newline=''</span></code> <a class="footnote-reference brackets" href="#id3" id="id2">1</a>. An optional <em>dialect</em>
|
||
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
|
||
<a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class or one of the strings returned by the
|
||
<a class="reference internal" href="#csv.list_dialects" title="csv.list_dialects"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_dialects()</span></code></a> function. The other optional <em>fmtparams</em> keyword arguments
|
||
can be given to override individual formatting parameters in the current
|
||
dialect. For full details about the dialect and formatting parameters, see
|
||
section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>. To make it
|
||
as easy as possible to interface with modules which implement the DB API, the
|
||
value <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> is written as the empty string. While this isn’t a
|
||
reversible transformation, it makes it easier to dump SQL NULL data values to
|
||
CSV files without preprocessing the data returned from a <code class="docutils literal notranslate"><span class="pre">cursor.fetch*</span></code> call.
|
||
All other non-string data are stringified with <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> before being written.</p>
|
||
<p>A short usage example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'eggs.csv'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>
|
||
<span class="n">spamwriter</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">writer</span><span class="p">(</span><span class="n">csvfile</span><span class="p">,</span> <span class="n">delimiter</span><span class="o">=</span><span class="s1">' '</span><span class="p">,</span>
|
||
<span class="n">quotechar</span><span class="o">=</span><span class="s1">'|'</span><span class="p">,</span> <span class="n">quoting</span><span class="o">=</span><span class="n">csv</span><span class="o">.</span><span class="n">QUOTE_MINIMAL</span><span class="p">)</span>
|
||
<span class="n">spamwriter</span><span class="o">.</span><span class="n">writerow</span><span class="p">([</span><span class="s1">'Spam'</span><span class="p">]</span> <span class="o">*</span> <span class="mi">5</span> <span class="o">+</span> <span class="p">[</span><span class="s1">'Baked Beans'</span><span class="p">])</span>
|
||
<span class="n">spamwriter</span><span class="o">.</span><span class="n">writerow</span><span class="p">([</span><span class="s1">'Spam'</span><span class="p">,</span> <span class="s1">'Lovely Spam'</span><span class="p">,</span> <span class="s1">'Wonderful Spam'</span><span class="p">])</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="csv.register_dialect">
|
||
<code class="descclassname">csv.</code><code class="descname">register_dialect</code><span class="sig-paren">(</span><em>name</em><span class="optional">[</span>, <em>dialect</em><span class="optional">[</span>, <em>**fmtparams</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.register_dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Associate <em>dialect</em> with <em>name</em>. <em>name</em> must be a string. The
|
||
dialect can be specified either by passing a sub-class of <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a>, or
|
||
by <em>fmtparams</em> keyword arguments, or both, with keyword arguments overriding
|
||
parameters of the dialect. For full details about the dialect and formatting
|
||
parameters, see section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="csv.unregister_dialect">
|
||
<code class="descclassname">csv.</code><code class="descname">unregister_dialect</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.unregister_dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Delete the dialect associated with <em>name</em> from the dialect registry. An
|
||
<a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> is raised if <em>name</em> is not a registered dialect name.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="csv.get_dialect">
|
||
<code class="descclassname">csv.</code><code class="descname">get_dialect</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.get_dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the dialect associated with <em>name</em>. An <a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> is raised if
|
||
<em>name</em> is not a registered dialect name. This function returns an immutable
|
||
<a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="csv.list_dialects">
|
||
<code class="descclassname">csv.</code><code class="descname">list_dialects</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.list_dialects" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the names of all registered dialects.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="csv.field_size_limit">
|
||
<code class="descclassname">csv.</code><code class="descname">field_size_limit</code><span class="sig-paren">(</span><span class="optional">[</span><em>new_limit</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.field_size_limit" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Returns the current maximum field size allowed by the parser. If <em>new_limit</em> is
|
||
given, this becomes the new limit.</p>
|
||
</dd></dl>
|
||
|
||
<p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following classes:</p>
|
||
<dl class="class">
|
||
<dt id="csv.DictReader">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">DictReader</code><span class="sig-paren">(</span><em>f</em>, <em>fieldnames=None</em>, <em>restkey=None</em>, <em>restval=None</em>, <em>dialect='excel'</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.DictReader" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create an object that operates like a regular reader but maps the
|
||
information in each row to an <a class="reference internal" href="collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-mod docutils literal notranslate"><span class="pre">OrderedDict</span></code></a>
|
||
whose keys are given by the optional <em>fieldnames</em> parameter.</p>
|
||
<p>The <em>fieldnames</em> parameter is a <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequence</span></a>. If <em>fieldnames</em> is
|
||
omitted, the values in the first row of file <em>f</em> will be used as the
|
||
fieldnames. Regardless of how the fieldnames are determined, the ordered
|
||
dictionary preserves their original ordering.</p>
|
||
<p>If a row has more fields than fieldnames, the remaining data is put in a
|
||
list and stored with the fieldname specified by <em>restkey</em> (which defaults
|
||
to <code class="docutils literal notranslate"><span class="pre">None</span></code>). If a non-blank row has fewer fields than fieldnames, the
|
||
missing values are filled-in with <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
<p>All other optional or keyword arguments are passed to the underlying
|
||
<a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> instance.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6: </span>Returned rows are now of type <code class="xref py py-class docutils literal notranslate"><span class="pre">OrderedDict</span></code>.</p>
|
||
</div>
|
||
<p>A short usage example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'names.csv'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">DictReader</span><span class="p">(</span><span class="n">csvfile</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">[</span><span class="s1">'first_name'</span><span class="p">],</span> <span class="n">row</span><span class="p">[</span><span class="s1">'last_name'</span><span class="p">])</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">Eric Idle</span>
|
||
<span class="go">John Cleese</span>
|
||
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||
<span class="go">OrderedDict([('first_name', 'John'), ('last_name', 'Cleese')])</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="csv.DictWriter">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">DictWriter</code><span class="sig-paren">(</span><em>f</em>, <em>fieldnames</em>, <em>restval=''</em>, <em>extrasaction='raise'</em>, <em>dialect='excel'</em>, <em>*args</em>, <em>**kwds</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.DictWriter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Create an object which operates like a regular writer but maps dictionaries
|
||
onto output rows. The <em>fieldnames</em> parameter is a <a class="reference internal" href="collections.abc.html#module-collections.abc" title="collections.abc: Abstract base classes for containers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sequence</span></code></a> of keys that identify the order in which values in the
|
||
dictionary passed to the <code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code> method are written to file
|
||
<em>f</em>. The optional <em>restval</em> parameter specifies the value to be
|
||
written if the dictionary is missing a key in <em>fieldnames</em>. If the
|
||
dictionary passed to the <code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code> method contains a key not found in
|
||
<em>fieldnames</em>, the optional <em>extrasaction</em> parameter indicates what action to
|
||
take.
|
||
If it is set to <code class="docutils literal notranslate"><span class="pre">'raise'</span></code>, the default value, a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
|
||
is raised.
|
||
If it is set to <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code>, extra values in the dictionary are ignored.
|
||
Any other optional or keyword arguments are passed to the underlying
|
||
<a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> instance.</p>
|
||
<p>Note that unlike the <a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a> class, the <em>fieldnames</em> parameter
|
||
of the <a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> class is not optional.</p>
|
||
<p>A short usage example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'names.csv'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>
|
||
<span class="n">fieldnames</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'first_name'</span><span class="p">,</span> <span class="s1">'last_name'</span><span class="p">]</span>
|
||
<span class="n">writer</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">DictWriter</span><span class="p">(</span><span class="n">csvfile</span><span class="p">,</span> <span class="n">fieldnames</span><span class="o">=</span><span class="n">fieldnames</span><span class="p">)</span>
|
||
|
||
<span class="n">writer</span><span class="o">.</span><span class="n">writeheader</span><span class="p">()</span>
|
||
<span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">({</span><span class="s1">'first_name'</span><span class="p">:</span> <span class="s1">'Baked'</span><span class="p">,</span> <span class="s1">'last_name'</span><span class="p">:</span> <span class="s1">'Beans'</span><span class="p">})</span>
|
||
<span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">({</span><span class="s1">'first_name'</span><span class="p">:</span> <span class="s1">'Lovely'</span><span class="p">,</span> <span class="s1">'last_name'</span><span class="p">:</span> <span class="s1">'Spam'</span><span class="p">})</span>
|
||
<span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">({</span><span class="s1">'first_name'</span><span class="p">:</span> <span class="s1">'Wonderful'</span><span class="p">,</span> <span class="s1">'last_name'</span><span class="p">:</span> <span class="s1">'Spam'</span><span class="p">})</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="csv.Dialect">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">Dialect</code><a class="headerlink" href="#csv.Dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class is a container class relied on primarily for its
|
||
attributes, which are used to define the parameters for a specific
|
||
<a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> or <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> instance.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="csv.excel">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">excel</code><a class="headerlink" href="#csv.excel" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <a class="reference internal" href="#csv.excel" title="csv.excel"><code class="xref py py-class docutils literal notranslate"><span class="pre">excel</span></code></a> class defines the usual properties of an Excel-generated CSV
|
||
file. It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'excel'</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="csv.excel_tab">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">excel_tab</code><a class="headerlink" href="#csv.excel_tab" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <a class="reference internal" href="#csv.excel_tab" title="csv.excel_tab"><code class="xref py py-class docutils literal notranslate"><span class="pre">excel_tab</span></code></a> class defines the usual properties of an Excel-generated
|
||
TAB-delimited file. It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'excel-tab'</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="csv.unix_dialect">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">unix_dialect</code><a class="headerlink" href="#csv.unix_dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <a class="reference internal" href="#csv.unix_dialect" title="csv.unix_dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">unix_dialect</span></code></a> class defines the usual properties of a CSV file
|
||
generated on UNIX systems, i.e. using <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> as line terminator and quoting
|
||
all fields. It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'unix'</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="csv.Sniffer">
|
||
<em class="property">class </em><code class="descclassname">csv.</code><code class="descname">Sniffer</code><a class="headerlink" href="#csv.Sniffer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The <a class="reference internal" href="#csv.Sniffer" title="csv.Sniffer"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code></a> class is used to deduce the format of a CSV file.</p>
|
||
<p>The <a class="reference internal" href="#csv.Sniffer" title="csv.Sniffer"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code></a> class provides two methods:</p>
|
||
<dl class="method">
|
||
<dt id="csv.Sniffer.sniff">
|
||
<code class="descname">sniff</code><span class="sig-paren">(</span><em>sample</em>, <em>delimiters=None</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.Sniffer.sniff" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Analyze the given <em>sample</em> and return a <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> subclass
|
||
reflecting the parameters found. If the optional <em>delimiters</em> parameter
|
||
is given, it is interpreted as a string containing possible valid
|
||
delimiter characters.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="csv.Sniffer.has_header">
|
||
<code class="descname">has_header</code><span class="sig-paren">(</span><em>sample</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.Sniffer.has_header" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Analyze the sample text (presumed to be in CSV format) and return
|
||
<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a> if the first row appears to be a series of column headers.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<p>An example for <a class="reference internal" href="#csv.Sniffer" title="csv.Sniffer"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code></a> use:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'example.csv'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>
|
||
<span class="n">dialect</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">Sniffer</span><span class="p">()</span><span class="o">.</span><span class="n">sniff</span><span class="p">(</span><span class="n">csvfile</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="mi">1024</span><span class="p">))</span>
|
||
<span class="n">csvfile</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||
<span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">csvfile</span><span class="p">,</span> <span class="n">dialect</span><span class="p">)</span>
|
||
<span class="c1"># ... process CSV file contents here ...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following constants:</p>
|
||
<dl class="data">
|
||
<dt id="csv.QUOTE_ALL">
|
||
<code class="descclassname">csv.</code><code class="descname">QUOTE_ALL</code><a class="headerlink" href="#csv.QUOTE_ALL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to quote all fields.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="csv.QUOTE_MINIMAL">
|
||
<code class="descclassname">csv.</code><code class="descname">QUOTE_MINIMAL</code><a class="headerlink" href="#csv.QUOTE_MINIMAL" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to only quote those fields which contain
|
||
special characters such as <em>delimiter</em>, <em>quotechar</em> or any of the characters in
|
||
<em>lineterminator</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="csv.QUOTE_NONNUMERIC">
|
||
<code class="descclassname">csv.</code><code class="descname">QUOTE_NONNUMERIC</code><a class="headerlink" href="#csv.QUOTE_NONNUMERIC" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to quote all non-numeric fields.</p>
|
||
<p>Instructs the reader to convert all non-quoted fields to type <em>float</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="csv.QUOTE_NONE">
|
||
<code class="descclassname">csv.</code><code class="descname">QUOTE_NONE</code><a class="headerlink" href="#csv.QUOTE_NONE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to never quote fields. When the current
|
||
<em>delimiter</em> occurs in output data it is preceded by the current <em>escapechar</em>
|
||
character. If <em>escapechar</em> is not set, the writer will raise <a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> if
|
||
any characters that require escaping are encountered.</p>
|
||
<p>Instructs <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> to perform no special processing of quote characters.</p>
|
||
</dd></dl>
|
||
|
||
<p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following exception:</p>
|
||
<dl class="exception">
|
||
<dt id="csv.Error">
|
||
<em class="property">exception </em><code class="descclassname">csv.</code><code class="descname">Error</code><a class="headerlink" href="#csv.Error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Raised by any of the functions when an error is detected.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="dialects-and-formatting-parameters">
|
||
<span id="csv-fmt-params"></span><h2>Dialects and Formatting Parameters<a class="headerlink" href="#dialects-and-formatting-parameters" title="Permalink to this headline">¶</a></h2>
|
||
<p>To make it easier to specify the format of input and output records, specific
|
||
formatting parameters are grouped together into dialects. A dialect is a
|
||
subclass of the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class having a set of specific methods and a
|
||
single <code class="xref py py-meth docutils literal notranslate"><span class="pre">validate()</span></code> method. When creating <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> or
|
||
<a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects, the programmer can specify a string or a subclass of
|
||
the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class as the dialect parameter. In addition to, or instead
|
||
of, the <em>dialect</em> parameter, the programmer can also specify individual
|
||
formatting parameters, which have the same names as the attributes defined below
|
||
for the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class.</p>
|
||
<p>Dialects support the following attributes:</p>
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.delimiter">
|
||
<code class="descclassname">Dialect.</code><code class="descname">delimiter</code><a class="headerlink" href="#csv.Dialect.delimiter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A one-character string used to separate fields. It defaults to <code class="docutils literal notranslate"><span class="pre">','</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.doublequote">
|
||
<code class="descclassname">Dialect.</code><code class="descname">doublequote</code><a class="headerlink" href="#csv.Dialect.doublequote" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Controls how instances of <em>quotechar</em> appearing inside a field should
|
||
themselves be quoted. When <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, the character is doubled. When
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, the <em>escapechar</em> is used as a prefix to the <em>quotechar</em>. It
|
||
defaults to <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>.</p>
|
||
<p>On output, if <em>doublequote</em> is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a> and no <em>escapechar</em> is set,
|
||
<a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> is raised if a <em>quotechar</em> is found in a field.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.escapechar">
|
||
<code class="descclassname">Dialect.</code><code class="descname">escapechar</code><a class="headerlink" href="#csv.Dialect.escapechar" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A one-character string used by the writer to escape the <em>delimiter</em> if <em>quoting</em>
|
||
is set to <a class="reference internal" href="#csv.QUOTE_NONE" title="csv.QUOTE_NONE"><code class="xref py py-const docutils literal notranslate"><span class="pre">QUOTE_NONE</span></code></a> and the <em>quotechar</em> if <em>doublequote</em> is
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>. On reading, the <em>escapechar</em> removes any special meaning from
|
||
the following character. It defaults to <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>, which disables escaping.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.lineterminator">
|
||
<code class="descclassname">Dialect.</code><code class="descname">lineterminator</code><a class="headerlink" href="#csv.Dialect.lineterminator" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The string used to terminate lines produced by the <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a>. It defaults
|
||
to <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> is hard-coded to recognise either <code class="docutils literal notranslate"><span class="pre">'\r'</span></code> or <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> as
|
||
end-of-line, and ignores <em>lineterminator</em>. This behavior may change in the
|
||
future.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.quotechar">
|
||
<code class="descclassname">Dialect.</code><code class="descname">quotechar</code><a class="headerlink" href="#csv.Dialect.quotechar" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A one-character string used to quote fields containing special characters, such
|
||
as the <em>delimiter</em> or <em>quotechar</em>, or which contain new-line characters. It
|
||
defaults to <code class="docutils literal notranslate"><span class="pre">'"'</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.quoting">
|
||
<code class="descclassname">Dialect.</code><code class="descname">quoting</code><a class="headerlink" href="#csv.Dialect.quoting" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Controls when quotes should be generated by the writer and recognised by the
|
||
reader. It can take on any of the <code class="xref py py-const docutils literal notranslate"><span class="pre">QUOTE_*</span></code> constants (see section
|
||
<a class="reference internal" href="#csv-contents"><span class="std std-ref">Module Contents</span></a>) and defaults to <a class="reference internal" href="#csv.QUOTE_MINIMAL" title="csv.QUOTE_MINIMAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">QUOTE_MINIMAL</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.skipinitialspace">
|
||
<code class="descclassname">Dialect.</code><code class="descname">skipinitialspace</code><a class="headerlink" href="#csv.Dialect.skipinitialspace" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>When <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, whitespace immediately following the <em>delimiter</em> is ignored.
|
||
The default is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.Dialect.strict">
|
||
<code class="descclassname">Dialect.</code><code class="descname">strict</code><a class="headerlink" href="#csv.Dialect.strict" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>When <code class="docutils literal notranslate"><span class="pre">True</span></code>, raise exception <a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> on bad CSV input.
|
||
The default is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="reader-objects">
|
||
<h2>Reader Objects<a class="headerlink" href="#reader-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p>Reader objects (<a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a> instances and objects returned by the
|
||
<a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-func docutils literal notranslate"><span class="pre">reader()</span></code></a> function) have the following public methods:</p>
|
||
<dl class="method">
|
||
<dt id="csv.csvreader.__next__">
|
||
<code class="descclassname">csvreader.</code><code class="descname">__next__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvreader.__next__" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the next row of the reader’s iterable object as a list (if the object
|
||
was returned from <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-func docutils literal notranslate"><span class="pre">reader()</span></code></a>) or a dict (if it is a <a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a>
|
||
instance), parsed according to the current dialect. Usually you should call
|
||
this as <code class="docutils literal notranslate"><span class="pre">next(reader)</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<p>Reader objects have the following public attributes:</p>
|
||
<dl class="attribute">
|
||
<dt id="csv.csvreader.dialect">
|
||
<code class="descclassname">csvreader.</code><code class="descname">dialect</code><a class="headerlink" href="#csv.csvreader.dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A read-only description of the dialect in use by the parser.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="csv.csvreader.line_num">
|
||
<code class="descclassname">csvreader.</code><code class="descname">line_num</code><a class="headerlink" href="#csv.csvreader.line_num" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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.</p>
|
||
</dd></dl>
|
||
|
||
<p>DictReader objects have the following public attribute:</p>
|
||
<dl class="attribute">
|
||
<dt id="csv.csvreader.fieldnames">
|
||
<code class="descclassname">csvreader.</code><code class="descname">fieldnames</code><a class="headerlink" href="#csv.csvreader.fieldnames" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="writer-objects">
|
||
<h2>Writer Objects<a class="headerlink" href="#writer-objects" title="Permalink to this headline">¶</a></h2>
|
||
<p><code class="xref py py-class docutils literal notranslate"><span class="pre">Writer</span></code> objects (<a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> instances and objects returned by
|
||
the <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-func docutils literal notranslate"><span class="pre">writer()</span></code></a> function) have the following public methods. A <em>row</em> must be
|
||
an iterable of strings or numbers for <code class="xref py py-class docutils literal notranslate"><span class="pre">Writer</span></code> objects and a dictionary
|
||
mapping fieldnames to strings or numbers (by passing them through <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a>
|
||
first) for <a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> 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).</p>
|
||
<dl class="method">
|
||
<dt id="csv.csvwriter.writerow">
|
||
<code class="descclassname">csvwriter.</code><code class="descname">writerow</code><span class="sig-paren">(</span><em>row</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerow" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the <em>row</em> parameter to the writer’s file object, formatted according to
|
||
the current dialect.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support of arbitrary iterables.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="csv.csvwriter.writerows">
|
||
<code class="descclassname">csvwriter.</code><code class="descname">writerows</code><span class="sig-paren">(</span><em>rows</em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerows" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write all elements in <em>rows</em> (an iterable of <em>row</em> objects as described
|
||
above) to the writer’s file object, formatted according to the current
|
||
dialect.</p>
|
||
</dd></dl>
|
||
|
||
<p>Writer objects have the following public attribute:</p>
|
||
<dl class="attribute">
|
||
<dt id="csv.csvwriter.dialect">
|
||
<code class="descclassname">csvwriter.</code><code class="descname">dialect</code><a class="headerlink" href="#csv.csvwriter.dialect" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A read-only description of the dialect in use by the writer.</p>
|
||
</dd></dl>
|
||
|
||
<p>DictWriter objects have the following public method:</p>
|
||
<dl class="method">
|
||
<dt id="csv.DictWriter.writeheader">
|
||
<code class="descclassname">DictWriter.</code><code class="descname">writeheader</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.DictWriter.writeheader" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write a row with the field names (as specified in the constructor).</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="examples">
|
||
<span id="csv-examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
|
||
<p>The simplest example of reading a CSV file:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'some.csv'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Reading a file with an alternate format:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'passwd'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="n">delimiter</span><span class="o">=</span><span class="s1">':'</span><span class="p">,</span> <span class="n">quoting</span><span class="o">=</span><span class="n">csv</span><span class="o">.</span><span class="n">QUOTE_NONE</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The corresponding simplest possible writing example is:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'some.csv'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">writer</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">writer</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
|
||
<span class="n">writer</span><span class="o">.</span><span class="n">writerows</span><span class="p">(</span><span class="n">someiterable</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Since <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> is used to open a CSV file for reading, the file
|
||
will by default be decoded into unicode using the system default
|
||
encoding (see <a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getpreferredencoding()</span></code></a>). To decode a file
|
||
using a different encoding, use the <code class="docutils literal notranslate"><span class="pre">encoding</span></code> argument of open:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'some.csv'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">'utf-8'</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
|
||
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The same applies to writing in something other than the system default
|
||
encoding: specify the encoding argument when opening the output file.</p>
|
||
<p>Registering a new dialect:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="n">csv</span><span class="o">.</span><span class="n">register_dialect</span><span class="p">(</span><span class="s1">'unixpwd'</span><span class="p">,</span> <span class="n">delimiter</span><span class="o">=</span><span class="s1">':'</span><span class="p">,</span> <span class="n">quoting</span><span class="o">=</span><span class="n">csv</span><span class="o">.</span><span class="n">QUOTE_NONE</span><span class="p">)</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'passwd'</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">f</span><span class="p">,</span> <span class="s1">'unixpwd'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A slightly more advanced use of the reader — catching and reporting errors:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span><span class="o">,</span> <span class="nn">sys</span>
|
||
<span class="n">filename</span> <span class="o">=</span> <span class="s1">'some.csv'</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">''</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
|
||
<span class="n">reader</span> <span class="o">=</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">(</span><span class="n">f</span><span class="p">)</span>
|
||
<span class="k">try</span><span class="p">:</span>
|
||
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="n">csv</span><span class="o">.</span><span class="n">Error</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
|
||
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="s1">'file </span><span class="si">{}</span><span class="s1">, line </span><span class="si">{}</span><span class="s1">: </span><span class="si">{}</span><span class="s1">'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">reader</span><span class="o">.</span><span class="n">line_num</span><span class="p">,</span> <span class="n">e</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>And while the module doesn’t directly support parsing strings, it can easily be
|
||
done:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>
|
||
<span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">csv</span><span class="o">.</span><span class="n">reader</span><span class="p">([</span><span class="s1">'one,two,three'</span><span class="p">]):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="rubric">Footnotes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="id3"><span class="brackets">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a href="#id2">2</a>)</span></dt>
|
||
<dd><p>If <code class="docutils literal notranslate"><span class="pre">newline=''</span></code> is not specified, newlines embedded inside quoted fields
|
||
will not be interpreted correctly, and on platforms that use <code class="docutils literal notranslate"><span class="pre">\r\n</span></code> linendings
|
||
on write an extra <code class="docutils literal notranslate"><span class="pre">\r</span></code> will be added. It should always be safe to specify
|
||
<code class="docutils literal notranslate"><span class="pre">newline=''</span></code>, since the csv module does its own
|
||
(<a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal</span></a>) newline handling.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing</a><ul>
|
||
<li><a class="reference internal" href="#module-contents">Module Contents</a></li>
|
||
<li><a class="reference internal" href="#dialects-and-formatting-parameters">Dialects and Formatting Parameters</a></li>
|
||
<li><a class="reference internal" href="#reader-objects">Reader Objects</a></li>
|
||
<li><a class="reference internal" href="#writer-objects">Writer Objects</a></li>
|
||
<li><a class="reference internal" href="#examples">Examples</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="fileformats.html"
|
||
title="previous chapter">File Formats</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="configparser.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/csv.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="configparser.html" title="configparser — Configuration file parser"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="fileformats.html" title="File Formats"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="fileformats.html" >File Formats</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |