/usr/share/doc/python-configparser/html/README.html is in python-configparser 3.3.0r2-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>configparser — ConfigParser 3.3.0r2-1 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '3.3.0r2-1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="ConfigParser 3.3.0r2-1 documentation" href="index.html" />
</head>
<body>
<div class="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><a href="configparser.html">ConfigParser 3.3.0r2-1 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="configparser">
<h1>configparser<a class="headerlink" href="#configparser" title="Permalink to this headline">¶</a></h1>
<p>The ancient <tt class="docutils literal"><span class="pre">ConfigParser</span></tt> module available in the standard library 2.x has
seen a major update in Python 3.2. This is a backport of those changes so that
they can be used directly in Python 2.6 - 2.7.</p>
<p>To use <tt class="docutils literal"><span class="pre">configparser</span></tt> instead of <tt class="docutils literal"><span class="pre">ConfigParser</span></tt>, simply replace:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">ConfigParser</span>
</pre></div>
</div>
<p>with:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">configparser</span>
</pre></div>
</div>
<p>For detailed documentation consult the vanilla version at
<a class="reference external" href="http://docs.python.org/3/library/configparser.html">http://docs.python.org/3/library/configparser.html</a>.</p>
<div class="section" id="why-you-ll-love-configparser">
<h2>Why you’ll love <tt class="docutils literal"><span class="pre">configparser</span></tt><a class="headerlink" href="#why-you-ll-love-configparser" title="Permalink to this headline">¶</a></h2>
<p>Whereas almost completely compatible with its older brother, <tt class="docutils literal"><span class="pre">configparser</span></tt>
sports a bunch of interesting new features:</p>
<ul>
<li><p class="first">full mapping protocol access (<a class="reference external" href="http://docs.python.org/3/library/configparser.html#mapping-protocol-access">more info</a>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">parser</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_string</span><span class="p">(</span><span class="s">"""</span>
<span class="go">[DEFAULT]</span>
<span class="go">location = upper left</span>
<span class="go">visible = yes</span>
<span class="go">editable = no</span>
<span class="go">color = blue</span>
<span class="go">[main]</span>
<span class="go">title = Main Menu</span>
<span class="go">color = green</span>
<span class="go">[options]</span>
<span class="go">title = Options</span>
<span class="go">""")</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="p">[</span><span class="s">'main'</span><span class="p">][</span><span class="s">'color'</span><span class="p">]</span>
<span class="go">'green'</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="p">[</span><span class="s">'main'</span><span class="p">][</span><span class="s">'editable'</span><span class="p">]</span>
<span class="go">'no'</span>
<span class="gp">>>> </span><span class="n">section</span> <span class="o">=</span> <span class="n">parser</span><span class="p">[</span><span class="s">'options'</span><span class="p">]</span>
<span class="gp">>>> </span><span class="n">section</span><span class="p">[</span><span class="s">'title'</span><span class="p">]</span>
<span class="go">'Options'</span>
<span class="gp">>>> </span><span class="n">section</span><span class="p">[</span><span class="s">'title'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'Options (editable: </span><span class="si">%(editable)s</span><span class="s">)'</span>
<span class="gp">>>> </span><span class="n">section</span><span class="p">[</span><span class="s">'title'</span><span class="p">]</span>
<span class="go">'Options (editable: no)'</span>
</pre></div>
</div>
</li>
<li><p class="first">there’s now one default <tt class="docutils literal"><span class="pre">ConfigParser</span></tt> class, which basically is the old
<tt class="docutils literal"><span class="pre">SafeConfigParser</span></tt> with a bunch of tweaks which make it more predictable for
users. Don’t need interpolation? Simply use
<tt class="docutils literal"><span class="pre">ConfigParser(interpolation=None)</span></tt>, no need to use a distinct
<tt class="docutils literal"><span class="pre">RawConfigParser</span></tt> anymore.</p>
</li>
<li><p class="first">the parser is highly <a class="reference external" href="http://docs.python.org/3/library/configparser.html#customizing-parser-behaviour">customizable upon instantiation</a>
supporting things like changing option delimiters, comment characters, the
name of the DEFAULT section, the interpolation syntax, etc.</p>
</li>
<li><p class="first">you can easily create your own interpolation syntax but there are two powerful
implementations built-in (<a class="reference external" href="http://docs.python.org/3/library/configparser.html#interpolation-of-values">more info</a>):</p>
<ul class="simple">
<li>the classic <tt class="docutils literal"><span class="pre">%(string-like)s</span></tt> syntax (called <tt class="docutils literal"><span class="pre">BasicInterpolation</span></tt>)</li>
<li>a new <tt class="docutils literal"><span class="pre">${buildout:like}</span></tt> syntax (called <tt class="docutils literal"><span class="pre">ExtendedInterpolation</span></tt>)</li>
</ul>
</li>
<li><p class="first">fallback values may be specified in getters (<a class="reference external" href="http://docs.python.org/3/library/configparser.html#fallback-values">more info</a>):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'closet'</span><span class="p">,</span> <span class="s">'monster'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">fallback</span><span class="o">=</span><span class="s">'No such things as monsters'</span><span class="p">)</span>
<span class="go">'No such things as monsters'</span>
</pre></div>
</div>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">ConfigParser</span></tt> objects can now read data directly <a class="reference external" href="http://docs.python.org/3/library/configparser.html#configparser.ConfigParser.read_string">from strings</a>
and <a class="reference external" href="http://docs.python.org/3/library/configparser.html#configparser.ConfigParser.read_dict">from dictionaries</a>.
That means importing configuration from JSON or specifying default values for
the whole configuration (multiple sections) is now a single line of code. Same
goes for copying data from another <tt class="docutils literal"><span class="pre">ConfigParser</span></tt> instance, thanks to its
mapping protocol support.</p>
</li>
<li><p class="first">many smaller tweaks, updates and fixes</p>
</li>
</ul>
</div>
<div class="section" id="a-few-words-about-unicode">
<h2>A few words about Unicode<a class="headerlink" href="#a-few-words-about-unicode" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">configparser</span></tt> comes from Python 3 and as such it works well with Unicode.
The library is generally cleaned up in terms of internal data storage and
reading/writing files. There are a couple of incompatibilities with the old
<tt class="docutils literal"><span class="pre">ConfigParser</span></tt> due to that. However, the work required to migrate is well
worth it as it shows the issues that would likely come up during migration of
your project to Python 3.</p>
<p>The design assumes that Unicode strings are used whenever possible <a class="footnote-reference" href="#id12" id="id1">[1]</a>. That
gives you the certainty that what’s stored in a configuration object is text.
Once your configuration is read, the rest of your application doesn’t have to
deal with encoding issues. All you have is text <a class="footnote-reference" href="#id13" id="id2">[2]</a>. The only two phases when
you should explicitly state encoding is when you either read from an external
source (e.g. a file) or write back.</p>
</div>
<div class="section" id="versioning">
<h2>Versioning<a class="headerlink" href="#versioning" title="Permalink to this headline">¶</a></h2>
<p>This backport is intended to keep 100% compatibility with the vanilla release in
Python 3.2+. To help maintaining a version you want and expect, a versioning
scheme is used where:</p>
<ul class="simple">
<li>the first three numbers indicate the version of Python 3.x from which the
backport is done</li>
<li>a backport release number is provided after the <tt class="docutils literal"><span class="pre">r</span></tt> letter</li>
</ul>
<p>For example, <tt class="docutils literal"><span class="pre">3.3.0r1</span></tt> is the <strong>first</strong> release of <tt class="docutils literal"><span class="pre">configparser</span></tt> compatible
with the library found in Python <strong>3.3.0</strong>.</p>
<p>A single exception from the 100% compatibility principle is that bugs fixed
before releasing another minor Python 3.x.y version <strong>will be included</strong> in the
backport releases done in the mean time. This rule applies to bugs only.</p>
</div>
<div class="section" id="maintenance">
<h2>Maintenance<a class="headerlink" href="#maintenance" title="Permalink to this headline">¶</a></h2>
<p>This backport is maintained on BitBucket by Łukasz Langa, the current vanilla
<tt class="docutils literal"><span class="pre">configparser</span></tt> maintainer for CPython:</p>
<ul class="simple">
<li><a class="reference external" href="https://bitbucket.org/ambv/configparser">configparser Mercurial repository</a></li>
<li><a class="reference external" href="https://bitbucket.org/ambv/configparser/issues">configparser issue tracker</a></li>
</ul>
</div>
<div class="section" id="change-log">
<h2>Change Log<a class="headerlink" href="#change-log" title="Permalink to this headline">¶</a></h2>
<div class="section" id="r2">
<h3>3.3.0r2<a class="headerlink" href="#r2" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>updated the fix for <a class="reference external" href="http://bugs.python.org/issue16820">#16820</a>: parsers
now preserve section order when using <tt class="docutils literal"><span class="pre">__setitem__</span></tt> and <tt class="docutils literal"><span class="pre">update</span></tt></li>
</ul>
</div>
<div class="section" id="r1">
<h3>3.3.0r1<a class="headerlink" href="#r1" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>compatible with 3.3.0 + fixes for <a class="reference external" href="http://bugs.python.org/issue15803">#15803</a> and <a class="reference external" href="http://bugs.python.org/issue16820">#16820</a></li>
<li>fixes <a class="reference external" href="https://bitbucket.org/ambv/configparser/issue/4">BitBucket issue #4</a>: <tt class="docutils literal"><span class="pre">read()</span></tt> properly
treats a bytestring argument as a filename</li>
<li><a class="reference external" href="http://pypi.python.org/pypi/ordereddict">ordereddict</a> dependency required
only for Python 2.6</li>
<li><a class="reference external" href="http://pypi.python.org/pypi/unittest2">unittest2</a> explicit dependency
dropped. If you want to test the release, add <tt class="docutils literal"><span class="pre">unittest2</span></tt> on your own.</li>
</ul>
</div>
<div class="section" id="r3">
<h3>3.2.0r3<a class="headerlink" href="#r3" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>proper Python 2.6 support<ul>
<li>explicitly stated the dependency on <a class="reference external" href="http://pypi.python.org/pypi/ordereddict">ordereddict</a></li>
<li>numbered all formatting braces in strings</li>
</ul>
</li>
<li>explicitly says that Python 2.5 support won’t happen (too much work necessary
without abstract base classes, string formatters, the <tt class="docutils literal"><span class="pre">io</span></tt> library, etc.)</li>
<li>some healthy advertising in the README</li>
</ul>
</div>
<div class="section" id="id7">
<h3>3.2.0r2<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>a backport-specific change: for convenience and basic compatibility with the
old ConfigParser, bytestrings are now accepted as section names, options and
values. Those strings are still converted to Unicode for internal storage so
in any case when such conversion is not possible (using the ‘ascii’ codec),
UnicodeDecodeError is raised.</li>
</ul>
</div>
<div class="section" id="id8">
<h3>3.2.0r1<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>the first public release compatible with 3.2.0 + fixes for <a class="reference external" href="http://bugs.python.org/issue11324">#11324</a>, <a class="reference external" href="http://bugs.python.org/issue11670">#11670</a> and <a class="reference external" href="http://bugs.python.org/issue11858">#11858</a>.</li>
</ul>
</div>
</div>
<div class="section" id="conversion-process">
<h2>Conversion Process<a class="headerlink" href="#conversion-process" title="Permalink to this headline">¶</a></h2>
<p>This section is technical and should bother you only if you are wondering how
this backport is produced. If the implementation details of this backport are
not important for you, feel free to ignore the following content.</p>
<p><tt class="docutils literal"><span class="pre">configparser</span></tt> is converted using <a class="reference external" href="http://pypi.python.org/pypi/3to2">3to2</a>.
Because a fully automatic conversion was not doable, I took the following
branching approach:</p>
<ul class="simple">
<li>the <tt class="docutils literal"><span class="pre">3.x</span></tt> branch holds unchanged files synchronized from the upstream
CPython repository. The synchronization is currently done by manually copying
the required files and stating from which CPython changeset they come from.</li>
<li>the <tt class="docutils literal"><span class="pre">3.x-clean</span></tt> branch holds a version of the <tt class="docutils literal"><span class="pre">3.x</span></tt> code with some tweaks
that make it independent from libraries and constructions unavailable on 2.x.
Code on this branch still <em>must</em> work on the corresponding Python 3.x. You
can check this running the supplied unit tests.</li>
<li>the <tt class="docutils literal"><span class="pre">default</span></tt> branch holds necessary changes which break unit tests on
Python 3.2. Additional files which are used by the backport are also stored
here.</li>
</ul>
<p>The process works like this:</p>
<ol class="arabic simple">
<li>I update the <tt class="docutils literal"><span class="pre">3.x</span></tt> branch with new versions of files. Commit.</li>
<li>I merge the new commit to <tt class="docutils literal"><span class="pre">3.x-clean</span></tt>. Check unit tests. Commit.</li>
<li>If there are necessary changes that can be made in a 3.x compatible manner,
I do them now (still on <tt class="docutils literal"><span class="pre">3.x-clean</span></tt>), check unit tests and commit. If I’m
not yet aware of any, no problem.</li>
<li>I merge the changes from <tt class="docutils literal"><span class="pre">3.x-clean</span></tt> to <tt class="docutils literal"><span class="pre">default</span></tt>. Commit.</li>
<li>If there are necessary changes that <em>cannot</em> be made in a 3.x compatible
manner, I do them now (on <tt class="docutils literal"><span class="pre">default</span></tt>). Note that the changes should still
be written using 3.x syntax. If I’m not yet aware of any required changes,
no problem.</li>
<li>I run <tt class="docutils literal"><span class="pre">./convert.py</span></tt> which is a custom <tt class="docutils literal"><span class="pre">3to2</span></tt> runner for this project.</li>
<li>I run the unit tests with <tt class="docutils literal"><span class="pre">unittest2</span></tt> on Python 2.x. If the tests are OK,
I can prepare a new release. Otherwise, I revert the <tt class="docutils literal"><span class="pre">default</span></tt> branch to
its previous state (<tt class="docutils literal"><span class="pre">hg</span> <span class="pre">revert</span> <span class="pre">.</span></tt>) and go back to Step 3.</li>
</ol>
<p><strong>NOTE:</strong> the <tt class="docutils literal"><span class="pre">default</span></tt> branch holds unconverted code. This is because keeping
the conversion step as the last (after any custom changes) helps managing the
history better. Plus, the merges are nicer and updates of the converter software
don’t create nasty conflicts in the repository.</p>
<p>This process works well but if you have any tips on how to make it simpler and
faster, do enlighten me :)</p>
</div>
<div class="section" id="footnotes">
<h2>Footnotes<a class="headerlink" href="#footnotes" title="Permalink to this headline">¶</a></h2>
<table class="docutils footnote" frame="void" id="id12" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>To somewhat ease migration, passing bytestrings is still supported but
they are converted to Unicode for internal storage anyway. This means
that for the vast majority of strings used in configuration files, it
won’t matter if you pass them as bytestrings or Unicode. However, if you
pass a bytestring that cannot be converted to Unicode using the naive
ASCII codec, a <tt class="docutils literal"><span class="pre">UnicodeDecodeError</span></tt> will be raised. This is purposeful
and helps you manage proper encoding for all content you store in
memory, read from various sources and write back.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id13" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>Life gets much easier when you understand that you basically manage
<strong>text</strong> in your application. You don’t care about bytes but about
letters. In that regard the concept of content encoding is meaningless.
The only time when you deal with raw bytes is when you write the data to
a file. Then you have to specify how your text should be encoded. On
the other end, to get meaningful text from a file, the application
reading it has to know which encoding was used during its creation. But
once the bytes are read and properly decoded, all you have is text. This
is especially powerful when you start interacting with multiple data
sources. Even if each of them uses a different encoding, inside your
application data is held in abstract text form. You can program your
business logic without worrying about which data came from which source.
You can freely exchange the data you store between sources. Only
reading/writing files requires encoding your text to bytes.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="configparser.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">configparser</a><ul>
<li><a class="reference internal" href="#why-you-ll-love-configparser">Why you’ll love <tt class="docutils literal"><span class="pre">configparser</span></tt></a></li>
<li><a class="reference internal" href="#a-few-words-about-unicode">A few words about Unicode</a></li>
<li><a class="reference internal" href="#versioning">Versioning</a></li>
<li><a class="reference internal" href="#maintenance">Maintenance</a></li>
<li><a class="reference internal" href="#change-log">Change Log</a><ul>
<li><a class="reference internal" href="#r2">3.3.0r2</a></li>
<li><a class="reference internal" href="#r1">3.3.0r1</a></li>
<li><a class="reference internal" href="#r3">3.2.0r3</a></li>
<li><a class="reference internal" href="#id7">3.2.0r2</a></li>
<li><a class="reference internal" href="#id8">3.2.0r1</a></li>
</ul>
</li>
<li><a class="reference internal" href="#conversion-process">Conversion Process</a></li>
<li><a class="reference internal" href="#footnotes">Footnotes</a></li>
</ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/README.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="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><a href="configparser.html">ConfigParser 3.3.0r2-1 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2013, Łukasz Langa <lukasz@langa.pl>.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
|