ConfigParser

Python has an excessive number of file parsers, especially given the PyPI. But there is just one standard library package that offers a configuration parser--configparser. The syntax expected by this parser is a conglomeration of many standards, and the parser has several large opt-in features.

Grammar and Grammar Errors

Sections

All options must be set under a section header. Section headers cannot be repeated, or the parser will raise configparser.DuplicateSectionError.

[Section1]
option=1

[Section2]
option=2

Options

Options and values are parsed as strings. The Option and value is delimited by either equals signs (=) or colonos (:). Spaces around the delimiter are ignored, but all other spaces are retained in the option and value. Options must be set with a value, even if it is empty.

[Section]
foo=1
bar=abc
baz=

If the parser is created with allow_no_value=True, options without values are allowed. When gotten, they return None. Otherwise, these options will raise configparser.ParsingError.

[Section]
keyword-instruction

Options must be unique within a section. Repeated settings will raise configparser.DuplicateOptionError.

Parser

In Python 2, the relevent package was ConfigParser. For Python 3 the name was standardized to configparser.

import configparser
c = configparser.ConfigParser()

Interpolation

The parser is capable of interpolation. Given this configuration file:

[Section]
my dir   = /Users
some dir = %(my dir)s/me

The parser can be made to interpret 'some dir' as '/Users/me'.

c = configparser.ConfigParser(interpolation=configparser.BasicInterpolation())

Getters

The primary method of getting a value is the get() method. Gotten values are always strings. (The optional fallback argument can specify a value of any type.)

c.get('Section', 'option')
c.get('Section', 'option', fallback=False)

Sections of the parser can be accessed using the notation parser['section']. This returns a proxy for the internal data structure-if mutated, the parser's data is mutated. This exposes an alternate get() method with a positional fallback value.

s = c['section']
s.get('option', False)

Lastly, there are helper functions for type casting.

c.getint('section', 'option')
c.getfloat('section', 'option')
c.getboolean('section', 'option')

getboolean in particular is useful because it interprets a variety of strings as boolean keywords: true and false, yes and no, on and off, 1 and 0.

Default Values

Defaults are fed into a parser at creation.

c = configparser.ConfigParser({'foo': 'bar'})

Defaults can also be set into the default section. The name of this section can be configured in the parser creation (the default_section keyword argument) or in the package (as the default value for the default_section keyword argument is configparser.DEFAULTSECT).

[DEFAULT]
foo = 1

Hierarchical Values

A common design goal is having default values, then multiple filenames to check for cascading value overwrites.

This design is accomplished by a two-stage import of configuration files.

with open('defaults.conf', 'r') as f:
    c.read_file(f)
c.read(['/etc/my-app.conf', os.path.expanduser('~/.config/my-app/my-app.conf')])

CategoryRicottone