mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2025-10-29 23:21:58 -06:00
1713 lines
173 KiB
HTML
1713 lines
173 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="configparser — Configuration file parser" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/library/configparser.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="Source code: Lib/configparser.py This module provides the ConfigParser class which implements a basic configuration language which provides a structure similar to what’s found in Microsoft Windows ..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="Source code: Lib/configparser.py This module provides the ConfigParser class which implements a basic configuration language which provides a structure similar to what’s found in Microsoft Windows ..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>configparser — Configuration file parser — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="tomllib — Parse TOML files" href="tomllib.html" />
|
||
<link rel="prev" title="csv — CSV File Reading and Writing" href="csv.html" />
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/library/configparser.html">
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
|
||
<input type="submit" value="Go"/>
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a><ul>
|
||
<li><a class="reference internal" href="#quick-start">Quick Start</a></li>
|
||
<li><a class="reference internal" href="#supported-datatypes">Supported Datatypes</a></li>
|
||
<li><a class="reference internal" href="#fallback-values">Fallback Values</a></li>
|
||
<li><a class="reference internal" href="#supported-ini-file-structure">Supported INI File Structure</a></li>
|
||
<li><a class="reference internal" href="#unnamed-sections">Unnamed Sections</a></li>
|
||
<li><a class="reference internal" href="#interpolation-of-values">Interpolation of values</a></li>
|
||
<li><a class="reference internal" href="#mapping-protocol-access">Mapping Protocol Access</a></li>
|
||
<li><a class="reference internal" href="#customizing-parser-behaviour">Customizing Parser Behaviour</a></li>
|
||
<li><a class="reference internal" href="#legacy-api-examples">Legacy API Examples</a></li>
|
||
<li><a class="reference internal" href="#configparser-objects">ConfigParser Objects</a></li>
|
||
<li><a class="reference internal" href="#rawconfigparser-objects">RawConfigParser Objects</a></li>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="csv.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="tomllib.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/library/configparser.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="tomllib.html" title="tomllib — Parse TOML files"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="csv.html" title="csv — CSV File Reading and Writing"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">File Formats</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-configparser">
|
||
<span id="configparser-configuration-file-parser"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser<a class="headerlink" href="#module-configparser" title="Link to this heading">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/3.13/Lib/configparser.py">Lib/configparser.py</a></p>
|
||
<hr class="docutils" id="index-0" />
|
||
<p>This module provides the <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> class which implements a basic
|
||
configuration language which provides a structure similar to what’s found in
|
||
Microsoft Windows INI files. You can use this to write Python programs which
|
||
can be customized by end users easily.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This library does <em>not</em> interpret or write the value-type prefixes used in
|
||
the Windows Registry extended version of INI syntax.</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt>Module <a class="reference internal" href="tomllib.html#module-tomllib" title="tomllib: Parse TOML files."><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code></a></dt><dd><p>TOML is a well-specified format for application configuration files.
|
||
It is specifically designed to be an improved version of INI.</p>
|
||
</dd>
|
||
<dt>Module <a class="reference internal" href="shlex.html#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a></dt><dd><p>Support for creating Unix shell-like mini-languages which can also
|
||
be used for application configuration files.</p>
|
||
</dd>
|
||
<dt>Module <a class="reference internal" href="json.html#module-json" title="json: Encode and decode the JSON format."><code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code></a></dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">json</span></code> module implements a subset of JavaScript syntax which is
|
||
sometimes used for configuration, but does not support comments.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<section id="quick-start">
|
||
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Link to this heading">¶</a></h2>
|
||
<p>Let’s take a very basic configuration file that looks like this:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[DEFAULT]</span>
|
||
<span class="na">ServerAliveInterval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">45</span>
|
||
<span class="na">Compression</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
|
||
<span class="na">CompressionLevel</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">9</span>
|
||
<span class="na">ForwardX11</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">yes</span>
|
||
|
||
<span class="k">[forge.example]</span>
|
||
<span class="na">User</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">hg</span>
|
||
|
||
<span class="k">[topsecret.server.example]</span>
|
||
<span class="na">Port</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">50022</span>
|
||
<span class="na">ForwardX11</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">no</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The structure of INI files is described <a class="reference external" href="#supported-ini-file-structure">in the following section</a>. Essentially, the file
|
||
consists of sections, each of which contains keys with values.
|
||
<a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> classes can read and write such files. Let’s start by
|
||
creating the above configuration file programmatically.</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span>
|
||
<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'ServerAliveInterval'</span><span class="p">:</span> <span class="s1">'45'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'Compression'</span><span class="p">:</span> <span class="s1">'yes'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'CompressionLevel'</span><span class="p">:</span> <span class="s1">'9'</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'forge.example'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'forge.example'</span><span class="p">][</span><span class="s1">'User'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'hg'</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'topsecret.server.example'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s1">'topsecret.server.example'</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'Port'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'50022'</span> <span class="c1"># mutates the parser</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'ForwardX11'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'no'</span> <span class="c1"># same here</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">][</span><span class="s1">'ForwardX11'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'yes'</span>
|
||
<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'example.ini'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">configfile</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">configfile</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As you can see, we can treat a config parser much like a dictionary.
|
||
There are differences, <a class="reference external" href="#mapping-protocol-access">outlined later</a>, but
|
||
the behavior is very close to what you would expect from a dictionary.</p>
|
||
<p>Now that we have created and saved a configuration file, let’s read it
|
||
back and explore the data it holds.</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">[]</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.ini'</span><span class="p">)</span>
|
||
<span class="go">['example.ini']</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['forge.example', 'topsecret.server.example']</span>
|
||
<span class="gp">>>> </span><span class="s1">'forge.example'</span> <span class="ow">in</span> <span class="n">config</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="s1">'python.org'</span> <span class="ow">in</span> <span class="n">config</span>
|
||
<span class="go">False</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'forge.example'</span><span class="p">][</span><span class="s1">'User'</span><span class="p">]</span>
|
||
<span class="go">'hg'</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">][</span><span class="s1">'Compression'</span><span class="p">]</span>
|
||
<span class="go">'yes'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s1">'topsecret.server.example'</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'ForwardX11'</span><span class="p">]</span>
|
||
<span class="go">'no'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'Port'</span><span class="p">]</span>
|
||
<span class="go">'50022'</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">config</span><span class="p">[</span><span class="s1">'forge.example'</span><span class="p">]:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
|
||
<span class="go">user</span>
|
||
<span class="go">compressionlevel</span>
|
||
<span class="go">serveraliveinterval</span>
|
||
<span class="go">compression</span>
|
||
<span class="go">forwardx11</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'forge.example'</span><span class="p">][</span><span class="s1">'ForwardX11'</span><span class="p">]</span>
|
||
<span class="go">'yes'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As we can see above, the API is pretty straightforward. The only bit of magic
|
||
involves the <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> section which provides default values for all other
|
||
sections <a class="footnote-reference brackets" href="#id16" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. Note also that keys in sections are
|
||
case-insensitive and stored in lowercase <a class="footnote-reference brackets" href="#id16" id="id2" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>.</p>
|
||
<p>It is possible to read several configurations into a single
|
||
<a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>, where the most recently added configuration has the
|
||
highest priority. Any conflicting keys are taken from the more recent
|
||
configuration while the previously existing keys are retained. The example
|
||
below reads in an <code class="docutils literal notranslate"><span class="pre">override.ini</span></code> file, which will override any conflicting
|
||
keys from the <code class="docutils literal notranslate"><span class="pre">example.ini</span></code> file.</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[DEFAULT]</span>
|
||
<span class="na">ServerAliveInterval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">-1</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config_override</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config_override</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'ServerAliveInterval'</span><span class="p">:</span> <span class="s1">'-1'</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'override.ini'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">configfile</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">config_override</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">configfile</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">config_override</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config_override</span><span class="o">.</span><span class="n">read</span><span class="p">([</span><span class="s1">'example.ini'</span><span class="p">,</span> <span class="s1">'override.ini'</span><span class="p">])</span>
|
||
<span class="go">['example.ini', 'override.ini']</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">config_override</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'DEFAULT'</span><span class="p">,</span> <span class="s1">'ServerAliveInterval'</span><span class="p">))</span>
|
||
<span class="go">-1</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This behaviour is equivalent to a <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConfigParser.read()</span></code></a> call with several
|
||
files passed to the <em>filenames</em> parameter.</p>
|
||
</section>
|
||
<section id="supported-datatypes">
|
||
<h2>Supported Datatypes<a class="headerlink" href="#supported-datatypes" title="Link to this heading">¶</a></h2>
|
||
<p>Config parsers do not guess datatypes of values in configuration files, always
|
||
storing them internally as strings. This means that if you need other
|
||
datatypes, you should convert on your own:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">int</span><span class="p">(</span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'Port'</span><span class="p">])</span>
|
||
<span class="go">50022</span>
|
||
<span class="gp">>>> </span><span class="nb">float</span><span class="p">(</span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'CompressionLevel'</span><span class="p">])</span>
|
||
<span class="go">9.0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Since this task is so common, config parsers provide a range of handy getter
|
||
methods to handle integers, floats and booleans. The last one is the most
|
||
interesting because simply passing the value to <code class="docutils literal notranslate"><span class="pre">bool()</span></code> would do no good
|
||
since <code class="docutils literal notranslate"><span class="pre">bool('False')</span></code> is still <code class="docutils literal notranslate"><span class="pre">True</span></code>. This is why config parsers also
|
||
provide <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a>. This method is case-insensitive and
|
||
recognizes Boolean values from <code class="docutils literal notranslate"><span class="pre">'yes'</span></code>/<code class="docutils literal notranslate"><span class="pre">'no'</span></code>, <code class="docutils literal notranslate"><span class="pre">'on'</span></code>/<code class="docutils literal notranslate"><span class="pre">'off'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'true'</span></code>/<code class="docutils literal notranslate"><span class="pre">'false'</span></code> and <code class="docutils literal notranslate"><span class="pre">'1'</span></code>/<code class="docutils literal notranslate"><span class="pre">'0'</span></code> <a class="footnote-reference brackets" href="#id16" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. For example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'ForwardX11'</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'forge.example'</span><span class="p">]</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'ForwardX11'</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'forge.example'</span><span class="p">,</span> <span class="s1">'Compression'</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Apart from <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a>, config parsers also
|
||
provide equivalent <a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getint()</span></code></a> and
|
||
<a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getfloat()</span></code></a> methods. You can register your own
|
||
converters and customize the provided ones. <a class="footnote-reference brackets" href="#id16" id="id4" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>
|
||
</section>
|
||
<section id="fallback-values">
|
||
<h2>Fallback Values<a class="headerlink" href="#fallback-values" title="Link to this heading">¶</a></h2>
|
||
<p>As with a dictionary, you can use a section’s <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> method to
|
||
provide fallback values:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Port'</span><span class="p">)</span>
|
||
<span class="go">'50022'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'CompressionLevel'</span><span class="p">)</span>
|
||
<span class="go">'9'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Cipher'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Cipher'</span><span class="p">,</span> <span class="s1">'3des-cbc'</span><span class="p">)</span>
|
||
<span class="go">'3des-cbc'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Please note that default values have precedence over fallback values.
|
||
For instance, in our example the <code class="docutils literal notranslate"><span class="pre">'CompressionLevel'</span></code> key was
|
||
specified only in the <code class="docutils literal notranslate"><span class="pre">'DEFAULT'</span></code> section. If we try to get it from
|
||
the section <code class="docutils literal notranslate"><span class="pre">'topsecret.server.example'</span></code>, we will always get the default,
|
||
even if we specify a fallback:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'CompressionLevel'</span><span class="p">,</span> <span class="s1">'3'</span><span class="p">)</span>
|
||
<span class="go">'9'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>One more thing to be aware of is that the parser-level <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> method
|
||
provides a custom, more complex interface, maintained for backwards
|
||
compatibility. When using this method, a fallback value can be provided via
|
||
the <code class="docutils literal notranslate"><span class="pre">fallback</span></code> keyword-only argument:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'forge.example'</span><span class="p">,</span> <span class="s1">'monster'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">fallback</span><span class="o">=</span><span class="s1">'No such things as monsters'</span><span class="p">)</span>
|
||
<span class="go">'No such things as monsters'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The same <code class="docutils literal notranslate"><span class="pre">fallback</span></code> argument can be used with the
|
||
<a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getint()</span></code></a>, <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getfloat()</span></code></a> and
|
||
<a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a> methods, for example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="s1">'BatchMode'</span> <span class="ow">in</span> <span class="n">topsecret</span>
|
||
<span class="go">False</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'BatchMode'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">][</span><span class="s1">'BatchMode'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'no'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'BatchMode'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="supported-ini-file-structure">
|
||
<h2>Supported INI File Structure<a class="headerlink" href="#supported-ini-file-structure" title="Link to this heading">¶</a></h2>
|
||
<p>A configuration file consists of sections, each led by a <code class="docutils literal notranslate"><span class="pre">[section]</span></code> header,
|
||
followed by key/value entries separated by a specific string (<code class="docutils literal notranslate"><span class="pre">=</span></code> or <code class="docutils literal notranslate"><span class="pre">:</span></code> by
|
||
default <a class="footnote-reference brackets" href="#id16" id="id5" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>). By default, section names are case sensitive but keys are not
|
||
<a class="footnote-reference brackets" href="#id16" id="id6" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. Leading and trailing whitespace is removed from keys and values.
|
||
Values can be omitted if the parser is configured to allow it <a class="footnote-reference brackets" href="#id16" id="id7" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>,
|
||
in which case the key/value delimiter may also be left
|
||
out. Values can also span multiple lines, as long as they are indented deeper
|
||
than the first line of the value. Depending on the parser’s mode, blank lines
|
||
may be treated as parts of multiline values or ignored.</p>
|
||
<p>By default, a valid section name can be any string that does not contain ‘\n’.
|
||
To change this, see <a class="reference internal" href="#configparser.ConfigParser.SECTCRE" title="configparser.ConfigParser.SECTCRE"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ConfigParser.SECTCRE</span></code></a>.</p>
|
||
<p>The first section name may be omitted if the parser is configured to allow an
|
||
unnamed top level section with <code class="docutils literal notranslate"><span class="pre">allow_unnamed_section=True</span></code>. In this case,
|
||
the keys/values may be retrieved by <a class="reference internal" href="#configparser.UNNAMED_SECTION" title="configparser.UNNAMED_SECTION"><code class="xref py py-const docutils literal notranslate"><span class="pre">UNNAMED_SECTION</span></code></a> as in
|
||
<code class="docutils literal notranslate"><span class="pre">config[UNNAMED_SECTION]</span></code>.</p>
|
||
<p>Configuration files may include comments, prefixed by specific
|
||
characters (<code class="docutils literal notranslate"><span class="pre">#</span></code> and <code class="docutils literal notranslate"><span class="pre">;</span></code> by default <a class="footnote-reference brackets" href="#id16" id="id8" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>). Comments may appear on
|
||
their own on an otherwise empty line, possibly indented. <a class="footnote-reference brackets" href="#id16" id="id9" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a></p>
|
||
<p>For example:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Simple Values]</span>
|
||
<span class="na">key</span><span class="o">=</span><span class="s">value</span>
|
||
<span class="na">spaces in keys</span><span class="o">=</span><span class="s">allowed</span>
|
||
<span class="na">spaces in values</span><span class="o">=</span><span class="s">allowed as well</span>
|
||
<span class="na">spaces around the delimiter</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">obviously</span>
|
||
<span class="na">you can also use</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="s">to delimit keys from values</span>
|
||
|
||
<span class="k">[All Values Are Strings]</span>
|
||
<span class="na">values like this</span><span class="o">:</span><span class="w"> </span><span class="s">1000000</span>
|
||
<span class="na">or this</span><span class="o">:</span><span class="w"> </span><span class="s">3.14159265359</span>
|
||
<span class="na">are they treated as numbers?</span><span class="w"> </span><span class="o">:</span><span class="w"> </span><span class="s">no</span>
|
||
<span class="na">integers, floats and booleans are held as</span><span class="o">:</span><span class="w"> </span><span class="s">strings</span>
|
||
<span class="na">can use the API to get converted values directly</span><span class="o">:</span><span class="w"> </span><span class="s">true</span>
|
||
|
||
<span class="k">[Multiline Values]</span>
|
||
<span class="na">chorus</span><span class="o">:</span><span class="w"> </span><span class="s">I'm a lumberjack, and I'm okay</span>
|
||
<span class="w"> </span><span class="na">I sleep all night and I work all day</span>
|
||
|
||
<span class="k">[No Values]</span>
|
||
<span class="na">key_without_value</span>
|
||
<span class="na">empty string value here</span><span class="w"> </span><span class="o">=</span>
|
||
|
||
<span class="k">[You can use comments]</span>
|
||
<span class="c1"># like this</span>
|
||
<span class="c1">; or this</span>
|
||
|
||
<span class="c1"># By default only in an empty line.</span>
|
||
<span class="c1"># Inline comments can be harmful because they prevent users</span>
|
||
<span class="c1"># from using the delimiting characters as parts of values.</span>
|
||
<span class="c1"># That being said, this can be customized.</span>
|
||
|
||
<span class="w"> </span><span class="k">[Sections Can Be Indented]</span>
|
||
<span class="w"> </span><span class="na">can_values_be_as_well</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">True</span>
|
||
<span class="w"> </span><span class="na">does_that_mean_anything_special</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">False</span>
|
||
<span class="w"> </span><span class="na">purpose</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">formatting for readability</span>
|
||
<span class="w"> </span><span class="na">multiline_values</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">are</span>
|
||
<span class="w"> </span><span class="na">handled just fine as</span>
|
||
<span class="w"> </span><span class="na">long as they are indented</span>
|
||
<span class="w"> </span><span class="na">deeper than the first line</span>
|
||
<span class="w"> </span><span class="na">of a value</span>
|
||
<span class="w"> </span><span class="c1"># Did I mention we can indent comments, too?</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="unnamed-sections">
|
||
<span id="id10"></span><h2>Unnamed Sections<a class="headerlink" href="#unnamed-sections" title="Link to this heading">¶</a></h2>
|
||
<p>The name of the first section (or unique) may be omitted and values
|
||
retrieved by the <a class="reference internal" href="#configparser.UNNAMED_SECTION" title="configparser.UNNAMED_SECTION"><code class="xref py py-const docutils literal notranslate"><span class="pre">UNNAMED_SECTION</span></code></a> attribute.</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">option = value</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">... </span><span class="s2">[ Section 2 ]</span>
|
||
<span class="gp">... </span><span class="s2">another = val</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">unnamed</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">(</span><span class="n">allow_unnamed_section</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">unnamed</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">unnamed</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">configparser</span><span class="o">.</span><span class="n">UNNAMED_SECTION</span><span class="p">,</span> <span class="s1">'option'</span><span class="p">)</span>
|
||
<span class="go">'value'</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="interpolation-of-values">
|
||
<h2>Interpolation of values<a class="headerlink" href="#interpolation-of-values" title="Link to this heading">¶</a></h2>
|
||
<p>On top of the core functionality, <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> supports
|
||
interpolation. This means values can be preprocessed before returning them
|
||
from <code class="docutils literal notranslate"><span class="pre">get()</span></code> calls.</p>
|
||
<dl class="py class" id="index-1">
|
||
<dt class="sig sig-object py" id="configparser.BasicInterpolation">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">BasicInterpolation</span></span><a class="headerlink" href="#configparser.BasicInterpolation" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The default implementation used by <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>. It enables
|
||
values to contain format strings which refer to other values in the same
|
||
section, or values in the special default section <a class="footnote-reference brackets" href="#id16" id="id11" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. Additional default
|
||
values can be provided on initialization.</p>
|
||
<p>For example:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Paths]</span>
|
||
<span class="na">home_dir</span><span class="o">:</span><span class="w"> </span><span class="s">/Users</span>
|
||
<span class="na">my_dir</span><span class="o">:</span><span class="w"> </span><span class="s">%(home_dir)s/lumberjack</span>
|
||
<span class="na">my_pictures</span><span class="o">:</span><span class="w"> </span><span class="s">%(my_dir)s/Pictures</span>
|
||
|
||
<span class="k">[Escape]</span>
|
||
<span class="c1"># use a %% to escape the % sign (% is the only character that needs to be escaped):</span>
|
||
<span class="na">gain</span><span class="o">:</span><span class="w"> </span><span class="s">80%%</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the example above, <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> with <em>interpolation</em> set to
|
||
<code class="docutils literal notranslate"><span class="pre">BasicInterpolation()</span></code> would resolve <code class="docutils literal notranslate"><span class="pre">%(home_dir)s</span></code> to the value of
|
||
<code class="docutils literal notranslate"><span class="pre">home_dir</span></code> (<code class="docutils literal notranslate"><span class="pre">/Users</span></code> in this case). <code class="docutils literal notranslate"><span class="pre">%(my_dir)s</span></code> in effect would
|
||
resolve to <code class="docutils literal notranslate"><span class="pre">/Users/lumberjack</span></code>. All interpolations are done on demand so
|
||
keys used in the chain of references do not have to be specified in any
|
||
specific order in the configuration file.</p>
|
||
<p>With <code class="docutils literal notranslate"><span class="pre">interpolation</span></code> set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, the parser would simply return
|
||
<code class="docutils literal notranslate"><span class="pre">%(my_dir)s/Pictures</span></code> as the value of <code class="docutils literal notranslate"><span class="pre">my_pictures</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">%(home_dir)s/lumberjack</span></code> as the value of <code class="docutils literal notranslate"><span class="pre">my_dir</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py class" id="index-2">
|
||
<dt class="sig sig-object py" id="configparser.ExtendedInterpolation">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">ExtendedInterpolation</span></span><a class="headerlink" href="#configparser.ExtendedInterpolation" title="Link to this definition">¶</a></dt>
|
||
<dd><p>An alternative handler for interpolation which implements a more advanced
|
||
syntax, used for instance in <code class="docutils literal notranslate"><span class="pre">zc.buildout</span></code>. Extended interpolation is
|
||
using <code class="docutils literal notranslate"><span class="pre">${section:option}</span></code> to denote a value from a foreign section.
|
||
Interpolation can span multiple levels. For convenience, if the
|
||
<code class="docutils literal notranslate"><span class="pre">section:</span></code> part is omitted, interpolation defaults to the current section
|
||
(and possibly the default values from the special section).</p>
|
||
<p>For example, the configuration specified above with basic interpolation,
|
||
would look like this with extended interpolation:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Paths]</span>
|
||
<span class="na">home_dir</span><span class="o">:</span><span class="w"> </span><span class="s">/Users</span>
|
||
<span class="na">my_dir</span><span class="o">:</span><span class="w"> </span><span class="s">${home_dir}/lumberjack</span>
|
||
<span class="na">my_pictures</span><span class="o">:</span><span class="w"> </span><span class="s">${my_dir}/Pictures</span>
|
||
|
||
<span class="k">[Escape]</span>
|
||
<span class="c1"># use a $$ to escape the $ sign ($ is the only character that needs to be escaped):</span>
|
||
<span class="na">cost</span><span class="o">:</span><span class="w"> </span><span class="s">$$80</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Values from other sections can be fetched as well:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Common]</span>
|
||
<span class="na">home_dir</span><span class="o">:</span><span class="w"> </span><span class="s">/Users</span>
|
||
<span class="na">library_dir</span><span class="o">:</span><span class="w"> </span><span class="s">/Library</span>
|
||
<span class="na">system_dir</span><span class="o">:</span><span class="w"> </span><span class="s">/System</span>
|
||
<span class="na">macports_dir</span><span class="o">:</span><span class="w"> </span><span class="s">/opt/local</span>
|
||
|
||
<span class="k">[Frameworks]</span>
|
||
<span class="na">Python</span><span class="o">:</span><span class="w"> </span><span class="s">3.2</span>
|
||
<span class="na">path</span><span class="o">:</span><span class="w"> </span><span class="s">${Common:system_dir}/Library/Frameworks/</span>
|
||
|
||
<span class="k">[Arthur]</span>
|
||
<span class="na">nickname</span><span class="o">:</span><span class="w"> </span><span class="s">Two Sheds</span>
|
||
<span class="na">last_name</span><span class="o">:</span><span class="w"> </span><span class="s">Jackson</span>
|
||
<span class="na">my_dir</span><span class="o">:</span><span class="w"> </span><span class="s">${Common:home_dir}/twosheds</span>
|
||
<span class="na">my_pictures</span><span class="o">:</span><span class="w"> </span><span class="s">${my_dir}/Pictures</span>
|
||
<span class="na">python_dir</span><span class="o">:</span><span class="w"> </span><span class="s">${Frameworks:path}/Python/Versions/${Frameworks:Python}</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="mapping-protocol-access">
|
||
<h2>Mapping Protocol Access<a class="headerlink" href="#mapping-protocol-access" title="Link to this heading">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</div>
|
||
<p>Mapping protocol access is a generic name for functionality that enables using
|
||
custom objects as if they were dictionaries. In case of <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a>,
|
||
the mapping interface implementation is using the
|
||
<code class="docutils literal notranslate"><span class="pre">parser['section']['option']</span></code> notation.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">parser['section']</span></code> in particular returns a proxy for the section’s data in
|
||
the parser. This means that the values are not copied but they are taken from
|
||
the original parser on demand. What’s even more important is that when values
|
||
are changed on a section proxy, they are actually mutated in the original
|
||
parser.</p>
|
||
<p><a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> objects behave as close to actual dictionaries as possible.
|
||
The mapping interface is complete and adheres to the
|
||
<a class="reference internal" href="collections.abc.html#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableMapping</span></code></a> ABC.
|
||
However, there are a few differences that should be taken into account:</p>
|
||
<ul>
|
||
<li><p>By default, all keys in sections are accessible in a case-insensitive manner
|
||
<a class="footnote-reference brackets" href="#id16" id="id12" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. E.g. <code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">option</span> <span class="pre">in</span> <span class="pre">parser["section"]</span></code> yields only <code class="docutils literal notranslate"><span class="pre">optionxform</span></code>’ed
|
||
option key names. This means lowercased keys by default. At the same time,
|
||
for a section that holds the key <code class="docutils literal notranslate"><span class="pre">'a'</span></code>, both expressions return <code class="docutils literal notranslate"><span class="pre">True</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s2">"a"</span> <span class="ow">in</span> <span class="n">parser</span><span class="p">[</span><span class="s2">"section"</span><span class="p">]</span>
|
||
<span class="s2">"A"</span> <span class="ow">in</span> <span class="n">parser</span><span class="p">[</span><span class="s2">"section"</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>All sections include <code class="docutils literal notranslate"><span class="pre">DEFAULTSECT</span></code> values as well which means that
|
||
<code class="docutils literal notranslate"><span class="pre">.clear()</span></code> on a section may not leave the section visibly empty. This is
|
||
because default values cannot be deleted from the section (because technically
|
||
they are not there). If they are overridden in the section, deleting causes
|
||
the default value to be visible again. Trying to delete a default value
|
||
causes a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">DEFAULTSECT</span></code> cannot be removed from the parser:</p>
|
||
<ul class="simple">
|
||
<li><p>trying to delete it raises <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>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.clear()</span></code> leaves it intact,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.popitem()</span></code> never returns it.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.get(section,</span> <span class="pre">option,</span> <span class="pre">**kwargs)</span></code> - the second argument is <strong>not</strong>
|
||
a fallback value. Note however that the section-level <code class="docutils literal notranslate"><span class="pre">get()</span></code> methods are
|
||
compatible both with the mapping protocol and the classic configparser API.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.items()</span></code> is compatible with the mapping protocol (returns a list of
|
||
<em>section_name</em>, <em>section_proxy</em> pairs including the DEFAULTSECT). However,
|
||
this method can also be invoked with arguments: <code class="docutils literal notranslate"><span class="pre">parser.items(section,</span> <span class="pre">raw,</span>
|
||
<span class="pre">vars)</span></code>. The latter call returns a list of <em>option</em>, <em>value</em> pairs for
|
||
a specified <code class="docutils literal notranslate"><span class="pre">section</span></code>, with all interpolations expanded (unless
|
||
<code class="docutils literal notranslate"><span class="pre">raw=True</span></code> is provided).</p></li>
|
||
</ul>
|
||
<p>The mapping protocol is implemented on top of the existing legacy API so that
|
||
subclasses overriding the original interface still should have mappings working
|
||
as expected.</p>
|
||
</section>
|
||
<section id="customizing-parser-behaviour">
|
||
<h2>Customizing Parser Behaviour<a class="headerlink" href="#customizing-parser-behaviour" title="Link to this heading">¶</a></h2>
|
||
<p>There are nearly as many INI format variants as there are applications using it.
|
||
<a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> goes a long way to provide support for the largest sensible
|
||
set of INI styles available. The default functionality is mainly dictated by
|
||
historical background and it’s very likely that you will want to customize some
|
||
of the features.</p>
|
||
<p>The most common way to change the way a specific config parser works is to use
|
||
the <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> options:</p>
|
||
<ul>
|
||
<li><p><em>defaults</em>, default value: <code class="docutils literal notranslate"><span class="pre">None</span></code></p>
|
||
<p>This option accepts a dictionary of key-value pairs which will be initially
|
||
put in the <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> section. This makes for an elegant way to support
|
||
concise configuration files that don’t specify values which are the same as
|
||
the documented default.</p>
|
||
<p>Hint: if you want to specify default values for a specific section, use
|
||
<a class="reference internal" href="#configparser.ConfigParser.read_dict" title="configparser.ConfigParser.read_dict"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_dict()</span></code></a> before you read the actual file.</p>
|
||
</li>
|
||
<li><p><em>dict_type</em>, default value: <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>
|
||
<p>This option has a major impact on how the mapping protocol will behave and how
|
||
the written configuration files look. With the standard dictionary, every
|
||
section is stored in the order they were added to the parser. Same goes for
|
||
options within sections.</p>
|
||
<p>An alternative dictionary type can be used for example to sort sections and
|
||
options on write-back.</p>
|
||
<p>Please note: there are ways to add a set of key-value pairs in a single
|
||
operation. When you use a regular dictionary in those operations, the order
|
||
of the keys will be ordered. For example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">read_dict</span><span class="p">({</span><span class="s1">'section1'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'key1'</span><span class="p">:</span> <span class="s1">'value1'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'key2'</span><span class="p">:</span> <span class="s1">'value2'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'key3'</span><span class="p">:</span> <span class="s1">'value3'</span><span class="p">},</span>
|
||
<span class="gp">... </span> <span class="s1">'section2'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'keyA'</span><span class="p">:</span> <span class="s1">'valueA'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'keyB'</span><span class="p">:</span> <span class="s1">'valueB'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'keyC'</span><span class="p">:</span> <span class="s1">'valueC'</span><span class="p">},</span>
|
||
<span class="gp">... </span> <span class="s1">'section3'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'x'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'y'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'baz'</span><span class="p">:</span> <span class="s1">'z'</span><span class="p">}</span>
|
||
<span class="gp">... </span><span class="p">})</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['section1', 'section2', 'section3']</span>
|
||
<span class="gp">>>> </span><span class="p">[</span><span class="n">option</span> <span class="k">for</span> <span class="n">option</span> <span class="ow">in</span> <span class="n">parser</span><span class="p">[</span><span class="s1">'section3'</span><span class="p">]]</span>
|
||
<span class="go">['foo', 'bar', 'baz']</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em>allow_no_value</em>, default value: <code class="docutils literal notranslate"><span class="pre">False</span></code></p>
|
||
<p>Some configuration files are known to include settings without values, but
|
||
which otherwise conform to the syntax supported by <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a>. The
|
||
<em>allow_no_value</em> parameter to the constructor can be used to
|
||
indicate that such values should be accepted:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">sample_config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[mysqld]</span>
|
||
<span class="gp">... </span><span class="s2"> user = mysql</span>
|
||
<span class="gp">... </span><span class="s2"> pid-file = /var/run/mysqld/mysqld.pid</span>
|
||
<span class="gp">... </span><span class="s2"> skip-external-locking</span>
|
||
<span class="gp">... </span><span class="s2"> old_passwords = 1</span>
|
||
<span class="gp">... </span><span class="s2"> skip-bdb</span>
|
||
<span class="gp">... </span><span class="s2"> # we don't need ACID today</span>
|
||
<span class="gp">... </span><span class="s2"> skip-innodb</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">(</span><span class="n">allow_no_value</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">sample_config</span><span class="p">)</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Settings with values are treated as before:</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s2">"mysqld"</span><span class="p">][</span><span class="s2">"user"</span><span class="p">]</span>
|
||
<span class="go">'mysql'</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Settings without values provide None:</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s2">"mysqld"</span><span class="p">][</span><span class="s2">"skip-bdb"</span><span class="p">]</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Settings which aren't specified still raise an error:</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s2">"mysqld"</span><span class="p">][</span><span class="s2">"does-not-exist"</span><span class="p">]</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">KeyError</span>: <span class="n">'does-not-exist'</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em>delimiters</em>, default value: <code class="docutils literal notranslate"><span class="pre">('=',</span> <span class="pre">':')</span></code></p>
|
||
<p>Delimiters are substrings that delimit keys from values within a section.
|
||
The first occurrence of a delimiting substring on a line is considered
|
||
a delimiter. This means values (but not keys) can contain the delimiters.</p>
|
||
<p>See also the <em>space_around_delimiters</em> argument to
|
||
<a class="reference internal" href="#configparser.ConfigParser.write" title="configparser.ConfigParser.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConfigParser.write()</span></code></a>.</p>
|
||
</li>
|
||
<li><p><em>comment_prefixes</em>, default value: <code class="docutils literal notranslate"><span class="pre">('#',</span> <span class="pre">';')</span></code></p></li>
|
||
<li><p><em>inline_comment_prefixes</em>, default value: <code class="docutils literal notranslate"><span class="pre">None</span></code></p>
|
||
<p>Comment prefixes are strings that indicate the start of a valid comment within
|
||
a config file. <em>comment_prefixes</em> are used only on otherwise empty lines
|
||
(optionally indented) whereas <em>inline_comment_prefixes</em> can be used after
|
||
every valid value (e.g. section names, options and empty lines as well). By
|
||
default inline comments are disabled and <code class="docutils literal notranslate"><span class="pre">'#'</span></code> and <code class="docutils literal notranslate"><span class="pre">';'</span></code> are used as
|
||
prefixes for whole line comments.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions of <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> behaviour matched
|
||
<code class="docutils literal notranslate"><span class="pre">comment_prefixes=('#',';')</span></code> and <code class="docutils literal notranslate"><span class="pre">inline_comment_prefixes=(';',)</span></code>.</p>
|
||
</div>
|
||
<p>Please note that config parsers don’t support escaping of comment prefixes so
|
||
using <em>inline_comment_prefixes</em> may prevent users from specifying option
|
||
values with characters used as comment prefixes. When in doubt, avoid
|
||
setting <em>inline_comment_prefixes</em>. In any circumstances, the only way of
|
||
storing comment prefix characters at the beginning of a line in multiline
|
||
values is to interpolate the prefix, for example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">configparser</span><span class="w"> </span><span class="kn">import</span> <span class="n">ConfigParser</span><span class="p">,</span> <span class="n">ExtendedInterpolation</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">ConfigParser</span><span class="p">(</span><span class="n">interpolation</span><span class="o">=</span><span class="n">ExtendedInterpolation</span><span class="p">())</span>
|
||
<span class="gp">>>> </span><span class="c1"># the default BasicInterpolation could be used as well</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[DEFAULT]</span>
|
||
<span class="gp">... </span><span class="s2">hash = #</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">... </span><span class="s2">[hashes]</span>
|
||
<span class="gp">... </span><span class="s2">shebang =</span>
|
||
<span class="gp">... </span><span class="s2"> $</span><span class="si">{hash}</span><span class="s2">!/usr/bin/env python</span>
|
||
<span class="gp">... </span><span class="s2"> $</span><span class="si">{hash}</span><span class="s2"> -*- coding: utf-8 -*-</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">... </span><span class="s2">extensions =</span>
|
||
<span class="gp">... </span><span class="s2"> enabled_extension</span>
|
||
<span class="gp">... </span><span class="s2"> another_extension</span>
|
||
<span class="gp">... </span><span class="s2"> #disabled_by_comment</span>
|
||
<span class="gp">... </span><span class="s2"> yet_another_extension</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">... </span><span class="s2">interpolation not necessary = if # is not at line start</span>
|
||
<span class="gp">... </span><span class="s2">even in multiline values = line #1</span>
|
||
<span class="gp">... </span><span class="s2"> line #2</span>
|
||
<span class="gp">... </span><span class="s2"> line #3</span>
|
||
<span class="gp">... </span><span class="s2">"""</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'shebang'</span><span class="p">])</span>
|
||
|
||
<span class="go">#!/usr/bin/env python</span>
|
||
<span class="go"># -*- coding: utf-8 -*-</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'extensions'</span><span class="p">])</span>
|
||
|
||
<span class="go">enabled_extension</span>
|
||
<span class="go">another_extension</span>
|
||
<span class="go">yet_another_extension</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'interpolation not necessary'</span><span class="p">])</span>
|
||
<span class="go">if # is not at line start</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'even in multiline values'</span><span class="p">])</span>
|
||
<span class="go">line #1</span>
|
||
<span class="go">line #2</span>
|
||
<span class="go">line #3</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em>strict</em>, default value: <code class="docutils literal notranslate"><span class="pre">True</span></code></p>
|
||
<p>When set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, the parser will not allow for any section or option
|
||
duplicates while reading from a single source (using <a class="reference internal" href="#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_file()</span></code></a>,
|
||
<a class="reference internal" href="#configparser.ConfigParser.read_string" title="configparser.ConfigParser.read_string"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_string()</span></code></a> or <a class="reference internal" href="#configparser.ConfigParser.read_dict" title="configparser.ConfigParser.read_dict"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_dict()</span></code></a>). It is recommended to use strict
|
||
parsers in new applications.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions of <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> behaviour matched
|
||
<code class="docutils literal notranslate"><span class="pre">strict=False</span></code>.</p>
|
||
</div>
|
||
</li>
|
||
<li><p><em>empty_lines_in_values</em>, default value: <code class="docutils literal notranslate"><span class="pre">True</span></code></p>
|
||
<p>In config parsers, values can span multiple lines as long as they are
|
||
indented more than the key that holds them. By default parsers also let
|
||
empty lines to be parts of values. At the same time, keys can be arbitrarily
|
||
indented themselves to improve readability. In consequence, when
|
||
configuration files get big and complex, it is easy for the user to lose
|
||
track of the file structure. Take for instance:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Section]</span>
|
||
<span class="na">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">multiline</span>
|
||
<span class="w"> </span><span class="na">value with a gotcha</span>
|
||
|
||
<span class="w"> </span><span class="na">this</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">is still a part of the multiline value of 'key'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This can be especially problematic for the user to see if she’s using a
|
||
proportional font to edit the file. That is why when your application does
|
||
not need values with empty lines, you should consider disallowing them. This
|
||
will make empty lines split keys every time. In the example above, it would
|
||
produce two keys, <code class="docutils literal notranslate"><span class="pre">key</span></code> and <code class="docutils literal notranslate"><span class="pre">this</span></code>.</p>
|
||
</li>
|
||
<li><p><em>default_section</em>, default value: <code class="docutils literal notranslate"><span class="pre">configparser.DEFAULTSECT</span></code> (that is:
|
||
<code class="docutils literal notranslate"><span class="pre">"DEFAULT"</span></code>)</p>
|
||
<p>The convention of allowing a special section of default values for other
|
||
sections or interpolation purposes is a powerful concept of this library,
|
||
letting users create complex declarative configurations. This section is
|
||
normally called <code class="docutils literal notranslate"><span class="pre">"DEFAULT"</span></code> but this can be customized to point to any
|
||
other valid section name. Some typical values include: <code class="docutils literal notranslate"><span class="pre">"general"</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">"common"</span></code>. The name provided is used for recognizing default sections
|
||
when reading from any source and is used when writing configuration back to
|
||
a file. Its current value can be retrieved using the
|
||
<code class="docutils literal notranslate"><span class="pre">parser_instance.default_section</span></code> attribute and may be modified at runtime
|
||
(i.e. to convert files from one format to another).</p>
|
||
</li>
|
||
<li><p><em>interpolation</em>, default value: <code class="docutils literal notranslate"><span class="pre">configparser.BasicInterpolation</span></code></p>
|
||
<p>Interpolation behaviour may be customized by providing a custom handler
|
||
through the <em>interpolation</em> argument. <code class="docutils literal notranslate"><span class="pre">None</span></code> can be used to turn off
|
||
interpolation completely, <code class="docutils literal notranslate"><span class="pre">ExtendedInterpolation()</span></code> provides a more
|
||
advanced variant inspired by <code class="docutils literal notranslate"><span class="pre">zc.buildout</span></code>. More on the subject in the
|
||
<a class="reference external" href="#interpolation-of-values">dedicated documentation section</a>.
|
||
<a class="reference internal" href="#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawConfigParser</span></code></a> has a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</li>
|
||
<li><p><em>converters</em>, default value: not set</p>
|
||
<p>Config parsers provide option value getters that perform type conversion. By
|
||
default <a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getint()</span></code></a>, <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getfloat()</span></code></a>, and
|
||
<a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a> are implemented. Should other getters be
|
||
desirable, users may define them in a subclass or pass a dictionary where each
|
||
key is a name of the converter and each value is a callable implementing said
|
||
conversion. For instance, passing <code class="docutils literal notranslate"><span class="pre">{'decimal':</span> <span class="pre">decimal.Decimal}</span></code> would add
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">getdecimal()</span></code> on both the parser object and all section proxies. In
|
||
other words, it will be possible to write both
|
||
<code class="docutils literal notranslate"><span class="pre">parser_instance.getdecimal('section',</span> <span class="pre">'key',</span> <span class="pre">fallback=0)</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">parser_instance['section'].getdecimal('key',</span> <span class="pre">0)</span></code>.</p>
|
||
<p>If the converter needs to access the state of the parser, it can be
|
||
implemented as a method on a config parser subclass. If the name of this
|
||
method starts with <code class="docutils literal notranslate"><span class="pre">get</span></code>, it will be available on all section proxies, in
|
||
the dict-compatible form (see the <code class="docutils literal notranslate"><span class="pre">getdecimal()</span></code> example above).</p>
|
||
</li>
|
||
</ul>
|
||
<p>More advanced customization may be achieved by overriding default values of
|
||
these parser attributes. The defaults are defined on the classes, so they may
|
||
be overridden by subclasses or by attribute assignment.</p>
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.BOOLEAN_STATES">
|
||
<span class="sig-prename descclassname"><span class="pre">ConfigParser.</span></span><span class="sig-name descname"><span class="pre">BOOLEAN_STATES</span></span><a class="headerlink" href="#configparser.ConfigParser.BOOLEAN_STATES" title="Link to this definition">¶</a></dt>
|
||
<dd><p>By default when using <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a>, config parsers
|
||
consider the following values <code class="docutils literal notranslate"><span class="pre">True</span></code>: <code class="docutils literal notranslate"><span class="pre">'1'</span></code>, <code class="docutils literal notranslate"><span class="pre">'yes'</span></code>, <code class="docutils literal notranslate"><span class="pre">'true'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'on'</span></code> and the following values <code class="docutils literal notranslate"><span class="pre">False</span></code>: <code class="docutils literal notranslate"><span class="pre">'0'</span></code>, <code class="docutils literal notranslate"><span class="pre">'no'</span></code>, <code class="docutils literal notranslate"><span class="pre">'false'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'off'</span></code>. You can override this by specifying a custom dictionary of strings
|
||
and their Boolean outcomes. For example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">custom</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'funky'</span><span class="p">:</span> <span class="s1">'nope'</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">]</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'funky'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="c">...</span>
|
||
<span class="gr">ValueError</span>: <span class="n">Not a boolean: nope</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">BOOLEAN_STATES</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'sure'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="s1">'nope'</span><span class="p">:</span> <span class="kc">False</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">]</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'funky'</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other typical Boolean pairs include <code class="docutils literal notranslate"><span class="pre">accept</span></code>/<code class="docutils literal notranslate"><span class="pre">reject</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">enabled</span></code>/<code class="docutils literal notranslate"><span class="pre">disabled</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py">
|
||
<span class="sig-prename descclassname"><span class="pre">ConfigParser.</span></span><span class="sig-name descname"><span class="pre">optionxform</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">option</span></span></em><span class="sig-paren">)</span></dt>
|
||
<dd><p>This method transforms option names on every read, get, or set
|
||
operation. The default converts the name to lowercase. This also
|
||
means that when a configuration file gets written, all keys will be
|
||
lowercase. Override this method if that’s unsuitable.
|
||
For example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[Section1]</span>
|
||
<span class="gp">... </span><span class="s2">Key = Value</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">... </span><span class="s2">[Section2]</span>
|
||
<span class="gp">... </span><span class="s2">AnotherKey = Value</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">typical</span><span class="p">[</span><span class="s1">'Section1'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['key']</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">typical</span><span class="p">[</span><span class="s1">'Section2'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['anotherkey']</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">RawConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">optionxform</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">option</span><span class="p">:</span> <span class="n">option</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">custom</span><span class="p">[</span><span class="s1">'Section1'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['Key']</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">custom</span><span class="p">[</span><span class="s1">'Section2'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['AnotherKey']</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The optionxform function transforms option names to a canonical form.
|
||
This should be an idempotent function: if the name is already in
|
||
canonical form, it should be returned unchanged.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py attribute">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.SECTCRE">
|
||
<span class="sig-prename descclassname"><span class="pre">ConfigParser.</span></span><span class="sig-name descname"><span class="pre">SECTCRE</span></span><a class="headerlink" href="#configparser.ConfigParser.SECTCRE" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A compiled regular expression used to parse section headers. The default
|
||
matches <code class="docutils literal notranslate"><span class="pre">[section]</span></code> to the name <code class="docutils literal notranslate"><span class="pre">"section"</span></code>. Whitespace is considered
|
||
part of the section name, thus <code class="docutils literal notranslate"><span class="pre">[</span>  <span class="pre">larch</span>  <span class="pre">]</span></code> will be read as a section of
|
||
name <code class="docutils literal notranslate"><span class="pre">"</span>  <span class="pre">larch</span>  <span class="pre">"</span></code>. Override this attribute if that’s unsuitable. For
|
||
example:</p>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span><span class="w"> </span><span class="nn">re</span>
|
||
<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[Section 1]</span>
|
||
<span class="gp">... </span><span class="s2">option = value</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">... </span><span class="s2">[ Section 2 ]</span>
|
||
<span class="gp">... </span><span class="s2">another = val</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['Section 1', ' Section 2 ']</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">SECTCRE</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="sa">r</span><span class="s2">"\[ *(?P<header>[^]]+?) *\]"</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['Section 1', 'Section 2']</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>While ConfigParser objects also use an <code class="docutils literal notranslate"><span class="pre">OPTCRE</span></code> attribute for recognizing
|
||
option lines, it’s not recommended to override it because that would
|
||
interfere with constructor options <em>allow_no_value</em> and <em>delimiters</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="legacy-api-examples">
|
||
<h2>Legacy API Examples<a class="headerlink" href="#legacy-api-examples" title="Link to this heading">¶</a></h2>
|
||
<p>Mainly because of backwards compatibility concerns, <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a>
|
||
provides also a legacy API with explicit <code class="docutils literal notranslate"><span class="pre">get</span></code>/<code class="docutils literal notranslate"><span class="pre">set</span></code> methods. While there
|
||
are valid use cases for the methods outlined below, mapping protocol access is
|
||
preferred for new projects. The legacy API is at times more advanced,
|
||
low-level and downright counterintuitive.</p>
|
||
<p>An example of writing to a configuration file:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span>
|
||
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">RawConfigParser</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Please note that using RawConfigParser's set functions, you can assign</span>
|
||
<span class="c1"># non-string values to keys internally, but will receive an error when</span>
|
||
<span class="c1"># attempting to write to a file or when you get it in non-raw mode. Setting</span>
|
||
<span class="c1"># values using the mapping protocol or ConfigParser's set() does not allow</span>
|
||
<span class="c1"># such assignments to take place.</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">add_section</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'an_int'</span><span class="p">,</span> <span class="s1">'15'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_bool'</span><span class="p">,</span> <span class="s1">'true'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_float'</span><span class="p">,</span> <span class="s1">'3.1415'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">,</span> <span class="s1">'fun'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">,</span> <span class="s1">'Python'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'</span><span class="si">%(bar)s</span><span class="s1"> is </span><span class="si">%(baz)s</span><span class="s1">!'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Writing our configuration file to 'example.cfg'</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">configfile</span><span class="p">:</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">configfile</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>An example of reading the configuration file again:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span>
|
||
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">RawConfigParser</span><span class="p">()</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># getfloat() raises an exception if the value is not a float</span>
|
||
<span class="c1"># getint() and getboolean() also do this for their respective types</span>
|
||
<span class="n">a_float</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">getfloat</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_float'</span><span class="p">)</span>
|
||
<span class="n">an_int</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">getint</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'an_int'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">a_float</span> <span class="o">+</span> <span class="n">an_int</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.</span>
|
||
<span class="c1"># This is because we are using a RawConfigParser().</span>
|
||
<span class="k">if</span> <span class="n">config</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_bool'</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To get interpolation, use <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span>
|
||
|
||
<span class="n">cfg</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="n">cfg</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Set the optional *raw* argument of get() to True if you wish to disable</span>
|
||
<span class="c1"># interpolation in a single get operation.</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="n">raw</span><span class="o">=</span><span class="kc">False</span><span class="p">))</span> <span class="c1"># -> "Python is fun!"</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="n">raw</span><span class="o">=</span><span class="kc">True</span><span class="p">))</span> <span class="c1"># -> "%(bar)s is %(baz)s!"</span>
|
||
|
||
<span class="c1"># The optional *vars* argument is a dict with members that will take</span>
|
||
<span class="c1"># precedence in interpolation.</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="nb">vars</span><span class="o">=</span><span class="p">{</span><span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'Documentation'</span><span class="p">,</span>
|
||
<span class="s1">'baz'</span><span class="p">:</span> <span class="s1">'evil'</span><span class="p">}))</span>
|
||
|
||
<span class="c1"># The optional *fallback* argument can be used to provide a fallback value</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span>
|
||
<span class="c1"># -> "Python is fun!"</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="s1">'Monty is not.'</span><span class="p">))</span>
|
||
<span class="c1"># -> "Python is fun!"</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'monster'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="s1">'No such things as monsters.'</span><span class="p">))</span>
|
||
<span class="c1"># -> "No such things as monsters."</span>
|
||
|
||
<span class="c1"># A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError</span>
|
||
<span class="c1"># but we can also use:</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'monster'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="kc">None</span><span class="p">))</span>
|
||
<span class="c1"># -> None</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Default values are available in both types of ConfigParsers. They are used in
|
||
interpolation if an option used is not defined elsewhere.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span>
|
||
|
||
<span class="c1"># New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each</span>
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">({</span><span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'Life'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">:</span> <span class="s1">'hard'</span><span class="p">})</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">)</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span> <span class="c1"># -> "Python is fun!"</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">remove_option</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">remove_option</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span> <span class="c1"># -> "Life is hard!"</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="configparser-objects">
|
||
<span id="id13"></span><h2>ConfigParser Objects<a class="headerlink" href="#configparser-objects" title="Link to this heading">¶</a></h2>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">ConfigParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">defaults</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">dict_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">dict</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_no_value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></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">('=',</span> <span class="pre">':')</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">comment_prefixes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">('#',</span> <span class="pre">';')</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">inline_comment_prefixes</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">strict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">empty_lines_in_values</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default_section</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">configparser.DEFAULTSECT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">interpolation</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">BasicInterpolation()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">converters</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">allow_unnamed_section</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The main configuration parser. When <em>defaults</em> is given, it is initialized
|
||
into the dictionary of intrinsic defaults. When <em>dict_type</em> is given, it
|
||
will be used to create the dictionary objects for the list of sections, for
|
||
the options within a section, and for the default values.</p>
|
||
<p>When <em>delimiters</em> is given, it is used as the set of substrings that
|
||
divide keys from values. When <em>comment_prefixes</em> is given, it will be used
|
||
as the set of substrings that prefix comments in otherwise empty lines.
|
||
Comments can be indented. When <em>inline_comment_prefixes</em> is given, it will
|
||
be used as the set of substrings that prefix comments in non-empty lines.</p>
|
||
<p>When <em>strict</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), the parser won’t allow for
|
||
any section or option duplicates while reading from a single source (file,
|
||
string or dictionary), raising <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateSectionError</span></code></a> or
|
||
<a class="reference internal" href="#configparser.DuplicateOptionError" title="configparser.DuplicateOptionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateOptionError</span></code></a>. When <em>empty_lines_in_values</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>
|
||
(default: <code class="docutils literal notranslate"><span class="pre">True</span></code>), each empty line marks the end of an option. Otherwise,
|
||
internal empty lines of a multiline option are kept as part of the value.
|
||
When <em>allow_no_value</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (default: <code class="docutils literal notranslate"><span class="pre">False</span></code>), options without
|
||
values are accepted; the value held for these is <code class="docutils literal notranslate"><span class="pre">None</span></code> and they are
|
||
serialized without the trailing delimiter.</p>
|
||
<p>When <em>default_section</em> is given, it specifies the name for the special
|
||
section holding default values for other sections and interpolation purposes
|
||
(normally named <code class="docutils literal notranslate"><span class="pre">"DEFAULT"</span></code>). This value can be retrieved and changed at
|
||
runtime using the <code class="docutils literal notranslate"><span class="pre">default_section</span></code> instance attribute. This won’t
|
||
re-evaluate an already parsed config file, but will be used when writing
|
||
parsed settings to a new config file.</p>
|
||
<p>Interpolation behaviour may be customized by providing a custom handler
|
||
through the <em>interpolation</em> argument. <code class="docutils literal notranslate"><span class="pre">None</span></code> can be used to turn off
|
||
interpolation completely, <code class="docutils literal notranslate"><span class="pre">ExtendedInterpolation()</span></code> provides a more
|
||
advanced variant inspired by <code class="docutils literal notranslate"><span class="pre">zc.buildout</span></code>. More on the subject in the
|
||
<a class="reference external" href="#interpolation-of-values">dedicated documentation section</a>.</p>
|
||
<p>All option names used in interpolation will be passed through the
|
||
<a class="reference internal" href="#configparser.ConfigParser.optionxform" title="configparser.ConfigParser.optionxform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optionxform()</span></code></a> method just like any other option name reference. For
|
||
example, using the default implementation of <a class="reference internal" href="#configparser.ConfigParser.optionxform" title="configparser.ConfigParser.optionxform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optionxform()</span></code></a> (which
|
||
converts option names to lower case), the values <code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre">%(bar)s</span></code> and <code class="docutils literal notranslate"><span class="pre">foo</span>
|
||
<span class="pre">%(BAR)s</span></code> are equivalent.</p>
|
||
<p>When <em>converters</em> is given, it should be a dictionary where each key
|
||
represents the name of a type converter and each value is a callable
|
||
implementing the conversion from string to the desired datatype. Every
|
||
converter gets its own corresponding <code class="xref py py-meth docutils literal notranslate"><span class="pre">get*()</span></code> method on the parser
|
||
object and section proxies.</p>
|
||
<p>When <em>allow_unnamed_section</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (default: <code class="docutils literal notranslate"><span class="pre">False</span></code>),
|
||
the first section name can be omitted. See the
|
||
<a class="reference external" href="#unnamed-sections">“Unnamed Sections” section</a>.</p>
|
||
<p>It is possible to read several configurations into a single
|
||
<a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>, where the most recently added configuration has the
|
||
highest priority. Any conflicting keys are taken from the more recent
|
||
configuration while the previously existing keys are retained. The example
|
||
below reads in an <code class="docutils literal notranslate"><span class="pre">override.ini</span></code> file, which will override any conflicting
|
||
keys from the <code class="docutils literal notranslate"><span class="pre">example.ini</span></code> file.</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[DEFAULT]</span>
|
||
<span class="na">ServerAliveInterval</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">-1</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config_override</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config_override</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'ServerAliveInterval'</span><span class="p">:</span> <span class="s1">'-1'</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'override.ini'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">configfile</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">config_override</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">configfile</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="gp">>>> </span><span class="n">config_override</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config_override</span><span class="o">.</span><span class="n">read</span><span class="p">([</span><span class="s1">'example.ini'</span><span class="p">,</span> <span class="s1">'override.ini'</span><span class="p">])</span>
|
||
<span class="go">['example.ini', 'override.ini']</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">config_override</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'DEFAULT'</span><span class="p">,</span> <span class="s1">'ServerAliveInterval'</span><span class="p">))</span>
|
||
<span class="go">-1</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.1: </span>The default <em>dict_type</em> is <a class="reference internal" href="collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.OrderedDict</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><em>allow_no_value</em>, <em>delimiters</em>, <em>comment_prefixes</em>, <em>strict</em>,
|
||
<em>empty_lines_in_values</em>, <em>default_section</em> and <em>interpolation</em> were
|
||
added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>converters</em> argument was added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>defaults</em> argument is read with <a class="reference internal" href="#configparser.ConfigParser.read_dict" title="configparser.ConfigParser.read_dict"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_dict()</span></code></a>,
|
||
providing consistent behavior across the parser: non-string
|
||
keys and values are implicitly converted to strings.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span>The default <em>dict_type</em> is <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>, since it now preserves
|
||
insertion order.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>Raise a <a class="reference internal" href="#configparser.MultilineContinuationError" title="configparser.MultilineContinuationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">MultilineContinuationError</span></code></a> when <em>allow_no_value</em> is
|
||
<code class="docutils literal notranslate"><span class="pre">True</span></code>, and a key without a value is continued with an indented line.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>The <em>allow_unnamed_section</em> argument was added.</p>
|
||
</div>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.defaults">
|
||
<span class="sig-name descname"><span class="pre">defaults</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.defaults" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a dictionary containing the instance-wide defaults.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.sections">
|
||
<span class="sig-name descname"><span class="pre">sections</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.sections" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a list of the sections available; the <em>default section</em> is not
|
||
included in the list.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.add_section">
|
||
<span class="sig-name descname"><span class="pre">add_section</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.add_section" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Add a section named <em>section</em> to the instance. If a section by the given
|
||
name already exists, <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateSectionError</span></code></a> is raised. If the
|
||
<em>default section</em> name is passed, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised. The name
|
||
of the section must be a string; if not, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Non-string section names raise <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.has_section">
|
||
<span class="sig-name descname"><span class="pre">has_section</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.has_section" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Indicates whether the named <em>section</em> is present in the configuration.
|
||
The <em>default section</em> is not acknowledged.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.options">
|
||
<span class="sig-name descname"><span class="pre">options</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.options" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Return a list of options available in the specified <em>section</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.has_option">
|
||
<span class="sig-name descname"><span class="pre">has_option</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.has_option" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If the given <em>section</em> exists, and contains the given <em>option</em>, return
|
||
<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>; otherwise return <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>. If the specified
|
||
<em>section</em> is <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> or an empty string, DEFAULT is assumed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.read">
|
||
<span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filenames</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</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="#configparser.ConfigParser.read" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Attempt to read and parse an iterable of filenames, returning a list of
|
||
filenames which were successfully parsed.</p>
|
||
<p>If <em>filenames</em> is a string, a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object or a
|
||
<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>, it is treated as
|
||
a single filename. If a file named in <em>filenames</em> cannot be opened, that
|
||
file will be ignored. This is designed so that you can specify an
|
||
iterable of potential configuration file locations (for example, the
|
||
current directory, the user’s home directory, and some system-wide
|
||
directory), and all existing configuration files in the iterable will be
|
||
read.</p>
|
||
<p>If none of the named files exist, the <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>
|
||
instance will contain an empty dataset. An application which requires
|
||
initial values to be loaded from a file should load the required file or
|
||
files using <a class="reference internal" href="#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_file()</span></code></a> before calling <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> for any
|
||
optional files:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">configparser</span><span class="o">,</span><span class="w"> </span><span class="nn">os</span>
|
||
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read_file</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="s1">'defaults.cfg'</span><span class="p">))</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">([</span><span class="s1">'site.cfg'</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s1">'~/.myapp.cfg'</span><span class="p">)],</span>
|
||
<span class="n">encoding</span><span class="o">=</span><span class="s1">'cp1250'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <em>encoding</em> parameter.
|
||
Previously, all files were read using the default encoding for <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>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.6.1: </span>The <em>filenames</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>filenames</em> parameter accepts a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.read_file">
|
||
<span class="sig-name descname"><span class="pre">read_file</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">source</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="#configparser.ConfigParser.read_file" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Read and parse configuration data from <em>f</em> which must be an iterable
|
||
yielding Unicode strings (for example files opened in text mode).</p>
|
||
<p>Optional argument <em>source</em> specifies the name of the file being read. If
|
||
not given and <em>f</em> has a <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code> attribute, that is used for
|
||
<em>source</em>; the default is <code class="docutils literal notranslate"><span class="pre">'<???>'</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2: </span>Replaces <code class="xref py py-meth docutils literal notranslate"><span class="pre">readfp()</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.read_string">
|
||
<span class="sig-name descname"><span class="pre">read_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">source</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'<string>'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.read_string" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Parse configuration data from a string.</p>
|
||
<p>Optional argument <em>source</em> specifies a context-specific name of the
|
||
string passed. If not given, <code class="docutils literal notranslate"><span class="pre">'<string>'</span></code> is used. This should
|
||
commonly be a filesystem path or a URL.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.read_dict">
|
||
<span class="sig-name descname"><span class="pre">read_dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dictionary</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">source</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'<dict>'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.read_dict" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Load configuration from any object that provides a dict-like <code class="docutils literal notranslate"><span class="pre">items()</span></code>
|
||
method. Keys are section names, values are dictionaries with keys and
|
||
values that should be present in the section. If the used dictionary
|
||
type preserves order, sections and their keys will be added in order.
|
||
Values are automatically converted to strings.</p>
|
||
<p>Optional argument <em>source</em> specifies a context-specific name of the
|
||
dictionary passed. If not given, <code class="docutils literal notranslate"><span class="pre"><dict></span></code> is used.</p>
|
||
<p>This method can be used to copy state between parsers.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.get">
|
||
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raw=False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">vars=None</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">fallback</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.get" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Get an <em>option</em> value for the named <em>section</em>. If <em>vars</em> is provided, it
|
||
must be a dictionary. The <em>option</em> is looked up in <em>vars</em> (if provided),
|
||
<em>section</em>, and in <em>DEFAULTSECT</em> in that order. If the key is not found
|
||
and <em>fallback</em> is provided, it is used as a fallback value. <code class="docutils literal notranslate"><span class="pre">None</span></code> can
|
||
be provided as a <em>fallback</em> value.</p>
|
||
<p>All the <code class="docutils literal notranslate"><span class="pre">'%'</span></code> interpolations are expanded in the return values, unless
|
||
the <em>raw</em> argument is true. Values for interpolation keys are looked up
|
||
in the same manner as the option.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Arguments <em>raw</em>, <em>vars</em> and <em>fallback</em> are keyword only to protect
|
||
users from trying to use the third argument as the <em>fallback</em> fallback
|
||
(especially when using the mapping protocol).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.getint">
|
||
<span class="sig-name descname"><span class="pre">getint</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raw=False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">vars=None</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">fallback</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.getint" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A convenience method which coerces the <em>option</em> in the specified <em>section</em>
|
||
to an integer. See <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> for explanation of <em>raw</em>, <em>vars</em> and
|
||
<em>fallback</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.getfloat">
|
||
<span class="sig-name descname"><span class="pre">getfloat</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raw=False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">vars=None</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">fallback</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.getfloat" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A convenience method which coerces the <em>option</em> in the specified <em>section</em>
|
||
to a floating-point number. See <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> for explanation of <em>raw</em>,
|
||
<em>vars</em> and <em>fallback</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.getboolean">
|
||
<span class="sig-name descname"><span class="pre">getboolean</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raw=False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">vars=None</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">fallback</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.getboolean" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A convenience method which coerces the <em>option</em> in the specified <em>section</em>
|
||
to a Boolean value. Note that the accepted values for the option are
|
||
<code class="docutils literal notranslate"><span class="pre">'1'</span></code>, <code class="docutils literal notranslate"><span class="pre">'yes'</span></code>, <code class="docutils literal notranslate"><span class="pre">'true'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'on'</span></code>, which cause this method to
|
||
return <code class="docutils literal notranslate"><span class="pre">True</span></code>, and <code class="docutils literal notranslate"><span class="pre">'0'</span></code>, <code class="docutils literal notranslate"><span class="pre">'no'</span></code>, <code class="docutils literal notranslate"><span class="pre">'false'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'off'</span></code>, which
|
||
cause it to return <code class="docutils literal notranslate"><span class="pre">False</span></code>. These string values are checked in a
|
||
case-insensitive manner. Any other value will cause it to raise
|
||
<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>. See <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> for explanation of <em>raw</em>, <em>vars</em> and
|
||
<em>fallback</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.items">
|
||
<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">raw</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">vars</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="#configparser.ConfigParser.items" title="Link to this definition">¶</a></dt>
|
||
<dt class="sig sig-object py">
|
||
<span class="sig-name descname"><span class="pre">items</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raw</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">vars</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></dt>
|
||
<dd><p>When <em>section</em> is not given, return a list of <em>section_name</em>,
|
||
<em>section_proxy</em> pairs, including DEFAULTSECT.</p>
|
||
<p>Otherwise, return a list of <em>name</em>, <em>value</em> pairs for the options in the
|
||
given <em>section</em>. Optional arguments have the same meaning as for the
|
||
<a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> method.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span>Items present in <em>vars</em> no longer appear in the result. The previous
|
||
behaviour mixed actual parser options with variables provided for
|
||
interpolation.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.set">
|
||
<span class="sig-name descname"><span class="pre">set</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.set" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If the given section exists, set the given option to the specified value;
|
||
otherwise raise <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSectionError</span></code></a>. <em>option</em> and <em>value</em> must be
|
||
strings; if not, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.write">
|
||
<span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fileobject</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">space_around_delimiters</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.write" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Write a representation of the configuration to the specified <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file
|
||
object</span></a>, which must be opened in text mode (accepting strings). This
|
||
representation can be parsed by a future <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> call. If
|
||
<em>space_around_delimiters</em> is true, delimiters between
|
||
keys and values are surrounded by spaces.</p>
|
||
</dd></dl>
|
||
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Comments in the original configuration file are not preserved when
|
||
writing the configuration back.
|
||
What is considered a comment, depends on the given values for
|
||
<em>comment_prefix</em> and <em>inline_comment_prefix</em>.</p>
|
||
</div>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.remove_option">
|
||
<span class="sig-name descname"><span class="pre">remove_option</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.remove_option" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Remove the specified <em>option</em> from the specified <em>section</em>. If the
|
||
section does not exist, raise <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSectionError</span></code></a>. If the option
|
||
existed to be removed, return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>; otherwise return
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.remove_section">
|
||
<span class="sig-name descname"><span class="pre">remove_section</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.remove_section" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Remove the specified <em>section</em> from the configuration. If the section in
|
||
fact existed, return <code class="docutils literal notranslate"><span class="pre">True</span></code>. Otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.ConfigParser.optionxform">
|
||
<span class="sig-name descname"><span class="pre">optionxform</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">option</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.optionxform" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Transforms the option name <em>option</em> as found in an input file or as passed
|
||
in by client code to the form that should be used in the internal
|
||
structures. The default implementation returns a lower-case version of
|
||
<em>option</em>; subclasses may override this or client code can set an attribute
|
||
of this name on instances to affect this behavior.</p>
|
||
<p>You don’t need to subclass the parser to use this method, you can also
|
||
set it on an instance, to a function that takes a string argument and
|
||
returns a string. Setting it to <code class="docutils literal notranslate"><span class="pre">str</span></code>, for example, would make option
|
||
names case sensitive:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cfgparser</span> <span class="o">=</span> <span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="n">cfgparser</span><span class="o">.</span><span class="n">optionxform</span> <span class="o">=</span> <span class="nb">str</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that when reading configuration files, whitespace around the option
|
||
names is stripped before <a class="reference internal" href="#configparser.ConfigParser.optionxform" title="configparser.ConfigParser.optionxform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optionxform()</span></code></a> is called.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="configparser.UNNAMED_SECTION">
|
||
<span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">UNNAMED_SECTION</span></span><a class="headerlink" href="#configparser.UNNAMED_SECTION" title="Link to this definition">¶</a></dt>
|
||
<dd><p>A special object representing a section name used to reference the unnamed section (see <a class="reference internal" href="#unnamed-sections"><span class="std std-ref">Unnamed Sections</span></a>).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py data">
|
||
<dt class="sig sig-object py" id="configparser.MAX_INTERPOLATION_DEPTH">
|
||
<span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">MAX_INTERPOLATION_DEPTH</span></span><a class="headerlink" href="#configparser.MAX_INTERPOLATION_DEPTH" title="Link to this definition">¶</a></dt>
|
||
<dd><p>The maximum depth for recursive interpolation for <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> when the <em>raw</em>
|
||
parameter is false. This is relevant only when the default <em>interpolation</em>
|
||
is used.</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="rawconfigparser-objects">
|
||
<span id="id15"></span><h2>RawConfigParser Objects<a class="headerlink" href="#rawconfigparser-objects" title="Link to this heading">¶</a></h2>
|
||
<dl class="py class">
|
||
<dt class="sig sig-object py" id="configparser.RawConfigParser">
|
||
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">RawConfigParser</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">defaults</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">dict_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">dict</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">allow_no_value</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></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">('=',</span> <span class="pre">':')</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">comment_prefixes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">('#',</span> <span class="pre">';')</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">inline_comment_prefixes</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">strict</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">empty_lines_in_values</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">default_section</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">configparser.DEFAULTSECT</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">interpolation</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">BasicInterpolation()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">converters</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">allow_unnamed_section</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.RawConfigParser" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Legacy variant of the <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>. It has interpolation
|
||
disabled by default and allows for non-string section names, option
|
||
names, and values via its unsafe <code class="docutils literal notranslate"><span class="pre">add_section</span></code> and <code class="docutils literal notranslate"><span class="pre">set</span></code> methods,
|
||
as well as the legacy <code class="docutils literal notranslate"><span class="pre">defaults=</span></code> keyword argument handling.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><em>allow_no_value</em>, <em>delimiters</em>, <em>comment_prefixes</em>, <em>strict</em>,
|
||
<em>empty_lines_in_values</em>, <em>default_section</em> and <em>interpolation</em> were
|
||
added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>converters</em> argument was added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.8: </span>The default <em>dict_type</em> is <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>, since it now preserves
|
||
insertion order.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.13: </span>The <em>allow_unnamed_section</em> argument was added.</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Consider using <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> instead which checks types of
|
||
the values to be stored internally. If you don’t want interpolation, you
|
||
can use <code class="docutils literal notranslate"><span class="pre">ConfigParser(interpolation=None)</span></code>.</p>
|
||
</div>
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.RawConfigParser.add_section">
|
||
<span class="sig-name descname"><span class="pre">add_section</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.RawConfigParser.add_section" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Add a section named <em>section</em> to the instance. If a section by the given
|
||
name already exists, <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateSectionError</span></code></a> is raised. If the
|
||
<em>default section</em> name is passed, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
|
||
<p>Type of <em>section</em> is not checked which lets users create non-string named
|
||
sections. This behaviour is unsupported and may cause internal errors.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py method">
|
||
<dt class="sig sig-object py" id="configparser.RawConfigParser.set">
|
||
<span class="sig-name descname"><span class="pre">set</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">section</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">option</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.RawConfigParser.set" title="Link to this definition">¶</a></dt>
|
||
<dd><p>If the given section exists, set the given option to the specified value;
|
||
otherwise raise <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSectionError</span></code></a>. While it is possible to use
|
||
<a class="reference internal" href="#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawConfigParser</span></code></a> (or <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> with <em>raw</em> parameters
|
||
set to true) for <em>internal</em> storage of non-string values, full
|
||
functionality (including interpolation and output to files) can only be
|
||
achieved using string values.</p>
|
||
<p>This method lets users assign non-string values to keys internally. This
|
||
behaviour is unsupported and will cause errors when attempting to write
|
||
to a file or get it in non-raw mode. <strong>Use the mapping protocol API</strong>
|
||
which does not allow such assignments to take place.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="exceptions">
|
||
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Link to this heading">¶</a></h2>
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.Error">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">Error</span></span><a class="headerlink" href="#configparser.Error" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Base class for all other <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> exceptions.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.NoSectionError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">NoSectionError</span></span><a class="headerlink" href="#configparser.NoSectionError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when a specified section is not found.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.DuplicateSectionError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">DuplicateSectionError</span></span><a class="headerlink" href="#configparser.DuplicateSectionError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised if <a class="reference internal" href="#configparser.ConfigParser.add_section" title="configparser.ConfigParser.add_section"><code class="xref py py-meth docutils literal notranslate"><span class="pre">add_section()</span></code></a> is called with the name of a section
|
||
that is already present or in strict parsers when a section if found more
|
||
than once in a single input file, string or dictionary.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Added the optional <em>source</em> and <em>lineno</em> attributes and parameters to
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.DuplicateOptionError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">DuplicateOptionError</span></span><a class="headerlink" href="#configparser.DuplicateOptionError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised by strict parsers if a single option appears twice during
|
||
reading from a single file, string or dictionary. This catches misspellings
|
||
and case sensitivity-related errors, e.g. a dictionary may have two keys
|
||
representing the same case-insensitive configuration key.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.NoOptionError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">NoOptionError</span></span><a class="headerlink" href="#configparser.NoOptionError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when a specified option is not found in the specified
|
||
section.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.InterpolationError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">InterpolationError</span></span><a class="headerlink" href="#configparser.InterpolationError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Base class for exceptions raised when problems occur performing string
|
||
interpolation.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.InterpolationDepthError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">InterpolationDepthError</span></span><a class="headerlink" href="#configparser.InterpolationDepthError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when string interpolation cannot be completed because the
|
||
number of iterations exceeds <a class="reference internal" href="#configparser.MAX_INTERPOLATION_DEPTH" title="configparser.MAX_INTERPOLATION_DEPTH"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAX_INTERPOLATION_DEPTH</span></code></a>. Subclass of
|
||
<a class="reference internal" href="#configparser.InterpolationError" title="configparser.InterpolationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterpolationError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.InterpolationMissingOptionError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">InterpolationMissingOptionError</span></span><a class="headerlink" href="#configparser.InterpolationMissingOptionError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when an option referenced from a value does not exist.
|
||
Subclass of <a class="reference internal" href="#configparser.InterpolationError" title="configparser.InterpolationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterpolationError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.InterpolationSyntaxError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">InterpolationSyntaxError</span></span><a class="headerlink" href="#configparser.InterpolationSyntaxError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when the source text into which substitutions are made does
|
||
not conform to the required syntax. Subclass of <a class="reference internal" href="#configparser.InterpolationError" title="configparser.InterpolationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterpolationError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.MissingSectionHeaderError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">MissingSectionHeaderError</span></span><a class="headerlink" href="#configparser.MissingSectionHeaderError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when attempting to parse a file which has no section
|
||
headers.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.ParsingError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">ParsingError</span></span><a class="headerlink" href="#configparser.ParsingError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when errors occur attempting to parse a file.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.12: </span>The <code class="docutils literal notranslate"><span class="pre">filename</span></code> attribute and <code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code> constructor argument were
|
||
removed. They have been available using the name <code class="docutils literal notranslate"><span class="pre">source</span></code> since 3.2.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="py exception">
|
||
<dt class="sig sig-object py" id="configparser.MultilineContinuationError">
|
||
<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">configparser.</span></span><span class="sig-name descname"><span class="pre">MultilineContinuationError</span></span><a class="headerlink" href="#configparser.MultilineContinuationError" title="Link to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when a key without a corresponding value is continued with
|
||
an indented line.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">Added in version 3.13.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p class="rubric">Footnotes</p>
|
||
<aside class="footnote-list brackets">
|
||
<aside class="footnote brackets" id="id16" role="doc-footnote">
|
||
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
|
||
<span class="backrefs">(<a role="doc-backlink" href="#id1">1</a>,<a role="doc-backlink" href="#id2">2</a>,<a role="doc-backlink" href="#id3">3</a>,<a role="doc-backlink" href="#id4">4</a>,<a role="doc-backlink" href="#id5">5</a>,<a role="doc-backlink" href="#id6">6</a>,<a role="doc-backlink" href="#id7">7</a>,<a role="doc-backlink" href="#id8">8</a>,<a role="doc-backlink" href="#id9">9</a>,<a role="doc-backlink" href="#id11">10</a>,<a role="doc-backlink" href="#id12">11</a>)</span>
|
||
<p>Config parsers allow for heavy customization. If you are interested in
|
||
changing the behaviour outlined by the footnote reference, consult the
|
||
<a class="reference internal" href="#customizing-parser-behaviour">Customizing Parser Behaviour</a> section.</p>
|
||
</aside>
|
||
</aside>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a><ul>
|
||
<li><a class="reference internal" href="#quick-start">Quick Start</a></li>
|
||
<li><a class="reference internal" href="#supported-datatypes">Supported Datatypes</a></li>
|
||
<li><a class="reference internal" href="#fallback-values">Fallback Values</a></li>
|
||
<li><a class="reference internal" href="#supported-ini-file-structure">Supported INI File Structure</a></li>
|
||
<li><a class="reference internal" href="#unnamed-sections">Unnamed Sections</a></li>
|
||
<li><a class="reference internal" href="#interpolation-of-values">Interpolation of values</a></li>
|
||
<li><a class="reference internal" href="#mapping-protocol-access">Mapping Protocol Access</a></li>
|
||
<li><a class="reference internal" href="#customizing-parser-behaviour">Customizing Parser Behaviour</a></li>
|
||
<li><a class="reference internal" href="#legacy-api-examples">Legacy API Examples</a></li>
|
||
<li><a class="reference internal" href="#configparser-objects">ConfigParser Objects</a></li>
|
||
<li><a class="reference internal" href="#rawconfigparser-objects">RawConfigParser Objects</a></li>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="csv.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="tomllib.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tomllib</span></code> — Parse TOML files</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/library/configparser.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="tomllib.html" title="tomllib — Parse TOML files"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="csv.html" title="csv — CSV File Reading and Writing"
|
||
>previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="fileformats.html" >File Formats</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
©
|
||
<a href="../copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |