configparser2 is derived from Lukasz Langa's configparser mercurial repo. The only difference is a name is not conflicting with the default python3 configparser.
Source Code for configparser2 is on Github.
A quick pip install configparser2
should do the job.
The ancient ConfigParser
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 - 3.5.
To use the configparser2
backport instead of the built-in version on both
Python 2 and Python 3, simply import it explicitly as a backport:
from backports import configparser2
If you'd like to use the backport on Python 2 and the built-in version on Python 3, use that invocation instead:
import configparser2
For detailed documentation consult the vanilla version at http://docs.python.org/3/library/configparser2.html.
Whereas almost completely compatible with its older brother, configparser2
sports a bunch of interesting new features:
full mapping protocol access (more info):
>>> parser = ConfigParser() >>> parser.read_string(""" [DEFAULT] location = upper left visible = yes editable = no color = blue [main] title = Main Menu color = green [options] title = Options """) >>> parser['main']['color'] 'green' >>> parser['main']['editable'] 'no' >>> section = parser['options'] >>> section['title'] 'Options' >>> section['title'] = 'Options (editable: %(editable)s)' >>> section['title'] 'Options (editable: no)'
there's now one default
ConfigParser
class, which basically is the oldSafeConfigParser
with a bunch of tweaks which make it more predictable for users. Don't need interpolation? Simply useConfigParser(interpolation=None)
, no need to use a distinctRawConfigParser
anymore.the parser is highly customizable upon instantiation supporting things like changing option delimiters, comment characters, the name of the DEFAULT section, the interpolation syntax, etc.
you can easily create your own interpolation syntax but there are two powerful implementations built-in (more info):
- the classic
%(string-like)s
syntax (calledBasicInterpolation
) - a new
${buildout:like}
syntax (calledExtendedInterpolation
)
- the classic
fallback values may be specified in getters (more info):
>>> config.get('closet', 'monster', ... fallback='No such things as monsters') 'No such things as monsters'
ConfigParser
objects can now read data directly from strings and from dictionaries. 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 anotherConfigParser
instance, thanks to its mapping protocol support.many smaller tweaks, updates and fixes
configparser2
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
ConfigParser
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.
The design assumes that Unicode strings are used whenever possible [1]. 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 [2]. 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.
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:
- the first two numbers indicate the version of Python 3 from which the backport is done
- a backport release number is provided as the final number (zero-indexed)
For example, 3.5.2
is the third backport release of the
configparser2
library as seen in Python 3.5. Note that 3.5.2
does
NOT necessarily mean this backport version is based on the standard library
of Python 3.5.2.
One exception from the 100% compatibility principle is that bugs fixed before releasing another minor Python 3 bugfix version will be included in the backport releases done in the mean time.
This backport is maintained on BitBucket by Łukasz Langa, the current vanilla
configparser2
maintainer for CPython:
- Change name to configparser2
- a complete rewrite of the backport; now single codebase working on Python
2.6 - 3.5. To use on Python 3 import
from backports import configparser2
instead of the built-in version. - compatible with 3.4.1 + fixes for #19546
- fixes BitBucket issue #1: versioning non-compliant with PEP 386
- fixes BitBucket issue #3:
reload(sys); sys.setdefaultencoding('utf8')
in setup.py - fixes BitBucket issue #5: Installing the backport on Python 3 breaks virtualenv
- fixes BitBucket issue #6: PyPy compatibility
- second beta of 3.5.0, not using any third-party futurization libraries
- first beta of 3.5.0, using python-future
- for the full feature list, see 3.5.0
- updated the fix for #16820: parsers
now preserve section order when using
__setitem__
andupdate
- compatible with 3.3.0 + fixes for #15803 and #16820
- fixes BitBucket issue #4:
read()
properly treats a bytestring argument as a filename - ordereddict dependency required only for Python 2.6
- unittest2 explicit dependency
dropped. If you want to test the release, add
unittest2
on your own.
- proper Python 2.6 support
- explicitly stated the dependency on ordereddict
- numbered all formatting braces in strings
- explicitly says that Python 2.5 support won't happen (too much work necessary
without abstract base classes, string formatters, the
io
library, etc.) - some healthy advertising in the README
- 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.
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.
configparser2
is converted using python-future and free time. Because a fully automatic
conversion was not doable, I took the following branching approach:
- the
3.x
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. - the
default
branch holds a version of the3.x
code with some tweaks that make it independent from libraries and constructions unavailable on 2.x. Code on this branch still must work on the corresponding Python 3.x but will also work on Python 2.6 and 2.7 (including PyPy). You can check this running the supplied unit tests withtox
.
The process works like this:
- I update the
3.x
branch with new versions of files. Commit. - I merge the new commit to
default
. I runtox
. Commit. - If there are necessary changes, I do them now (on
default
). Note that the changes should be written in the syntax subset supported by Python 2.6. - I run
tox
. If it works, I update the docs and release the new version. Otherwise, I go back to point 3. I might usepasteurize
to suggest me required changes but usually I do them manually to keep resulting code in a nicer form.
[1] | 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 UnicodeDecodeError 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. |
[2] | Life gets much easier when you understand that you basically manage text 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. |