Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Bevaka 1
Stjärnmärk 0
Wiki 捐赠
gooderp18绿色标准版
Du kan inte välja fler än 25 ämnen Ämnen måste starta med en bokstav eller siffra, kan innehålla bindestreck ('-') och vara max 35 tecken långa.
Gren: master
Grenar Taggar
${ item.name }
Skapa branchen ${ searchTerm }
från 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/csv.html

952 lines
89KB
Rå Permalänk Blame Historik 

  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" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <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..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>csv — CSV File Reading and Writing &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="configparser — Configuration file parser" href="configparser.html" />

  39.     <link rel="prev" title="File Formats" href="fileformats.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/csv.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <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>

  99. <li><a class="reference internal" href="#module-contents">Module Contents</a></li>

  100. <li><a class="reference internal" href="#dialects-and-formatting-parameters">Dialects and Formatting Parameters</a></li>

  101. <li><a class="reference internal" href="#reader-objects">Reader Objects</a></li>

  102. <li><a class="reference internal" href="#writer-objects">Writer Objects</a></li>

  103. <li><a class="reference internal" href="#examples">Examples</a></li>

  104. </ul>

  105. </li>

  106. </ul>

  107. 

  108.   </div>

  109.   <div>

  110.     <h4>Previous topic</h4>

  111.     <p class="topless"><a href="fileformats.html"

  112.                           title="previous chapter">File Formats</a></p>

  113.   </div>

  114.   <div>

  115.     <h4>Next topic</h4>

  116.     <p class="topless"><a href="configparser.html"

  117.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>

  118.   </div>

  119.   <div role="note" aria-label="source link">

  120.     <h3>This Page</h3>

  121.     <ul class="this-page-menu">

  122.       <li><a href="../bugs.html">Report a Bug</a></li>

  123.       <li>

  124.         <a href="https://github.com/python/cpython/blob/main/Doc/library/csv.rst"

  125.             rel="nofollow">Show Source

  126.         </a>

  127.       </li>

  128.     </ul>

  129.   </div>

  130.         </nav>

  131.     </div>

  132. </div>

  133. 

  134.   

  135.     <div class="related" role="navigation" aria-label="related navigation">

  136.       <h3>Navigation</h3>

  137.       <ul>

  138.         <li class="right" style="margin-right: 10px">

  139.           <a href="../genindex.html" title="General Index"

  140.              accesskey="I">index</a></li>

  141.         <li class="right" >

  142.           <a href="../py-modindex.html" title="Python Module Index"

  143.              >modules</a> |</li>

  144.         <li class="right" >

  145.           <a href="configparser.html" title="configparser — Configuration file parser"

  146.              accesskey="N">next</a> |</li>

  147.         <li class="right" >

  148.           <a href="fileformats.html" title="File Formats"

  149.              accesskey="P">previous</a> |</li>

  150. 

  151.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  152.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  153.           <li class="switchers">

  154.             <div class="language_switcher_placeholder"></div>

  155.             <div class="version_switcher_placeholder"></div>

  156.           </li>

  157.           <li>

  158.               

  159.           </li>

  160.     <li id="cpython-language-and-version">

  161.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  162.     </li>

  163. 

  164.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  165.           <li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">File Formats</a> &#187;</li>

  166.         <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>

  167.                 <li class="right">

  168.                     

  169. 

  170.     <div class="inline-search" role="search">

  171.         <form class="inline-search" action="../search.html" method="get">

  172.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  173.           <input type="submit" value="Go" />

  174.         </form>

  175.     </div>

  176.                      |

  177.                 </li>

  178.             <li class="right">

  179. <label class="theme-selector-label">

  180.     Theme

  181.     <select class="theme-selector" oninput="activateTheme(this.value)">

  182.         <option value="auto" selected>Auto</option>

  183.         <option value="light">Light</option>

  184.         <option value="dark">Dark</option>

  185.     </select>

  186. </label> |</li>

  187.             

  188.       </ul>

  189.     </div>    

  190. 

  191.     <div class="document">

  192.       <div class="documentwrapper">

  193.         <div class="bodywrapper">

  194.           <div class="body" role="main">

  195.             

  196.   <section id="module-csv">

  197. <span id="csv-csv-file-reading-and-writing"></span><h1><a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> — CSV File Reading and Writing<a class="headerlink" href="#module-csv" title="Link to this heading">¶</a></h1>

  198. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/csv.py">Lib/csv.py</a></p>

  199. <hr class="docutils" id="index-0" />

  200. <p>The so-called CSV (Comma Separated Values) format is the most common import and

  201. export format for spreadsheets and databases.  CSV format was used for many

  202. years prior to attempts to describe the format in a standardized way in

  203. <span class="target" id="index-1"></span><a class="rfc reference external" href="https://datatracker.ietf.org/doc/html/rfc4180.html"><strong>RFC 4180</strong></a>.  The lack of a well-defined standard means that subtle differences

  204. often exist in the data produced and consumed by different applications.  These

  205. differences can make it annoying to process CSV files from multiple sources.

  206. Still, while the delimiters and quoting characters vary, the overall format is

  207. similar enough that it is possible to write a single module which can

  208. efficiently manipulate such data, hiding the details of reading and writing the

  209. data from the programmer.</p>

  210. <p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module implements classes to read and write tabular data in CSV

  211. format.  It allows programmers to say, “write this data in the format preferred

  212. by Excel,” or “read data from this file which was generated by Excel,” without

  213. knowing the precise details of the CSV format used by Excel.  Programmers can

  214. also describe the CSV formats understood by other applications or define their

  215. own special-purpose CSV formats.</p>

  216. <p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module’s <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> and <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects read and

  217. write sequences.  Programmers can also read and write data in dictionary form

  218. using the <a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a> and <a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> classes.</p>

  219. <div class="admonition seealso">

  220. <p class="admonition-title">See also</p>

  221. <dl class="simple">

  222. <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>

  223. </dd>

  224. </dl>

  225. </div>

  226. <section id="module-contents">

  227. <span id="csv-contents"></span><h2>Module Contents<a class="headerlink" href="#module-contents" title="Link to this heading">¶</a></h2>

  228. <p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following functions:</p>

  229. <dl class="py function" id="index-3">

  230. <dt class="sig sig-object py" id="csv.reader">

  231. <span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">reader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">csvfile</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'excel'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">fmtparams</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.reader" title="Link to this definition">¶</a></dt>

  232. <dd><p>Return a <a class="reference internal" href="#reader-objects"><span class="std std-ref">reader object</span></a> that will process

  233. lines from the given <em>csvfile</em>.  A csvfile must be an iterable of

  234. strings, each in the reader’s defined csv format.

  235. A csvfile is most commonly a file-like object or list.

  236. If <em>csvfile</em> is a file object,

  237. it should be opened with <code class="docutils literal notranslate"><span class="pre">newline=''</span></code>. <a class="footnote-reference brackets" href="#id4" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>  An optional

  238. <em>dialect</em> parameter can be given which is used to define a set of parameters

  239. specific to a particular CSV dialect.  It may be an instance of a subclass of

  240. the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class or one of the strings returned by the

  241. <a class="reference internal" href="#csv.list_dialects" title="csv.list_dialects"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_dialects()</span></code></a> function.  The other optional <em>fmtparams</em> keyword arguments

  242. can be given to override individual formatting parameters in the current

  243. dialect.  For full details about the dialect and formatting parameters, see

  244. section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>.</p>

  245. <p>Each row read from the csv file is returned as a list of strings.  No

  246. automatic data type conversion is performed unless the <code class="docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code> format

  247. option is specified (in which case unquoted fields are transformed into floats).</p>

  248. <p>A short usage example:</p>

  249. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">csv</span>

  250. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;eggs.csv&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>

  251. <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">&#39; &#39;</span><span class="p">,</span> <span class="n">quotechar</span><span class="o">=</span><span class="s1">&#39;|&#39;</span><span class="p">)</span>

  252. <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>

  253. <span class="gp">... </span>        <span class="nb">print</span><span class="p">(</span><span class="s1">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">row</span><span class="p">))</span>

  254. <span class="go">Spam, Spam, Spam, Spam, Spam, Baked Beans</span>

  255. <span class="go">Spam, Lovely Spam, Wonderful Spam</span>

  256. </pre></div>

  257. </div>

  258. </dd></dl>

  259. 

  260. <dl class="py function">

  261. <dt class="sig sig-object py" id="csv.writer">

  262. <span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">writer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">csvfile</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'excel'</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">fmtparams</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.writer" title="Link to this definition">¶</a></dt>

  263. <dd><p>Return a writer object responsible for converting the user’s data into delimited

  264. strings on the given file-like object.  <em>csvfile</em> can be any object with a

  265. <a class="reference internal" href="io.html#io.TextIOBase.write" title="io.TextIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> method.  If <em>csvfile</em> is a file object, it should be opened with

  266. <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>

  267. parameter can be given which is used to define a set of parameters specific to a

  268. particular CSV dialect.  It may be an instance of a subclass of the

  269. <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class or one of the strings returned by the

  270. <a class="reference internal" href="#csv.list_dialects" title="csv.list_dialects"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_dialects()</span></code></a> function.  The other optional <em>fmtparams</em> keyword arguments

  271. can be given to override individual formatting parameters in the current

  272. dialect.  For full details about dialects and formatting parameters, see

  273. the <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a> section. To make it

  274. as easy as possible to interface with modules which implement the DB API, the

  275. value <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> is written as the empty string.  While this isn’t a

  276. reversible transformation, it makes it easier to dump SQL NULL data values to

  277. CSV files without preprocessing the data returned from a <code class="docutils literal notranslate"><span class="pre">cursor.fetch*</span></code> call.

  278. All other non-string data are stringified with <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> before being written.</p>

  279. <p>A short usage example:</p>

  280. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  281. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;eggs.csv&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>

  282.     <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">&#39; &#39;</span><span class="p">,</span>

  283.                             <span class="n">quotechar</span><span class="o">=</span><span class="s1">&#39;|&#39;</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>

  284.     <span class="n">spamwriter</span><span class="o">.</span><span class="n">writerow</span><span class="p">([</span><span class="s1">&#39;Spam&#39;</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">&#39;Baked Beans&#39;</span><span class="p">])</span>

  285.     <span class="n">spamwriter</span><span class="o">.</span><span class="n">writerow</span><span class="p">([</span><span class="s1">&#39;Spam&#39;</span><span class="p">,</span> <span class="s1">&#39;Lovely Spam&#39;</span><span class="p">,</span> <span class="s1">&#39;Wonderful Spam&#39;</span><span class="p">])</span>

  286. </pre></div>

  287. </div>

  288. </dd></dl>

  289. 

  290. <dl class="py function">

  291. <dt class="sig sig-object py" id="csv.register_dialect">

  292. <span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">register_dialect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">dialect</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">**fmtparams</span></span></em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.register_dialect" title="Link to this definition">¶</a></dt>

  293. <dd><p>Associate <em>dialect</em> with <em>name</em>.  <em>name</em> must be a string. The

  294. dialect can be specified either by passing a sub-class of <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a>, or

  295. by <em>fmtparams</em> keyword arguments, or both, with keyword arguments overriding

  296. parameters of the dialect. For full details about dialects and formatting

  297. parameters, see section <a class="reference internal" href="#csv-fmt-params"><span class="std std-ref">Dialects and Formatting Parameters</span></a>.</p>

  298. </dd></dl>

  299. 

  300. <dl class="py function">

  301. <dt class="sig sig-object py" id="csv.unregister_dialect">

  302. <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>

  303. <dd><p>Delete the dialect associated with <em>name</em> from the dialect registry.  An

  304. <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>

  305. </dd></dl>

  306. 

  307. <dl class="py function">

  308. <dt class="sig sig-object py" id="csv.get_dialect">

  309. <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>

  310. <dd><p>Return the dialect associated with <em>name</em>.  An <a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> is raised if

  311. <em>name</em> is not a registered dialect name.  This function returns an immutable

  312. <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>

  313. </dd></dl>

  314. 

  315. <dl class="py function">

  316. <dt class="sig sig-object py" id="csv.list_dialects">

  317. <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>

  318. <dd><p>Return the names of all registered dialects.</p>

  319. </dd></dl>

  320. 

  321. <dl class="py function">

  322. <dt class="sig sig-object py" id="csv.field_size_limit">

  323. <span class="sig-prename descclassname"><span class="pre">csv.</span></span><span class="sig-name descname"><span class="pre">field_size_limit</span></span><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param"><span class="n"><span class="pre">new_limit</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#csv.field_size_limit" title="Link to this definition">¶</a></dt>

  324. <dd><p>Returns the current maximum field size allowed by the parser. If <em>new_limit</em> is

  325. given, this becomes the new limit.</p>

  326. </dd></dl>

  327. 

  328. <p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following classes:</p>

  329. <dl class="py class">

  330. <dt class="sig sig-object py" id="csv.DictReader">

  331. <em class="property"><span class="pre">class</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>

  332. <dd><p>Create an object that operates like a regular reader but maps the

  333. information in each row to a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> whose keys are given by the

  334. optional <em>fieldnames</em> parameter.</p>

  335. <p>The <em>fieldnames</em> parameter is a <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequence</span></a>.  If <em>fieldnames</em> is

  336. omitted, the values in the first row of file <em>f</em> will be used as the

  337. fieldnames.  Regardless of how the fieldnames are determined, the

  338. dictionary preserves their original ordering.</p>

  339. <p>If a row has more fields than fieldnames, the remaining data is put in a

  340. list and stored with the fieldname specified by <em>restkey</em> (which defaults

  341. to <code class="docutils literal notranslate"><span class="pre">None</span></code>).  If a non-blank row has fewer fields than fieldnames, the

  342. missing values are filled-in with the value of <em>restval</em> (which defaults

  343. to <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>

  344. <p>All other optional or keyword arguments are passed to the underlying

  345. <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>

  346. <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>

  347. <div class="versionchanged">

  348. <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>

  349. </div>

  350. <div class="versionchanged">

  351. <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>

  352. </div>

  353. <p>A short usage example:</p>

  354. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">csv</span>

  355. <span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;names.csv&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>

  356. <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>

  357. <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>

  358. <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">&#39;first_name&#39;</span><span class="p">],</span> <span class="n">row</span><span class="p">[</span><span class="s1">&#39;last_name&#39;</span><span class="p">])</span>

  359. <span class="gp">...</span>

  360. <span class="go">Eric Idle</span>

  361. <span class="go">John Cleese</span>

  362. 

  363. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>

  364. <span class="go">{&#39;first_name&#39;: &#39;John&#39;, &#39;last_name&#39;: &#39;Cleese&#39;}</span>

  365. </pre></div>

  366. </div>

  367. </dd></dl>

  368. 

  369. <dl class="py class">

  370. <dt class="sig sig-object py" id="csv.DictWriter">

  371. <em class="property"><span class="pre">class</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>

  372. <dd><p>Create an object which operates like a regular writer but maps dictionaries

  373. onto output rows.  The <em>fieldnames</em> parameter is a <a class="reference internal" href="collections.abc.html#module-collections.abc" title="collections.abc: Abstract base classes for containers"><code class="xref py py-mod docutils literal notranslate"><span class="pre">sequence</span></code></a> of keys that identify the order in which values in the

  374. dictionary passed to the <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code></a> method are written to file

  375. <em>f</em>.  The optional <em>restval</em> parameter specifies the value to be

  376. written if the dictionary is missing a key in <em>fieldnames</em>.  If the

  377. dictionary passed to the <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writerow()</span></code></a> method contains a key not found in

  378. <em>fieldnames</em>, the optional <em>extrasaction</em> parameter indicates what action to

  379. take.

  380. If it is set to <code class="docutils literal notranslate"><span class="pre">'raise'</span></code>, the default value, a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>

  381. is raised.

  382. If it is set to <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code>, extra values in the dictionary are ignored.

  383. Any other optional or keyword arguments are passed to the underlying

  384. <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>

  385. <p>Note that unlike the <a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a> class, the <em>fieldnames</em> parameter

  386. of the <a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> class is not optional.</p>

  387. <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>

  388. <p>A short usage example:</p>

  389. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  390. 

  391. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;names.csv&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>

  392.     <span class="n">fieldnames</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;first_name&#39;</span><span class="p">,</span> <span class="s1">&#39;last_name&#39;</span><span class="p">]</span>

  393.     <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>

  394. 

  395.     <span class="n">writer</span><span class="o">.</span><span class="n">writeheader</span><span class="p">()</span>

  396.     <span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">({</span><span class="s1">&#39;first_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Baked&#39;</span><span class="p">,</span> <span class="s1">&#39;last_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Beans&#39;</span><span class="p">})</span>

  397.     <span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">({</span><span class="s1">&#39;first_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Lovely&#39;</span><span class="p">,</span> <span class="s1">&#39;last_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Spam&#39;</span><span class="p">})</span>

  398.     <span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">({</span><span class="s1">&#39;first_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Wonderful&#39;</span><span class="p">,</span> <span class="s1">&#39;last_name&#39;</span><span class="p">:</span> <span class="s1">&#39;Spam&#39;</span><span class="p">})</span>

  399. </pre></div>

  400. </div>

  401. </dd></dl>

  402. 

  403. <dl class="py class">

  404. <dt class="sig sig-object py" id="csv.Dialect">

  405. <em class="property"><span class="pre">class</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>

  406. <dd><p>The <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class is a container class whose attributes contain

  407. information for how to handle doublequotes, whitespace, delimiters, etc.

  408. Due to the lack of a strict CSV specification, different applications

  409. produce subtly different CSV data.  <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> instances define how

  410. <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>

  411. <p>All available <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> names are returned by <a class="reference internal" href="#csv.list_dialects" title="csv.list_dialects"><code class="xref py py-func docutils literal notranslate"><span class="pre">list_dialects()</span></code></a>,

  412. and they can be registered with specific <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> and <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a>

  413. classes through their initializer (<code class="docutils literal notranslate"><span class="pre">__init__</span></code>) functions like this:</p>

  414. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  415. 

  416. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;students.csv&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>

  417.     <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">&#39;unix&#39;</span><span class="p">)</span>

  418. </pre></div>

  419. </div>

  420. </dd></dl>

  421. 

  422. <dl class="py class">

  423. <dt class="sig sig-object py" id="csv.excel">

  424. <em class="property"><span class="pre">class</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>

  425. <dd><p>The <a class="reference internal" href="#csv.excel" title="csv.excel"><code class="xref py py-class docutils literal notranslate"><span class="pre">excel</span></code></a> class defines the usual properties of an Excel-generated CSV

  426. file.  It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'excel'</span></code>.</p>

  427. </dd></dl>

  428. 

  429. <dl class="py class">

  430. <dt class="sig sig-object py" id="csv.excel_tab">

  431. <em class="property"><span class="pre">class</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>

  432. <dd><p>The <a class="reference internal" href="#csv.excel_tab" title="csv.excel_tab"><code class="xref py py-class docutils literal notranslate"><span class="pre">excel_tab</span></code></a> class defines the usual properties of an Excel-generated

  433. TAB-delimited file.  It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'excel-tab'</span></code>.</p>

  434. </dd></dl>

  435. 

  436. <dl class="py class">

  437. <dt class="sig sig-object py" id="csv.unix_dialect">

  438. <em class="property"><span class="pre">class</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>

  439. <dd><p>The <a class="reference internal" href="#csv.unix_dialect" title="csv.unix_dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">unix_dialect</span></code></a> class defines the usual properties of a CSV file

  440. generated on UNIX systems, i.e. using <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> as line terminator and quoting

  441. all fields.  It is registered with the dialect name <code class="docutils literal notranslate"><span class="pre">'unix'</span></code>.</p>

  442. <div class="versionadded">

  443. <p><span class="versionmodified added">New in version 3.2.</span></p>

  444. </div>

  445. </dd></dl>

  446. 

  447. <dl class="py class">

  448. <dt class="sig sig-object py" id="csv.Sniffer">

  449. <em class="property"><span class="pre">class</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>

  450. <dd><p>The <a class="reference internal" href="#csv.Sniffer" title="csv.Sniffer"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code></a> class is used to deduce the format of a CSV file.</p>

  451. <p>The <a class="reference internal" href="#csv.Sniffer" title="csv.Sniffer"><code class="xref py py-class docutils literal notranslate"><span class="pre">Sniffer</span></code></a> class provides two methods:</p>

  452. <dl class="py method">

  453. <dt class="sig sig-object py" id="csv.Sniffer.sniff">

  454. <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>

  455. <dd><p>Analyze the given <em>sample</em> and return a <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> subclass

  456. reflecting the parameters found.  If the optional <em>delimiters</em> parameter

  457. is given, it is interpreted as a string containing possible valid

  458. delimiter characters.</p>

  459. </dd></dl>

  460. 

  461. <dl class="py method">

  462. <dt class="sig sig-object py" id="csv.Sniffer.has_header">

  463. <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>

  464. <dd><p>Analyze the sample text (presumed to be in CSV format) and return

  465. <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.

  466. Inspecting each column, one of two key criteria will be considered to

  467. estimate if the sample contains a header:</p>

  468. <ul class="simple">

  469. <li><p>the second through n-th rows contain numeric values</p></li>

  470. <li><p>the second through n-th rows contain strings where at least one value’s

  471. length differs from that of the putative header of that column.</p></li>

  472. </ul>

  473. <p>Twenty rows after the first row are sampled; if more than half of columns +

  474. 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>

  475. </dd></dl>

  476. 

  477. <div class="admonition note">

  478. <p class="admonition-title">Note</p>

  479. <p>This method is a rough heuristic and may produce both false positives and

  480. negatives.</p>

  481. </div>

  482. </dd></dl>

  483. 

  484. <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>

  485. <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">&#39;example.csv&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">csvfile</span><span class="p">:</span>

  486.     <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>

  487.     <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>

  488.     <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>

  489.     <span class="c1"># ... process CSV file contents here ...</span>

  490. </pre></div>

  491. </div>

  492. <p id="csv-constants">The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following constants:</p>

  493. <dl class="py data">

  494. <dt class="sig sig-object py" id="csv.QUOTE_ALL">

  495. <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>

  496. <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>

  497. </dd></dl>

  498. 

  499. <dl class="py data">

  500. <dt class="sig sig-object py" id="csv.QUOTE_MINIMAL">

  501. <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>

  502. <dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to only quote those fields which contain

  503. special characters such as <em>delimiter</em>, <em>quotechar</em> or any of the characters in

  504. <em>lineterminator</em>.</p>

  505. </dd></dl>

  506. 

  507. <dl class="py data">

  508. <dt class="sig sig-object py" id="csv.QUOTE_NONNUMERIC">

  509. <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>

  510. <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>

  511. <p>Instructs <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> objects to convert all non-quoted fields to type <em>float</em>.</p>

  512. </dd></dl>

  513. 

  514. <dl class="py data">

  515. <dt class="sig sig-object py" id="csv.QUOTE_NONE">

  516. <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>

  517. <dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to never quote fields.  When the current

  518. <em>delimiter</em> occurs in output data it is preceded by the current <em>escapechar</em>

  519. character.  If <em>escapechar</em> is not set, the writer will raise <a class="reference internal" href="#csv.Error" title="csv.Error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">Error</span></code></a> if

  520. any characters that require escaping are encountered.</p>

  521. <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>

  522. </dd></dl>

  523. 

  524. <dl class="py data">

  525. <dt class="sig sig-object py" id="csv.QUOTE_NOTNULL">

  526. <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>

  527. <dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to quote all fields which are not

  528. <code class="docutils literal notranslate"><span class="pre">None</span></code>.  This is similar to <a class="reference internal" href="#csv.QUOTE_ALL" title="csv.QUOTE_ALL"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_ALL</span></code></a>, except that if a

  529. field value is <code class="docutils literal notranslate"><span class="pre">None</span></code> an empty (unquoted) string is written.</p>

  530. <p>Instructs <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> objects to interpret an empty (unquoted) field as None and

  531. 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>

  532. <div class="versionadded">

  533. <p><span class="versionmodified added">New in version 3.12.</span></p>

  534. </div>

  535. </dd></dl>

  536. 

  537. <dl class="py data">

  538. <dt class="sig sig-object py" id="csv.QUOTE_STRINGS">

  539. <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>

  540. <dd><p>Instructs <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects to always place quotes around fields

  541. which are strings.  This is similar to <a class="reference internal" href="#csv.QUOTE_NONNUMERIC" title="csv.QUOTE_NONNUMERIC"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code></a>, except that if a

  542. field value is <code class="docutils literal notranslate"><span class="pre">None</span></code> an empty (unquoted) string is written.</p>

  543. <p>Instructs <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> objects to interpret an empty (unquoted) string as <code class="docutils literal notranslate"><span class="pre">None</span></code> and

  544. to otherwise behave as <a class="reference internal" href="#csv.QUOTE_NONNUMERIC" title="csv.QUOTE_NONNUMERIC"><code class="xref py py-data docutils literal notranslate"><span class="pre">QUOTE_NONNUMERIC</span></code></a>.</p>

  545. <div class="versionadded">

  546. <p><span class="versionmodified added">New in version 3.12.</span></p>

  547. </div>

  548. </dd></dl>

  549. 

  550. <p>The <a class="reference internal" href="#module-csv" title="csv: Write and read tabular data to and from delimited files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code></a> module defines the following exception:</p>

  551. <dl class="py exception">

  552. <dt class="sig sig-object py" id="csv.Error">

  553. <em class="property"><span class="pre">exception</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>

  554. <dd><p>Raised by any of the functions when an error is detected.</p>

  555. </dd></dl>

  556. 

  557. </section>

  558. <section id="dialects-and-formatting-parameters">

  559. <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>

  560. <p>To make it easier to specify the format of input and output records, specific

  561. formatting parameters are grouped together into dialects.  A dialect is a

  562. subclass of the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class containing various attributes

  563. describing the format of the CSV file.  When creating <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> or

  564. <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects, the programmer can specify a string or a subclass of

  565. the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class as the dialect parameter.  In addition to, or instead

  566. of, the <em>dialect</em> parameter, the programmer can also specify individual

  567. formatting parameters, which have the same names as the attributes defined below

  568. for the <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a> class.</p>

  569. <p>Dialects support the following attributes:</p>

  570. <dl class="py attribute">

  571. <dt class="sig sig-object py" id="csv.Dialect.delimiter">

  572. <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>

  573. <dd><p>A one-character string used to separate fields.  It defaults to <code class="docutils literal notranslate"><span class="pre">','</span></code>.</p>

  574. </dd></dl>

  575. 

  576. <dl class="py attribute">

  577. <dt class="sig sig-object py" id="csv.Dialect.doublequote">

  578. <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>

  579. <dd><p>Controls how instances of <em>quotechar</em> appearing inside a field should

  580. themselves be quoted.  When <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>, the character is doubled. When

  581. <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>, the <em>escapechar</em> is used as a prefix to the <em>quotechar</em>.  It

  582. defaults to <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>.</p>

  583. <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,

  584. <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>

  585. </dd></dl>

  586. 

  587. <dl class="py attribute">

  588. <dt class="sig sig-object py" id="csv.Dialect.escapechar">

  589. <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>

  590. <dd><p>A one-character string used by the writer to escape the <em>delimiter</em> if <em>quoting</em>

  591. is set to <a class="reference internal" href="#csv.QUOTE_NONE" title="csv.QUOTE_NONE"><code class="xref py py-const docutils literal notranslate"><span class="pre">QUOTE_NONE</span></code></a> and the <em>quotechar</em> if <em>doublequote</em> is

  592. <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>. On reading, the <em>escapechar</em> removes any special meaning from

  593. the following character. It defaults to <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a>, which disables escaping.</p>

  594. <div class="versionchanged">

  595. <p><span class="versionmodified changed">Changed in version 3.11: </span>An empty <em>escapechar</em> is not allowed.</p>

  596. </div>

  597. </dd></dl>

  598. 

  599. <dl class="py attribute">

  600. <dt class="sig sig-object py" id="csv.Dialect.lineterminator">

  601. <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>

  602. <dd><p>The string used to terminate lines produced by the <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a>. It defaults

  603. to <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>.</p>

  604. <div class="admonition note">

  605. <p class="admonition-title">Note</p>

  606. <p>The <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-class docutils literal notranslate"><span class="pre">reader</span></code></a> is hard-coded to recognise either <code class="docutils literal notranslate"><span class="pre">'\r'</span></code> or <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> as

  607. end-of-line, and ignores <em>lineterminator</em>. This behavior may change in the

  608. future.</p>

  609. </div>

  610. </dd></dl>

  611. 

  612. <dl class="py attribute">

  613. <dt class="sig sig-object py" id="csv.Dialect.quotechar">

  614. <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>

  615. <dd><p>A one-character string used to quote fields containing special characters, such

  616. as the <em>delimiter</em> or <em>quotechar</em>, or which contain new-line characters.  It

  617. defaults to <code class="docutils literal notranslate"><span class="pre">'&quot;'</span></code>.</p>

  618. <div class="versionchanged">

  619. <p><span class="versionmodified changed">Changed in version 3.11: </span>An empty <em>quotechar</em> is not allowed.</p>

  620. </div>

  621. </dd></dl>

  622. 

  623. <dl class="py attribute">

  624. <dt class="sig sig-object py" id="csv.Dialect.quoting">

  625. <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>

  626. <dd><p>Controls when quotes should be generated by the writer and recognised by the

  627. reader.  It can take on any of the <a class="reference internal" href="#csv-constants"><span class="std std-ref">QUOTE_* constants</span></a>

  628. and defaults to <a class="reference internal" href="#csv.QUOTE_MINIMAL" title="csv.QUOTE_MINIMAL"><code class="xref py py-const docutils literal notranslate"><span class="pre">QUOTE_MINIMAL</span></code></a>.</p>

  629. </dd></dl>

  630. 

  631. <dl class="py attribute">

  632. <dt class="sig sig-object py" id="csv.Dialect.skipinitialspace">

  633. <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>

  634. <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.

  635. The default is <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>.</p>

  636. </dd></dl>

  637. 

  638. <dl class="py attribute">

  639. <dt class="sig sig-object py" id="csv.Dialect.strict">

  640. <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>

  641. <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.

  642. The default is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>

  643. </dd></dl>

  644. 

  645. </section>

  646. <section id="reader-objects">

  647. <span id="id3"></span><h2>Reader Objects<a class="headerlink" href="#reader-objects" title="Link to this heading">¶</a></h2>

  648. <p>Reader objects (<a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a> instances and objects returned by the

  649. <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>

  650. <dl class="py method">

  651. <dt class="sig sig-object py" id="csv.csvreader.__next__">

  652. <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>

  653. <dd><p>Return the next row of the reader’s iterable object as a list (if the object

  654. was returned from <a class="reference internal" href="#csv.reader" title="csv.reader"><code class="xref py py-func docutils literal notranslate"><span class="pre">reader()</span></code></a>) or a dict (if it is a <a class="reference internal" href="#csv.DictReader" title="csv.DictReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictReader</span></code></a>

  655. instance), parsed according to the current <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a>.  Usually you

  656. should call this as <code class="docutils literal notranslate"><span class="pre">next(reader)</span></code>.</p>

  657. </dd></dl>

  658. 

  659. <p>Reader objects have the following public attributes:</p>

  660. <dl class="py attribute">

  661. <dt class="sig sig-object py" id="csv.csvreader.dialect">

  662. <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>

  663. <dd><p>A read-only description of the dialect in use by the parser.</p>

  664. </dd></dl>

  665. 

  666. <dl class="py attribute">

  667. <dt class="sig sig-object py" id="csv.csvreader.line_num">

  668. <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>

  669. <dd><p>The number of lines read from the source iterator. This is not the same as the

  670. number of records returned, as records can span multiple lines.</p>

  671. </dd></dl>

  672. 

  673. <p>DictReader objects have the following public attribute:</p>

  674. <dl class="py attribute">

  675. <dt class="sig sig-object py" id="csv.DictReader.fieldnames">

  676. <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>

  677. <dd><p>If not passed as a parameter when creating the object, this attribute is

  678. initialized upon first access or when the first record is read from the

  679. file.</p>

  680. </dd></dl>

  681. 

  682. </section>

  683. <section id="writer-objects">

  684. <h2>Writer Objects<a class="headerlink" href="#writer-objects" title="Link to this heading">¶</a></h2>

  685. <p><a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects (<a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> instances and objects returned by

  686. the <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-func docutils literal notranslate"><span class="pre">writer()</span></code></a> function) have the following public methods.  A <em>row</em> must be

  687. an iterable of strings or numbers for <a class="reference internal" href="#csv.writer" title="csv.writer"><code class="xref py py-class docutils literal notranslate"><span class="pre">writer</span></code></a> objects and a dictionary

  688. mapping fieldnames to strings or numbers (by passing them through <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a>

  689. first) for <a class="reference internal" href="#csv.DictWriter" title="csv.DictWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">DictWriter</span></code></a> objects.  Note that complex numbers are written

  690. out surrounded by parens. This may cause some problems for other programs which

  691. read CSV files (assuming they support complex numbers at all).</p>

  692. <dl class="py method">

  693. <dt class="sig sig-object py" id="csv.csvwriter.writerow">

  694. <span class="sig-prename descclassname"><span class="pre">csvwriter.</span></span><span class="sig-name descname"><span class="pre">writerow</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">row</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerow" title="Link to this definition">¶</a></dt>

  695. <dd><p>Write the <em>row</em> parameter to the writer’s file object, formatted according

  696. to the current <a class="reference internal" href="#csv.Dialect" title="csv.Dialect"><code class="xref py py-class docutils literal notranslate"><span class="pre">Dialect</span></code></a>. Return the return value of the call to the

  697. <em>write</em> method of the underlying file object.</p>

  698. <div class="versionchanged">

  699. <p><span class="versionmodified changed">Changed in version 3.5: </span>Added support of arbitrary iterables.</p>

  700. </div>

  701. </dd></dl>

  702. 

  703. <dl class="py method">

  704. <dt class="sig sig-object py" id="csv.csvwriter.writerows">

  705. <span class="sig-prename descclassname"><span class="pre">csvwriter.</span></span><span class="sig-name descname"><span class="pre">writerows</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">rows</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#csv.csvwriter.writerows" title="Link to this definition">¶</a></dt>

  706. <dd><p>Write all elements in <em>rows</em> (an iterable of <em>row</em> objects as described

  707. above) to the writer’s file object, formatted according to the current

  708. dialect.</p>

  709. </dd></dl>

  710. 

  711. <p>Writer objects have the following public attribute:</p>

  712. <dl class="py attribute">

  713. <dt class="sig sig-object py" id="csv.csvwriter.dialect">

  714. <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>

  715. <dd><p>A read-only description of the dialect in use by the writer.</p>

  716. </dd></dl>

  717. 

  718. <p>DictWriter objects have the following public method:</p>

  719. <dl class="py method">

  720. <dt class="sig sig-object py" id="csv.DictWriter.writeheader">

  721. <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>

  722. <dd><p>Write a row with the field names (as specified in the constructor) to

  723. the writer’s file object, formatted according to the current dialect. Return

  724. the return value of the <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">csvwriter.writerow()</span></code></a> call used internally.</p>

  725. <div class="versionadded">

  726. <p><span class="versionmodified added">New in version 3.2.</span></p>

  727. </div>

  728. <div class="versionchanged">

  729. <p><span class="versionmodified changed">Changed in version 3.8: </span><a class="reference internal" href="#csv.DictWriter.writeheader" title="csv.DictWriter.writeheader"><code class="xref py py-meth docutils literal notranslate"><span class="pre">writeheader()</span></code></a> now also returns the value returned by

  730. the <a class="reference internal" href="#csv.csvwriter.writerow" title="csv.csvwriter.writerow"><code class="xref py py-meth docutils literal notranslate"><span class="pre">csvwriter.writerow()</span></code></a> method it uses internally.</p>

  731. </div>

  732. </dd></dl>

  733. 

  734. </section>

  735. <section id="examples">

  736. <span id="csv-examples"></span><h2>Examples<a class="headerlink" href="#examples" title="Link to this heading">¶</a></h2>

  737. <p>The simplest example of reading a CSV file:</p>

  738. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  739. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;some.csv&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  740.     <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>

  741.     <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>

  742.         <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>

  743. </pre></div>

  744. </div>

  745. <p>Reading a file with an alternate format:</p>

  746. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  747. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;passwd&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  748.     <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">&#39;:&#39;</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>

  749.     <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>

  750.         <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>

  751. </pre></div>

  752. </div>

  753. <p>The corresponding simplest possible writing example is:</p>

  754. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  755. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;some.csv&#39;</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  756.     <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>

  757.     <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>

  758. </pre></div>

  759. </div>

  760. <p>Since <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> is used to open a CSV file for reading, the file

  761. will by default be decoded into unicode using the system default

  762. encoding (see <a class="reference internal" href="locale.html#locale.getencoding" title="locale.getencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getencoding()</span></code></a>).  To decode a file

  763. using a different encoding, use the <code class="docutils literal notranslate"><span class="pre">encoding</span></code> argument of open:</p>

  764. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  765. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;some.csv&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s1">&#39;utf-8&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  766.     <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>

  767.     <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>

  768.         <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>

  769. </pre></div>

  770. </div>

  771. <p>The same applies to writing in something other than the system default

  772. encoding: specify the encoding argument when opening the output file.</p>

  773. <p>Registering a new dialect:</p>

  774. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  775. <span class="n">csv</span><span class="o">.</span><span class="n">register_dialect</span><span class="p">(</span><span class="s1">&#39;unixpwd&#39;</span><span class="p">,</span> <span class="n">delimiter</span><span class="o">=</span><span class="s1">&#39;:&#39;</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>

  776. <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">&#39;passwd&#39;</span><span class="p">,</span> <span class="n">newline</span><span class="o">=</span><span class="s1">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  777.     <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">&#39;unixpwd&#39;</span><span class="p">)</span>

  778. </pre></div>

  779. </div>

  780. <p>A slightly more advanced use of the reader — catching and reporting errors:</p>

  781. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span><span class="o">,</span> <span class="nn">sys</span>

  782. <span class="n">filename</span> <span class="o">=</span> <span class="s1">&#39;some.csv&#39;</span>

  783. <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">&#39;&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>

  784.     <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>

  785.     <span class="k">try</span><span class="p">:</span>

  786.         <span class="k">for</span> <span class="n">row</span> <span class="ow">in</span> <span class="n">reader</span><span class="p">:</span>

  787.             <span class="nb">print</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>

  788.     <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>

  789.         <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="s1">&#39;file </span><span class="si">{}</span><span class="s1">, line </span><span class="si">{}</span><span class="s1">: </span><span class="si">{}</span><span class="s1">&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">reader</span><span class="o">.</span><span class="n">line_num</span><span class="p">,</span> <span class="n">e</span><span class="p">))</span>

  790. </pre></div>

  791. </div>

  792. <p>And while the module doesn’t directly support parsing strings, it can easily be

  793. done:</p>

  794. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">csv</span>

  795. <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">&#39;one,two,three&#39;</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 class="rubric">Footnotes</p>

  800. <aside class="footnote-list brackets">

  801. <aside class="footnote brackets" id="id4" role="doc-footnote">

  802. <span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>

  803. <span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>)</span>

  804. <p>If <code class="docutils literal notranslate"><span class="pre">newline=''</span></code> is not specified, newlines embedded inside quoted fields

  805. will not be interpreted correctly, and on platforms that use <code class="docutils literal notranslate"><span class="pre">\r\n</span></code> linendings

  806. on write an extra <code class="docutils literal notranslate"><span class="pre">\r</span></code> will be added.  It should always be safe to specify

  807. <code class="docutils literal notranslate"><span class="pre">newline=''</span></code>, since the csv module does its own

  808. (<a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal</span></a>) newline handling.</p>

  809. </aside>

  810. </aside>

  811. </section>

  812. </section>

  813. 

  814. 

  815.             <div class="clearer"></div>

  816.           </div>

  817.         </div>

  818.       </div>

  819.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  820.         <div class="sphinxsidebarwrapper">

  821.   <div>

  822.     <h3><a href="../contents.html">Table of Contents</a></h3>

  823.     <ul>

  824. <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>

  825. <li><a class="reference internal" href="#module-contents">Module Contents</a></li>

  826. <li><a class="reference internal" href="#dialects-and-formatting-parameters">Dialects and Formatting Parameters</a></li>

  827. <li><a class="reference internal" href="#reader-objects">Reader Objects</a></li>

  828. <li><a class="reference internal" href="#writer-objects">Writer Objects</a></li>

  829. <li><a class="reference internal" href="#examples">Examples</a></li>

  830. </ul>

  831. </li>

  832. </ul>

  833. 

  834.   </div>

  835.   <div>

  836.     <h4>Previous topic</h4>

  837.     <p class="topless"><a href="fileformats.html"

  838.                           title="previous chapter">File Formats</a></p>

  839.   </div>

  840.   <div>

  841.     <h4>Next topic</h4>

  842.     <p class="topless"><a href="configparser.html"

  843.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></p>

  844.   </div>

  845.   <div role="note" aria-label="source link">

  846.     <h3>This Page</h3>

  847.     <ul class="this-page-menu">

  848.       <li><a href="../bugs.html">Report a Bug</a></li>

  849.       <li>

  850.         <a href="https://github.com/python/cpython/blob/main/Doc/library/csv.rst"

  851.             rel="nofollow">Show Source

  852.         </a>

  853.       </li>

  854.     </ul>

  855.   </div>

  856.         </div>

  857. <div id="sidebarbutton" title="Collapse sidebar">

  858. <span>«</span>

  859. </div>

  860. 

  861.       </div>

  862.       <div class="clearer"></div>

  863.     </div>  

  864.     <div class="related" role="navigation" aria-label="related navigation">

  865.       <h3>Navigation</h3>

  866.       <ul>

  867.         <li class="right" style="margin-right: 10px">

  868.           <a href="../genindex.html" title="General Index"

  869.              >index</a></li>

  870.         <li class="right" >

  871.           <a href="../py-modindex.html" title="Python Module Index"

  872.              >modules</a> |</li>

  873.         <li class="right" >

  874.           <a href="configparser.html" title="configparser — Configuration file parser"

  875.              >next</a> |</li>

  876.         <li class="right" >

  877.           <a href="fileformats.html" title="File Formats"

  878.              >previous</a> |</li>

  879. 

  880.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  881.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  882.           <li class="switchers">

  883.             <div class="language_switcher_placeholder"></div>

  884.             <div class="version_switcher_placeholder"></div>

  885.           </li>

  886.           <li>

  887.               

  888.           </li>

  889.     <li id="cpython-language-and-version">

  890.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  891.     </li>

  892. 

  893.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  894.           <li class="nav-item nav-item-2"><a href="fileformats.html" >File Formats</a> &#187;</li>

  895.         <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>

  896.                 <li class="right">

  897.                     

  898. 

  899.     <div class="inline-search" role="search">

  900.         <form class="inline-search" action="../search.html" method="get">

  901.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  902.           <input type="submit" value="Go" />

  903.         </form>

  904.     </div>

  905.                      |

  906.                 </li>

  907.             <li class="right">

  908. <label class="theme-selector-label">

  909.     Theme

  910.     <select class="theme-selector" oninput="activateTheme(this.value)">

  911.         <option value="auto" selected>Auto</option>

  912.         <option value="light">Light</option>

  913.         <option value="dark">Dark</option>

  914.     </select>

  915. </label> |</li>

  916.             

  917.       </ul>

  918.     </div>  

  919.     <div class="footer">

  920.     &copy; 

  921.       <a href="../copyright.html">

  922.     

  923.     Copyright

  924.     

  925.       </a>

  926.      2001-2024, Python Software Foundation.

  927.     <br />

  928.     This page is licensed under the Python Software Foundation License Version 2.

  929.     <br />

  930.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  931.     <br />

  932.     

  933.       See <a href="/license.html">History and License</a> for more information.<br />

  934.     

  935.     

  936.     <br />

  937. 

  938.     The Python Software Foundation is a non-profit corporation.

  939. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  940. <br />

  941.     <br />

  942.       Last updated on Apr 09, 2024 (13:47 UTC).

  943.     

  944.       <a href="/bugs.html">Found a bug</a>?

  945.     

  946.     <br />

  947. 

  948.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  949.     </div>

  950. 

  951.   </body>

  952. </html>
上海开阖软件有限公司 沪ICP备12045867号-1