mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2025-10-28 08:21:57 -06:00
957 lines
90 KiB
HTML
957 lines
90 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="csv — CSV File Reading and Writing" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/library/csv.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="Source code: Lib/csv.py 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 att..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="Source code: Lib/csv.py 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 att..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>csv — CSV File Reading and Writing — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 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="canonical" href="https://docs.python.org/3/library/csv.html">
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
|
||
<input type="submit" value="Go"/>
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<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>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="fileformats.html"
|
||
title="previous chapter">File Formats</a></p>
|
||
</div>
|
||
<div>
|
||
<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>
|
||
<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/main/Doc/library/csv.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<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.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 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="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-csv">
|
||
<span id="csv-csv-file-reading-and-writing"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing<a class="headerlink" href="#module-csv" title="Link to this heading">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/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://datatracker.ietf.org/doc/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://peps.python.org/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>
|
||
<section id="module-contents">
|
||
<span id="csv-contents"></span><h2>Module Contents<a class="headerlink" href="#module-contents" title="Link to this heading">¶</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>
|
||
<dl class="py function" id="index-3">
|
||
<dt class="sig sig-object py" id="csv.reader">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">reader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">csvfile</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'excel'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">fmtparams</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.reader" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a <a class="reference internal" href="#reader-objects"><span class="std std-ref">reader object</span></a> that will process
|
||
lines from the given <em>csvfile</em>. A csvfile must be an iterable of
|
||
strings, each in the reader’s defined csv format.
|
||
A csvfile is most commonly a file-like object or list.
|
||
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="#id4" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></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="w"> </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="py function">
|
||
<dt class="sig sig-object py" id="csv.writer">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">writer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">csvfile</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'excel'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">fmtparams</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.writer" title="Link 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
|
||
<a class="reference internal" href="io.html#io.TextIOBase.write" title="io.TextIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> 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="#id4" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></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 dialects and formatting parameters, see
|
||
the <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a> section. 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="w"> </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="py function">
|
||
<dt class="sig sig-object py" id="csv.register_dialect">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">register_dialect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">**fmtparams</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.register_dialect" title="Link 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 dialects 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="py function">
|
||
<dt class="sig sig-object py" id="csv.unregister_dialect">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">unregister_dialect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.unregister_dialect" title="Link 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="py function">
|
||
<dt class="sig sig-object py" id="csv.get_dialect">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">get_dialect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.get_dialect" title="Link 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="py function">
|
||
<dt class="sig sig-object py" id="csv.list_dialects">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">list_dialects</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.list_dialects" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return the names of all registered dialects.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py function">
|
||
<dt class="sig sig-object py" id="csv.field_size_limit">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">field_size_limit</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">new_limit</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.field_size_limit" title="Link 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="py class">
|
||
<dt class="sig sig-object py" id="csv.DictReader">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">DictReader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fieldnames</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">restkey</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">restval</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'excel'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwds</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.DictReader" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Create an object that operates like a regular reader but maps the
|
||
information in each row to a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</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 and will be omitted from the results. If
|
||
<em>fieldnames</em> is provided, they will be used and the first row will be
|
||
included in the results. Regardless of how the fieldnames are determined,
|
||
the 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 the value of <em>restval</em> (which defaults
|
||
to <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>
|
||
<p>If the argument passed to <em>fieldnames</em> is an iterator, it will be coerced to a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>.</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>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span>Returned rows are now of type <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a>.</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="w"> </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">{'first_name': 'John', 'last_name': 'Cleese'}</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="csv.DictWriter">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">DictWriter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fieldnames</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">restval</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extrasaction</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'raise'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'excel'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwds</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.DictWriter" title="Link 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 <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code></a> 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 <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code></a> 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>If the argument passed to <em>fieldnames</em> is an iterator, it will be coerced to a <a class="reference internal" href="stdtypes.html#list" title="list"><code class="xref py py-class docutils literal notranslate"><span class="pre">list</span></code></a>.</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="w"> </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="py class">
|
||
<dt class="sig sig-object py" id="csv.Dialect">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">Dialect</span></span><a class="headerlink" href="#csv.Dialect" title="Link 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 whose attributes contain
|
||
information for how to handle doublequotes, whitespace, delimiters, etc.
|
||
Due to the lack of a strict CSV specification, different applications
|
||
produce subtly different CSV data. <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> instances define how
|
||
<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> instances behave.</p>
|
||
<p>All available <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> names are returned by <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>,
|
||
and they can be registered with 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> 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>
|
||
classes through their initializer (<code class="docutils literal notranslate"><span class="pre">__init__</span></code>) functions like this:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">csv</span>
|
||
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'students.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">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">csvfile</span><span class="p">,</span> <span class="n">dialect</span><span class="o">=</span><span class="s1">'unix'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="csv.excel">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">excel</span></span><a class="headerlink" href="#csv.excel" title="Link 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="py class">
|
||
<dt class="sig sig-object py" id="csv.excel_tab">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">excel_tab</span></span><a class="headerlink" href="#csv.excel_tab" title="Link 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="py class">
|
||
<dt class="sig sig-object py" id="csv.unix_dialect">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">unix_dialect</span></span><a class="headerlink" href="#csv.unix_dialect" title="Link 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">Added in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="csv.Sniffer">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">Sniffer</span></span><a class="headerlink" href="#csv.Sniffer" title="Link 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="py method">
|
||
<dt class="sig sig-object py" id="csv.Sniffer.sniff">
|
||
<span class="sig-name descname"><span class="pre">sniff</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sample</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">delimiters</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.Sniffer.sniff" title="Link 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="py method">
|
||
<dt class="sig sig-object py" id="csv.Sniffer.has_header">
|
||
<span class="sig-name descname"><span class="pre">has_header</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sample</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.Sniffer.has_header" title="Link 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.
|
||
Inspecting each column, one of two key criteria will be considered to
|
||
estimate if the sample contains a header:</p>
|
||
<ul class="simple">
|
||
<li><p>the second through n-th rows contain numeric values</p></li>
|
||
<li><p>the second through n-th rows contain strings where at least one value’s
|
||
length differs from that of the putative header of that column.</p></li>
|
||
</ul>
|
||
<p>Twenty rows after the first row are sampled; if more than half of columns +
|
||
rows meet the criteria, <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> is returned.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This method is a rough heuristic and may produce both false positives and
|
||
negatives.</p>
|
||
</div>
|
||
</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 id="csv-constants">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="py data">
|
||
<dt class="sig sig-object py" id="csv.QUOTE_ALL">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">QUOTE_ALL</span></span><a class="headerlink" href="#csv.QUOTE_ALL" title="Link 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="py data">
|
||
<dt class="sig sig-object py" id="csv.QUOTE_MINIMAL">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">QUOTE_MINIMAL</span></span><a class="headerlink" href="#csv.QUOTE_MINIMAL" title="Link 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="py data">
|
||
<dt class="sig sig-object py" id="csv.QUOTE_NONNUMERIC">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">QUOTE_NONNUMERIC</span></span><a class="headerlink" href="#csv.QUOTE_NONNUMERIC" title="Link 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 <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> objects to convert all non-quoted fields to type <em>float</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="csv.QUOTE_NONE">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">QUOTE_NONE</span></span><a class="headerlink" href="#csv.QUOTE_NONE" title="Link 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> objects to perform no special processing of quote characters.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="csv.QUOTE_NOTNULL">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">QUOTE_NOTNULL</span></span><a class="headerlink" href="#csv.QUOTE_NOTNULL" title="Link 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 which are not
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>. This is similar to <a class="reference internal" href="#csv.QUOTE_ALL" title="csv.QUOTE_ALL"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_ALL</span></code></a>, except that if a
|
||
field value is <code class="docutils literal notranslate"><span class="pre">None</span></code> an empty (unquoted) string is written.</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> objects to interpret an empty (unquoted) field
|
||
as <code class="docutils literal notranslate"><span class="pre">None</span></code> and to otherwise behave as <a class="reference internal" href="#csv.QUOTE_ALL" title="csv.QUOTE_ALL"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_ALL</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.12.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="csv.QUOTE_STRINGS">
|
||
<span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">QUOTE_STRINGS</span></span><a class="headerlink" href="#csv.QUOTE_STRINGS" title="Link 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 always place quotes around fields
|
||
which are strings. This is similar to <a class="reference internal" href="#csv.QUOTE_NONNUMERIC" title="csv.QUOTE_NONNUMERIC"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code></a>, except that if a
|
||
field value is <code class="docutils literal notranslate"><span class="pre">None</span></code> an empty (unquoted) string is written.</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> objects to interpret an empty (unquoted) string as <code class="docutils literal notranslate"><span class="pre">None</span></code> and
|
||
to otherwise behave as <a class="reference internal" href="#csv.QUOTE_NONNUMERIC" title="csv.QUOTE_NONNUMERIC"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.12.</span></p>
|
||
</div>
|
||
</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="py exception">
|
||
<dt class="sig sig-object py" id="csv.Error">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">Error</span></span><a class="headerlink" href="#csv.Error" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Raised by any of the functions when an error is detected.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<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="Link to this heading">¶</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 containing various attributes
|
||
describing the format of the CSV file. 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.delimiter">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">delimiter</span></span><a class="headerlink" href="#csv.Dialect.delimiter" title="Link 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.doublequote">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">doublequote</span></span><a class="headerlink" href="#csv.Dialect.doublequote" title="Link 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.escapechar">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">escapechar</span></span><a class="headerlink" href="#csv.Dialect.escapechar" title="Link 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>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>An empty <em>escapechar</em> is not allowed.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.lineterminator">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">lineterminator</span></span><a class="headerlink" href="#csv.Dialect.lineterminator" title="Link 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.quotechar">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">quotechar</span></span><a class="headerlink" href="#csv.Dialect.quotechar" title="Link 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>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.11: </span>An empty <em>quotechar</em> is not allowed.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.quoting">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">quoting</span></span><a class="headerlink" href="#csv.Dialect.quoting" title="Link 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 <a class="reference internal" href="#csv-constants"><span class="std std-ref">QUOTE_* constants</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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.skipinitialspace">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">skipinitialspace</span></span><a class="headerlink" href="#csv.Dialect.skipinitialspace" title="Link 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>, spaces immediately following the <em>delimiter</em> are 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.Dialect.strict">
|
||
<span class="sig-prename descclassname"><span class="pre">Dialect.</span></span><span class="sig-name descname"><span class="pre">strict</span></span><a class="headerlink" href="#csv.Dialect.strict" title="Link 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>
|
||
|
||
</section>
|
||
<section id="reader-objects">
|
||
<span id="id3"></span><h2>Reader Objects<a class="headerlink" href="#reader-objects" title="Link to this heading">¶</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="py method">
|
||
<dt class="sig sig-object py" id="csv.csvreader.__next__">
|
||
<span class="sig-prename descclassname"><span class="pre">csvreader.</span></span><span class="sig-name descname"><span class="pre">__next__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvreader.__next__" title="Link 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 <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>. 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.csvreader.dialect">
|
||
<span class="sig-prename descclassname"><span class="pre">csvreader.</span></span><span class="sig-name descname"><span class="pre">dialect</span></span><a class="headerlink" href="#csv.csvreader.dialect" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A read-only description of the dialect in use by the parser.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="csv.csvreader.line_num">
|
||
<span class="sig-prename descclassname"><span class="pre">csvreader.</span></span><span class="sig-name descname"><span class="pre">line_num</span></span><a class="headerlink" href="#csv.csvreader.line_num" title="Link 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.DictReader.fieldnames">
|
||
<span class="sig-prename descclassname"><span class="pre">DictReader.</span></span><span class="sig-name descname"><span class="pre">fieldnames</span></span><a class="headerlink" href="#csv.DictReader.fieldnames" title="Link 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>
|
||
|
||
</section>
|
||
<section id="writer-objects">
|
||
<h2>Writer Objects<a class="headerlink" href="#writer-objects" title="Link to this heading">¶</a></h2>
|
||
<p><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 (<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 <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 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="py method">
|
||
<dt class="sig sig-object py" id="csv.csvwriter.writerow">
|
||
<span class="sig-prename descclassname"><span class="pre">csvwriter.</span></span><span class="sig-name descname"><span class="pre">writerow</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">row</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerow" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Write the <em>row</em> parameter to the writer’s file object, formatted according
|
||
to the current <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>. Return the return value of the call to the
|
||
<em>write</em> method of the underlying file object.</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="py method">
|
||
<dt class="sig sig-object py" id="csv.csvwriter.writerows">
|
||
<span class="sig-prename descclassname"><span class="pre">csvwriter.</span></span><span class="sig-name descname"><span class="pre">writerows</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">rows</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerows" title="Link 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="py attribute">
|
||
<dt class="sig sig-object py" id="csv.csvwriter.dialect">
|
||
<span class="sig-prename descclassname"><span class="pre">csvwriter.</span></span><span class="sig-name descname"><span class="pre">dialect</span></span><a class="headerlink" href="#csv.csvwriter.dialect" title="Link 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="py method">
|
||
<dt class="sig sig-object py" id="csv.DictWriter.writeheader">
|
||
<span class="sig-prename descclassname"><span class="pre">DictWriter.</span></span><span class="sig-name descname"><span class="pre">writeheader</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.DictWriter.writeheader" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Write a row with the field names (as specified in the constructor) to
|
||
the writer’s file object, formatted according to the current dialect. Return
|
||
the return value of the <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">csvwriter.writerow()</span></code></a> call used internally.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span><a class="reference internal" href="#csv.DictWriter.writeheader" title="csv.DictWriter.writeheader"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writeheader()</span></code></a> now also returns the value returned by
|
||
the <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">csvwriter.writerow()</span></code></a> method it uses internally.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="examples">
|
||
<span id="csv-examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</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="w"> </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="w"> </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="w"> </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.getencoding" title="locale.getencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getencoding()</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="w"> </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="w"> </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="w"> </span><span class="nn">csv</span><span class="o">,</span><span class="w"> </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="w"> </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>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id4" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
|
||
<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>)</span>
|
||
<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>
|
||
</aside>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<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>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="fileformats.html"
|
||
title="previous chapter">File Formats</a></p>
|
||
</div>
|
||
<div>
|
||
<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>
|
||
<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/main/Doc/library/csv.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<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.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 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="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
©
|
||
<a href="../copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |