parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="csv — CSV File Reading and Writing" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/csv.html" />10<meta property="og:site_name" content="Python documentation" />11<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..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_csv_aff76666.png" />15<meta property="og:image:alt" 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..." />16<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..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>csv — CSV File Reading and Writing — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="configparser — Configuration file parser" href="configparser.html" />43 <link rel="prev" title="File Formats" href="fileformats.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/csv.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <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>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<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>108<li><a class="reference internal" href="#module-contents">Module Contents</a></li>109<li><a class="reference internal" href="#dialects-and-formatting-parameters">Dialects and Formatting Parameters</a></li>110<li><a class="reference internal" href="#reader-objects">Reader Objects</a></li>111<li><a class="reference internal" href="#writer-objects">Writer Objects</a></li>112<li><a class="reference internal" href="#examples">Examples</a></li>113</ul>114</li>115</ul>116 117 </div>118 <div>119 <h4>Previous topic</h4>120 <p class="topless"><a href="fileformats.html"121 title="previous chapter">File Formats</a></p>122 </div>123 <div>124 <h4>Next topic</h4>125 <p class="topless"><a href="configparser.html"126 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>127 </div>128 <script>129 document.addEventListener('DOMContentLoaded', () => {130 const title = document.querySelector('meta[property="og:title"]').content;131 const elements = document.querySelectorAll('.improvepage');132 const pageurl = window.location.href.split('?')[0];133 elements.forEach(element => {134 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));135 url.searchParams.set('pagetitle', title);136 url.searchParams.set('pageurl', pageurl);137 url.searchParams.set('pagesource', "library/csv.rst");138 element.href = url.toString();139 });140 });141 </script>142 <div role="note" aria-label="source link">143 <h3>This page</h3>144 <ul class="this-page-menu">145 <li><a href="../bugs.html">Report a bug</a></li>146 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>147 <li>148 <a href="https://github.com/python/cpython/blob/main/Doc/library/csv.rst?plain=1"149 rel="nofollow">Show source150 </a>151 </li>152 153 </ul>154 </div>155 </nav>156 </div>157</div>158 159 160 <div class="related" role="navigation" aria-label="Related">161 <h3>Navigation</h3>162 <ul>163 <li class="right" style="margin-right: 10px">164 <a href="../genindex.html" title="General Index"165 accesskey="I">index</a></li>166 <li class="right" >167 <a href="../py-modindex.html" title="Python Module Index"168 >modules</a> |</li>169 <li class="right" >170 <a href="configparser.html" title="configparser — Configuration file parser"171 accesskey="N">next</a> |</li>172 <li class="right" >173 <a href="fileformats.html" title="File Formats"174 accesskey="P">previous</a> |</li>175 176 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>177 <li><a href="https://www.python.org/">Python</a> »</li>178 <li class="switchers">179 <div class="language_switcher_placeholder"></div>180 <div class="version_switcher_placeholder"></div>181 </li>182 <li>183 184 </li>185 <li id="cpython-language-and-version">186 <a href="../index.html">3.15.0a6 Documentation</a> »187 </li>188 189 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>190 <li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">File Formats</a> »</li>191 <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>192 <li class="right">193 194 195 <div class="inline-search" role="search">196 <form class="inline-search" action="../search.html" method="get">197 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">198 <input type="submit" value="Go">199 </form>200 </div>201 |202 </li>203 <li class="right">204<label class="theme-selector-label">205 Theme206 <select class="theme-selector" oninput="activateTheme(this.value)">207 <option value="auto" selected>Auto</option>208 <option value="light">Light</option>209 <option value="dark">Dark</option>210 </select>211</label> |</li>212 213 </ul>214 </div> 215 216 <div class="document">217 <div class="documentwrapper">218 <div class="bodywrapper">219 <div class="body" role="main">220 221 <section id="module-csv">222<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>223<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/csv.py">Lib/csv.py</a></p>224<hr class="docutils" id="index-0" />225<p>The so-called CSV (Comma Separated Values) format is the most common import and226export format for spreadsheets and databases. CSV format was used for many227years prior to attempts to describe the format in a standardized way in228<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 differences229often exist in the data produced and consumed by different applications. These230differences can make it annoying to process CSV files from multiple sources.231Still, while the delimiters and quoting characters vary, the overall format is232similar enough that it is possible to write a single module which can233efficiently manipulate such data, hiding the details of reading and writing the234data from the programmer.</p>235<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> module implements classes to read and write tabular data in CSV236format. It allows programmers to say, “write this data in the format preferred237by Excel,” or “read data from this file which was generated by Excel,” without238knowing the precise details of the CSV format used by Excel. Programmers can239also describe the CSV formats understood by other applications or define their240own special-purpose CSV formats.</p>241<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> 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 and242write sequences. Programmers can also read and write data in dictionary form243using 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>244<div class="admonition seealso">245<p class="admonition-title">See also</p>246<dl class="simple">247<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>248</dd>249</dl>250</div>251<section id="module-contents">252<span id="csv-contents"></span><h2>Module Contents<a class="headerlink" href="#module-contents" title="Link to this heading">¶</a></h2>253<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> module defines the following functions:</p>254<dl class="py function" id="index-3">255<dt class="sig sig-object py" id="csv.reader">256<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="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></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>257<dd><p>Return a <a class="reference internal" href="#reader-objects"><span class="std std-ref">reader object</span></a> that will process258lines from the given <em>csvfile</em>. A csvfile must be an iterable of259strings, each in the reader’s defined csv format.260A csvfile is most commonly a file-like object or list.261If <em>csvfile</em> is a file object,262it 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 optional263<em>dialect</em> parameter can be given which is used to define a set of parameters264specific to a particular CSV dialect. It may be an instance of a subclass of265the <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 the266<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 arguments267can be given to override individual formatting parameters in the current268dialect. For full details about the dialect and formatting parameters, see269section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>.</p>270<p>Each row read from the csv file is returned as a list of strings. No271automatic data type conversion is performed unless the <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> format272option is specified (in which case unquoted fields are transformed into floats).</p>273<p>A short usage example:</p>274<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>275<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>276<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>277<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>278<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>279<span class="go">Spam, Spam, Spam, Spam, Spam, Baked Beans</span>280<span class="go">Spam, Lovely Spam, Wonderful Spam</span>281</pre></div>282</div>283</dd></dl>284 285<dl class="py function">286<dt class="sig sig-object py" id="csv.writer">287<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="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></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>288<dd><p>Return a writer object responsible for converting the user’s data into delimited289strings on the given file-like object. <em>csvfile</em> can be any object with a290<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 with291<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>292parameter can be given which is used to define a set of parameters specific to a293particular CSV dialect. It may be an instance of a subclass of the294<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 the295<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 arguments296can be given to override individual formatting parameters in the current297dialect. For full details about dialects and formatting parameters, see298the <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a> section. To make it299as easy as possible to interface with modules which implement the DB API, the300value <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 a301reversible transformation, it makes it easier to dump SQL NULL data values to302CSV files without preprocessing the data returned from a <code class="docutils literal notranslate"><span class="pre">cursor.fetch*</span></code> call.303All 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>304<p>A short usage example:</p>305<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>306<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>307 <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>308 <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>309 <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>310 <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>311</pre></div>312</div>313</dd></dl>314 315<dl class="py function">316<dt class="sig sig-object py" id="csv.register_dialect">317<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>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></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.register_dialect" title="Link to this definition">¶</a></dt>318<dd><p>Associate <em>dialect</em> with <em>name</em>. <em>name</em> must be a string. The319dialect 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>, or320by <em>fmtparams</em> keyword arguments, or both, with keyword arguments overriding321parameters of the dialect. For full details about dialects and formatting322parameters, see section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>.</p>323</dd></dl>324 325<dl class="py function">326<dt class="sig sig-object py" id="csv.unregister_dialect">327<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>328<dd><p>Delete the dialect associated with <em>name</em> from the dialect registry. An329<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>330</dd></dl>331 332<dl class="py function">333<dt class="sig sig-object py" id="csv.get_dialect">334<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>335<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 if336<em>name</em> is not a registered dialect name. This function returns an immutable337<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>338</dd></dl>339 340<dl class="py function">341<dt class="sig sig-object py" id="csv.list_dialects">342<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>343<dd><p>Return the names of all registered dialects.</p>344</dd></dl>345 346<dl class="py function">347<dt class="sig sig-object py" id="csv.field_size_limit">348<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="sig-paren">)</span><a class="headerlink" href="#csv.field_size_limit" title="Link to this definition">¶</a></dt>349<dt class="sig sig-object py">350<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><em class="sig-param"><span class="n"><span class="pre">new_limit</span></span></em><span class="sig-paren">)</span></dt>351<dd><p>Returns the current maximum field size allowed by the parser. If <em>new_limit</em> is352given, this becomes the new limit.</p>353</dd></dl>354 355<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> module defines the following classes:</p>356<dl class="py class">357<dt class="sig sig-object py" id="csv.DictReader">358<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>359<dd><p>Create an object that operates like a regular reader but maps the360information 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 the361optional <em>fieldnames</em> parameter.</p>362<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> is363omitted, the values in the first row of file <em>f</em> will be used as the364fieldnames and will be omitted from the results. If365<em>fieldnames</em> is provided, they will be used and the first row will be366included in the results. Regardless of how the fieldnames are determined,367the dictionary preserves their original ordering.</p>368<p>If a row has more fields than fieldnames, the remaining data is put in a369list and stored with the fieldname specified by <em>restkey</em> (which defaults370to <code class="docutils literal notranslate"><span class="pre">None</span></code>). If a non-blank row has fewer fields than fieldnames, the371missing values are filled-in with the value of <em>restval</em> (which defaults372to <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>373<p>All other optional or keyword arguments are passed to the underlying374<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>375<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>376<div class="versionchanged">377<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>378</div>379<div class="versionchanged">380<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>381</div>382<p>A short usage example:</p>383<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>384<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>385<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>386<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>387<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>388<span class="gp">...</span>389<span class="go">Eric Idle</span>390<span class="go">John Cleese</span>391 392<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>393<span class="go">{'first_name': 'John', 'last_name': 'Cleese'}</span>394</pre></div>395</div>396</dd></dl>397 398<dl class="py class">399<dt class="sig sig-object py" id="csv.DictWriter">400<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>401<dd><p>Create an object which operates like a regular writer but maps dictionaries402onto 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 the403dictionary 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 file404<em>f</em>. The optional <em>restval</em> parameter specifies the value to be405written if the dictionary is missing a key in <em>fieldnames</em>. If the406dictionary passed to the <code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code> method contains a key not found in407<em>fieldnames</em>, the optional <em>extrasaction</em> parameter indicates what action to408take.409If 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>410is raised.411If it is set to <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code>, extra values in the dictionary are ignored.412Any other optional or keyword arguments are passed to the underlying413<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>414<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> parameter415of the <code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code> class is not optional.</p>416<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>417<p>A short usage example:</p>418<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>419 420<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>421 <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>422 <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>423 424 <span class="n">writer</span><span class="o">.</span><span class="n">writeheader</span><span class="p">()</span>425 <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>426 <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>427 <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>428</pre></div>429</div>430</dd></dl>431 432<dl class="py class">433<dt class="sig sig-object py" id="csv.Dialect">434<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>435<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code> class is a container class whose attributes contain436information for how to handle doublequotes, whitespace, delimiters, etc.437Due to the lack of a strict CSV specification, different applications438produce subtly different CSV data. <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code> instances define how439<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>440<p>All available <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code> 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>,441and 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>442classes through their initializer (<code class="docutils literal notranslate"><span class="pre">__init__</span></code>) functions like this:</p>443<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>444 445<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>446 <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>447</pre></div>448</div>449</dd></dl>450 451<dl class="py class">452<dt class="sig sig-object py" id="csv.excel">453<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>454<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">excel</span></code> class defines the usual properties of an Excel-generated CSV455file. It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'excel'</span></code>.</p>456</dd></dl>457 458<dl class="py class">459<dt class="sig sig-object py" id="csv.excel_tab">460<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>461<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">excel_tab</span></code> class defines the usual properties of an Excel-generated462TAB-delimited file. It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'excel-tab'</span></code>.</p>463</dd></dl>464 465<dl class="py class">466<dt class="sig sig-object py" id="csv.unix_dialect">467<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>468<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">unix_dialect</span></code> class defines the usual properties of a CSV file469generated on UNIX systems, i.e. using <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> as line terminator and quoting470all fields. It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'unix'</span></code>.</p>471<div class="versionadded">472<p><span class="versionmodified added">Added in version 3.2.</span></p>473</div>474</dd></dl>475 476<dl class="py class">477<dt class="sig sig-object py" id="csv.Sniffer">478<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>479<dd><p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code> class is used to deduce the format of a CSV file.</p>480<p>The <code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code> class provides two methods:</p>481<dl class="py method">482<dt class="sig sig-object py" id="csv.Sniffer.sniff">483<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>484<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> subclass485reflecting the parameters found. If the optional <em>delimiters</em> parameter486is given, it is interpreted as a string containing possible valid487delimiter characters.</p>488</dd></dl>489 490<dl class="py method">491<dt class="sig sig-object py" id="csv.Sniffer.has_header">492<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>493<dd><p>Analyze the sample text (presumed to be in CSV format) and return494<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.495Inspecting each column, one of two key criteria will be considered to496estimate if the sample contains a header:</p>497<ul class="simple">498<li><p>the second through n-th rows contain numeric values</p></li>499<li><p>the second through n-th rows contain strings where at least one value’s500length differs from that of the putative header of that column.</p></li>501</ul>502<p>Twenty-one rows after the header are sampled; if more than half of the503columns + 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>504</dd></dl>505 506<div class="admonition note">507<p class="admonition-title">Note</p>508<p>This method is a rough heuristic and may produce both false positives and509negatives.</p>510</div>511</dd></dl>512 513<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>514<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>515 <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>516 <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>517 <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>518 <span class="c1"># ... process CSV file contents here ...</span>519</pre></div>520</div>521<p id="csv-constants">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> module defines the following constants:</p>522<dl class="py data">523<dt class="sig sig-object py" id="csv.QUOTE_ALL">524<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>525<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>526</dd></dl>527 528<dl class="py data">529<dt class="sig sig-object py" id="csv.QUOTE_MINIMAL">530<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>531<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 contain532special characters such as <em>delimiter</em>, <em>quotechar</em>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>533or any of the characters in <em>lineterminator</em>.</p>534</dd></dl>535 536<dl class="py data">537<dt class="sig sig-object py" id="csv.QUOTE_NONNUMERIC">538<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>539<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>540<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 <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>.</p>541<div class="admonition note">542<p class="admonition-title">Note</p>543<p>Some numeric types, such as <a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal notranslate"><span class="pre">bool</span></code></a>, <a class="reference internal" href="fractions.html#fractions.Fraction" title="fractions.Fraction"><code class="xref py py-class docutils literal notranslate"><span class="pre">Fraction</span></code></a>,544or <a class="reference internal" href="enum.html#enum.IntEnum" title="enum.IntEnum"><code class="xref py py-class docutils literal notranslate"><span class="pre">IntEnum</span></code></a>, have a string representation that cannot be545converted to <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate"><span class="pre">float</span></code></a>.546They cannot be read in the <code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code> and547<a class="reference internal" href="#csv.QUOTE_STRINGS" title="csv.QUOTE_STRINGS"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_STRINGS</span></code></a> modes.</p>548</div>549</dd></dl>550 551<dl class="py data">552<dt class="sig sig-object py" id="csv.QUOTE_NONE">553<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>554<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.555When the current <em>delimiter</em>, <em>quotechar</em>, <em>escapechar</em>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>556or any of the characters in <em>lineterminator</em> occurs in output data557it is preceded by the current <em>escapechar</em> character.558If <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> if559any characters that require escaping are encountered.560Set <em>quotechar</em> to <code class="docutils literal notranslate"><span class="pre">None</span></code> to prevent its escaping.</p>561<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>562</dd></dl>563 564<dl class="py data">565<dt class="sig sig-object py" id="csv.QUOTE_NOTNULL">566<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>567<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 not568<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 a569field value is <code class="docutils literal notranslate"><span class="pre">None</span></code> an empty (unquoted) string is written.</p>570<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) field571as <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>572<div class="versionadded">573<p><span class="versionmodified added">Added in version 3.12.</span></p>574</div>575</dd></dl>576 577<dl class="py data">578<dt class="sig sig-object py" id="csv.QUOTE_STRINGS">579<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>580<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 fields581which 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 a582field value is <code class="docutils literal notranslate"><span class="pre">None</span></code> an empty (unquoted) string is written.</p>583<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> and584to 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>585<div class="versionadded">586<p><span class="versionmodified added">Added in version 3.12.</span></p>587</div>588</dd></dl>589 590<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> module defines the following exception:</p>591<dl class="py exception">592<dt class="sig sig-object py" id="csv.Error">593<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>594<dd><p>Raised by any of the functions when an error is detected.</p>595</dd></dl>596 597</section>598<section id="dialects-and-formatting-parameters">599<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>600<p>To make it easier to specify the format of input and output records, specific601formatting parameters are grouped together into dialects. A dialect is a602subclass 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 attributes603describing 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> or604<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 of605the <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code> class as the dialect parameter. In addition to, or instead606of, the <em>dialect</em> parameter, the programmer can also specify individual607formatting parameters, which have the same names as the attributes defined below608for the <code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code> class.</p>609<p>Dialects support the following attributes:</p>610<dl class="py attribute">611<dt class="sig sig-object py" id="csv.Dialect.delimiter">612<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>613<dd><p>A one-character string used to separate fields. It defaults to <code class="docutils literal notranslate"><span class="pre">','</span></code>.</p>614</dd></dl>615 616<dl class="py attribute">617<dt class="sig sig-object py" id="csv.Dialect.doublequote">618<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>619<dd><p>Controls how instances of <em>quotechar</em> appearing inside a field should620themselves 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. When621<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>. It622defaults to <code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code>.</p>623<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,624<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>625</dd></dl>626 627<dl class="py attribute">628<dt class="sig sig-object py" id="csv.Dialect.escapechar">629<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>630<dd><p>A one-character string used by the writer to escape characters that631require escaping:</p>632<blockquote>633<div><ul class="simple">634<li><p>the <em>delimiter</em>, the <em>quotechar</em>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> and any of the635characters in <em>lineterminator</em> are escaped if <em>quoting</em> is set to636<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>;</p></li>637<li><p>the <em>quotechar</em> is escaped 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>;</p></li>638<li><p>the <em>escapechar</em> itself.</p></li>639</ul>640</div></blockquote>641<p>On reading, the <em>escapechar</em> removes any special meaning from642the 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>643<div class="versionchanged">644<p><span class="versionmodified changed">Changed in version 3.11: </span>An empty <em>escapechar</em> is not allowed.</p>645</div>646</dd></dl>647 648<dl class="py attribute">649<dt class="sig sig-object py" id="csv.Dialect.lineterminator">650<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>651<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 defaults652to <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>.</p>653<div class="admonition note">654<p class="admonition-title">Note</p>655<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> as656end-of-line, and ignores <em>lineterminator</em>. This behavior may change in the657future.</p>658</div>659</dd></dl>660 661<dl class="py attribute">662<dt class="sig sig-object py" id="csv.Dialect.quotechar">663<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>664<dd><p>A one-character string used to quote fields containing special characters,665such as the <em>delimiter</em> or the <em>quotechar</em>, or which contain new-line666characters (<code class="docutils literal notranslate"><span class="pre">'\r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> or any of the characters in <em>lineterminator</em>).667It defaults to <code class="docutils literal notranslate"><span class="pre">'"'</span></code>.668Can be set to <code class="docutils literal notranslate"><span class="pre">None</span></code> to prevent escaping <code class="docutils literal notranslate"><span class="pre">'"'</span></code> if <em>quoting</em> is set669to <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>.</p>670<div class="versionchanged">671<p><span class="versionmodified changed">Changed in version 3.11: </span>An empty <em>quotechar</em> is not allowed.</p>672</div>673</dd></dl>674 675<dl class="py attribute">676<dt class="sig sig-object py" id="csv.Dialect.quoting">677<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>678<dd><p>Controls when quotes should be generated by the writer and recognised by the679reader. It can take on any of the <a class="reference internal" href="#csv-constants"><span class="std std-ref">QUOTE_* constants</span></a>680and 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> if <em>quotechar</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>,681and <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> otherwise.</p>682</dd></dl>683 684<dl class="py attribute">685<dt class="sig sig-object py" id="csv.Dialect.skipinitialspace">686<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>687<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.688The 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>. When combining <code class="docutils literal notranslate"><span class="pre">delimiter='</span> <span class="pre">'</span></code> with689<code class="docutils literal notranslate"><span class="pre">skipinitialspace=True</span></code>, unquoted empty fields are not allowed.</p>690</dd></dl>691 692<dl class="py attribute">693<dt class="sig sig-object py" id="csv.Dialect.strict">694<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>695<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.696The default is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>697</dd></dl>698 699</section>700<section id="reader-objects">701<span id="id3"></span><h2>Reader Objects<a class="headerlink" href="#reader-objects" title="Link to this heading">¶</a></h2>702<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 the703<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>704<dl class="py method">705<dt class="sig sig-object py" id="csv.csvreader.__next__">706<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>707<dd><p>Return the next row of the reader’s iterable object as a list (if the object708was 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>709instance), 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 you710should call this as <code class="docutils literal notranslate"><span class="pre">next(reader)</span></code>.</p>711</dd></dl>712 713<p>Reader objects have the following public attributes:</p>714<dl class="py attribute">715<dt class="sig sig-object py" id="csv.csvreader.dialect">716<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>717<dd><p>A read-only description of the dialect in use by the parser.</p>718</dd></dl>719 720<dl class="py attribute">721<dt class="sig sig-object py" id="csv.csvreader.line_num">722<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>723<dd><p>The number of lines read from the source iterator. This is not the same as the724number of records returned, as records can span multiple lines.</p>725</dd></dl>726 727<p>DictReader objects have the following public attribute:</p>728<dl class="py attribute">729<dt class="sig sig-object py" id="csv.DictReader.fieldnames">730<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>731<dd><p>If not passed as a parameter when creating the object, this attribute is732initialized upon first access or when the first record is read from the733file.</p>734</dd></dl>735 736</section>737<section id="writer-objects">738<h2>Writer Objects<a class="headerlink" href="#writer-objects" title="Link to this heading">¶</a></h2>739<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 by740the <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 be741an iterable of strings or numbers for <code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code> objects and a dictionary742mapping 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>743first) for <code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code> objects. Note that complex numbers are written744out surrounded by parens. This may cause some problems for other programs which745read CSV files (assuming they support complex numbers at all).</p>746<dl class="py method">747<dt class="sig sig-object py" id="csv.csvwriter.writerow">748<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>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerow" title="Link to this definition">¶</a></dt>749<dd><p>Write the <em>row</em> parameter to the writer’s file object, formatted according750to 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 the751<em>write</em> method of the underlying file object.</p>752<div class="versionchanged">753<p><span class="versionmodified changed">Changed in version 3.5: </span>Added support of arbitrary iterables.</p>754</div>755</dd></dl>756 757<dl class="py method">758<dt class="sig sig-object py" id="csv.csvwriter.writerows">759<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>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerows" title="Link to this definition">¶</a></dt>760<dd><p>Write all elements in <em>rows</em> (an iterable of <em>row</em> objects as described761above) to the writer’s file object, formatted according to the current762dialect.</p>763</dd></dl>764 765<p>Writer objects have the following public attribute:</p>766<dl class="py attribute">767<dt class="sig sig-object py" id="csv.csvwriter.dialect">768<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>769<dd><p>A read-only description of the dialect in use by the writer.</p>770</dd></dl>771 772<p>DictWriter objects have the following public method:</p>773<dl class="py method">774<dt class="sig sig-object py" id="csv.DictWriter.writeheader">775<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>776<dd><p>Write a row with the field names (as specified in the constructor) to777the writer’s file object, formatted according to the current dialect. Return778the 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>779<div class="versionadded">780<p><span class="versionmodified added">Added in version 3.2.</span></p>781</div>782<div class="versionchanged">783<p><span class="versionmodified changed">Changed in version 3.8: </span><code class="xref py py-meth docutils literal notranslate"><span class="pre">writeheader()</span></code> now also returns the value returned by784the <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>785</div>786</dd></dl>787 788</section>789<section id="examples">790<span id="csv-examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>791<p>The simplest example of reading a CSV file:</p>792<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>793<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>794 <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>795 <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>796 <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>797</pre></div>798</div>799<p>Reading a file with an alternate format:</p>800<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>801<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>802 <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>803 <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>804 <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>805</pre></div>806</div>807<p>The corresponding simplest possible writing example is:</p>808<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>809<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>810 <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>811 <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>812</pre></div>813</div>814<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 file815will by default be decoded into unicode using the system default816encoding (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 file817using a different encoding, use the <code class="docutils literal notranslate"><span class="pre">encoding</span></code> argument of open:</p>818<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>819<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>820 <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>821 <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>822 <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>823</pre></div>824</div>825<p>The same applies to writing in something other than the system default826encoding: specify the encoding argument when opening the output file.</p>827<p>Registering a new dialect:</p>828<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>829<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>830<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>831 <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>832</pre></div>833</div>834<p>A slightly more advanced use of the reader — catching and reporting errors:</p>835<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>836<span class="n">filename</span> <span class="o">=</span> <span class="s1">'some.csv'</span>837<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>838 <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>839 <span class="k">try</span><span class="p">:</span>840 <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>841 <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>842 <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>843 <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="sa">f</span><span class="s1">'file </span><span class="si">{</span><span class="n">filename</span><span class="si">}</span><span class="s1">, line </span><span class="si">{</span><span class="n">reader</span><span class="o">.</span><span class="n">line_num</span><span class="si">}</span><span class="s1">: </span><span class="si">{</span><span class="n">e</span><span class="si">}</span><span class="s1">'</span><span class="p">)</span>844</pre></div>845</div>846<p>And while the module doesn’t directly support parsing strings, it can easily be847done:</p>848<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>849<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>850 <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>851</pre></div>852</div>853<p class="rubric">Footnotes</p>854<aside class="footnote-list brackets">855<aside class="footnote brackets" id="id4" role="doc-footnote">856<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>857<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>)</span>858<p>If <code class="docutils literal notranslate"><span class="pre">newline=''</span></code> is not specified, newlines embedded inside quoted fields859will not be interpreted correctly, and on platforms that use <code class="docutils literal notranslate"><span class="pre">\r\n</span></code> line endings860on write an extra <code class="docutils literal notranslate"><span class="pre">\r</span></code> will be added. It should always be safe to specify861<code class="docutils literal notranslate"><span class="pre">newline=''</span></code>, since the csv module does its own862(<a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal</span></a>) newline handling.</p>863</aside>864</aside>865</section>866</section>867 868 869 <div class="clearer"></div>870 </div>871 </div>872 </div>873 <div class="sphinxsidebar" role="navigation" aria-label="Main">874 <div class="sphinxsidebarwrapper">875 <div>876 <h3><a href="../contents.html">Table of Contents</a></h3>877 <ul>878<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>879<li><a class="reference internal" href="#module-contents">Module Contents</a></li>880<li><a class="reference internal" href="#dialects-and-formatting-parameters">Dialects and Formatting Parameters</a></li>881<li><a class="reference internal" href="#reader-objects">Reader Objects</a></li>882<li><a class="reference internal" href="#writer-objects">Writer Objects</a></li>883<li><a class="reference internal" href="#examples">Examples</a></li>884</ul>885</li>886</ul>887 888 </div>889 <div>890 <h4>Previous topic</h4>891 <p class="topless"><a href="fileformats.html"892 title="previous chapter">File Formats</a></p>893 </div>894 <div>895 <h4>Next topic</h4>896 <p class="topless"><a href="configparser.html"897 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>898 </div>899 <script>900 document.addEventListener('DOMContentLoaded', () => {901 const title = document.querySelector('meta[property="og:title"]').content;902 const elements = document.querySelectorAll('.improvepage');903 const pageurl = window.location.href.split('?')[0];904 elements.forEach(element => {905 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));906 url.searchParams.set('pagetitle', title);907 url.searchParams.set('pageurl', pageurl);908 url.searchParams.set('pagesource', "library/csv.rst");909 element.href = url.toString();910 });911 });912 </script>913 <div role="note" aria-label="source link">914 <h3>This page</h3>915 <ul class="this-page-menu">916 <li><a href="../bugs.html">Report a bug</a></li>917 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>918 <li>919 <a href="https://github.com/python/cpython/blob/main/Doc/library/csv.rst?plain=1"920 rel="nofollow">Show source921 </a>922 </li>923 924 </ul>925 </div>926 </div>927<div id="sidebarbutton" title="Collapse sidebar">928<span>«</span>929</div>930 931 </div>932 <div class="clearer"></div>933 </div> 934 <div class="related" role="navigation" aria-label="Related">935 <h3>Navigation</h3>936 <ul>937 <li class="right" style="margin-right: 10px">938 <a href="../genindex.html" title="General Index"939 >index</a></li>940 <li class="right" >941 <a href="../py-modindex.html" title="Python Module Index"942 >modules</a> |</li>943 <li class="right" >944 <a href="configparser.html" title="configparser — Configuration file parser"945 >next</a> |</li>946 <li class="right" >947 <a href="fileformats.html" title="File Formats"948 >previous</a> |</li>949 950 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>951 <li><a href="https://www.python.org/">Python</a> »</li>952 <li class="switchers">953 <div class="language_switcher_placeholder"></div>954 <div class="version_switcher_placeholder"></div>955 </li>956 <li>957 958 </li>959 <li id="cpython-language-and-version">960 <a href="../index.html">3.15.0a6 Documentation</a> »961 </li>962 963 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>964 <li class="nav-item nav-item-2"><a href="fileformats.html" >File Formats</a> »</li>965 <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>966 <li class="right">967 968 969 <div class="inline-search" role="search">970 <form class="inline-search" action="../search.html" method="get">971 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">972 <input type="submit" value="Go">973 </form>974 </div>975 |976 </li>977 <li class="right">978<label class="theme-selector-label">979 Theme980 <select class="theme-selector" oninput="activateTheme(this.value)">981 <option value="auto" selected>Auto</option>982 <option value="light">Light</option>983 <option value="dark">Dark</option>984 </select>985</label> |</li>986 987 </ul>988 </div> 989 <div class="footer">990 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.991 <br>992 This page is licensed under the Python Software Foundation License Version 2.993 <br>994 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.995 <br>996 997 See <a href="/license.html">History and License</a> for more information.<br>998 999 1000 <br>1001 1002 The Python Software Foundation is a non-profit corporation.1003<a href="https://www.python.org/psf/donations/">Please donate.</a>1004<br>1005 <br>1006 Last updated on Mar 10, 2026 (08:58 UTC).1007 1008 <a href="/bugs.html">Found a bug</a>?1009 1010 <br>1011 1012 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.1013 </div>1014 1015 </body>1016</html>