Source code
Revision control
Copy as Markdown
Other Tools
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
<html>
<head>
<title>iniparse</title>
<style type="text/css" title="stylesheet"> @import "style.css"; </style>
</head>
<body>
<div id="title">
<h1 style="font-family: monospace">iniparse</h1>
<p>Better INI parser for Python</p>
</div>
<div class="box">
<div class="boxtitle">Introduction</div>
<div class="boxitem">
<p><code>iniparse</code> is a INI parser for
which is:</p>
<ul>
<li><b>Compatible with <code>
Backward compatible implementations of <code>ConfigParser</code>,
<code>RawConfigParser</code>, and <code>SafeConfigParser</code>
are included that are API-compatible with the Python standard
library.</li>
<li><b>Preserves structure of INI files</b>: Order of sections &
options, indentation, comments, and blank lines are preserved as far
as possible when data is updated.</li>
<li><b>More convenient</b>: Values can be accessed using dotted
notation (<code>cfg.user.name</code>), or using container syntax
(<code>cfg['user']['name']</code>).</li>
<li><b>Extensible</b>: It is possible to add other configuration
formats, and to convert between different formats (as long as the
data models are compatible).</li>
</ul>
<p>It is very useful for config files that are updated both by users
and by programs, since it is very disorienting for a user to have
her config file completely rearranged whenever a program changes it.
iniparse also allows making the order of entries in a config file
significant, which is desirable in applications like image
galleries.</p>
</div>
</div>
<div class="box">
<div class="boxtitle">Examples</div>
<div class="boxitem">
<b>New API:</b>
<ul>
<li>Open an INI file:
<pre>
>>> from iniparse import INIConfig
>>> cfg = INIConfig(file('options.ini'))
</pre>
</li>
<li>Access/Modify data:
<pre>
>>> print cfg.playlist.expand_playlist
True
>>> print cfg.ui.width
150
>>> cfg.ui.width = 200
>>> print cfg['ui']['width']
200
</pre>
</li>
<li>Print data:
<pre>
>>> print cfg
[playlist]
expand_playlist = True
[ui]
display_clock = True
display_qlength = True
width = 200
</pre>
</li>
</ul>
<b>Backward Compatible API:</b>
<ul>
<li>The entire ConfigParser API is supported. This is just a brief
example:
<pre>
>>> from iniparse import ConfigParser
>>> cfgpr = ConfigParser()
>>> cfgpr.read('options.ini')
>>> print cfgpr.get('ui', 'width')
150
>>> cfgpr.set('ui', 'width', 175)
</pre>
</li>
<li>The new API can also be accessed via backward-compatible objects:
<pre>
>>> print cfgpr.data.playlist.expand_playlist
True
>>> cfgpr.data.ui.width = 200
>>> print cfgpr.data.ui.width
200
</pre>
</li>
</ul>
<b>A non-INI example:</b>
<ul>
<li>A simple dotted format is also implemented:
<pre>
>>> from iniparse import BasicConfig
>>> n = BasicConfig()
>>> n.x = 7
>>> n.name.first = 'paramjit'
>>> n.name.last = 'oberoi'
>>> print n.x
7
>>> print n.name.first
'paramjit'
>>> print n
name.first = paramjit
name.last = oberoi
x = 7
</pre>
</li>
<li>Convert to INI:
<pre>
>>> from iniparse import INIConfig
>>> i = INIConfig()
>>> del n.x # since INI doesn't support top-level values
>>> i.import_config(n)
>>> print i
[name]
first = paramjit
last = oberoi
</pre>
</li>
</ul>
</div>
<!-- div class="boxitem">
<p>For more information, see the automatically generated
<a href="iniparse.html">API documentation</a>.</p>
</div -->
</div>
<div id="footer">
<p>
Updated on 15 July 2007
</p>
</div>
</body>
</html>