configupdater package

Submodules

configupdater.configupdater module

Configuration file updater.

A configuration file consists of sections, lead by a “[section]” header, and followed by “name: value” entries, with continuations and such in the style of RFC 822.

The basic idea of ConfigUpdater is that a configuration file consists of three kinds of building blocks: sections, comments and spaces for separation. A section itself consists of three kinds of blocks: options, comments and spaces. This gives us the corresponding data structures to describe a configuration file.

A general block object contains the lines which were parsed and make up the block. If a block object was not changed then during writing the same lines that were parsed will be used to express the block. In case a block, e.g. an option, was changed, it is marked as updated and its values will be transformed into a corresponding string during an update of a configuration file.

Note

ConfigUpdater was created by starting from Python’s ConfigParser source code and changing it according to my needs. Thus this source code is subject to the PSF License in a way but I am not a lawyer.

class configupdater.configupdater.Comment(container)[source]

Bases: configupdater.configupdater.Block

Comment block

class configupdater.configupdater.ConfigUpdater(allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, space_around_delimiters=True)[source]

Bases: configupdater.configupdater.Container, collections.abc.MutableMapping

Parser for updating configuration files.

ConfigUpdater follows the API of ConfigParser with some differences:
  • inline comments are treated as part of a key’s value,

  • only a single config file can be updated at a time,

  • the original case of sections and keys are kept,

  • control over the position of a new section/key.

Following features are deliberately not implemented:

  • interpolation of values,

  • propagation of parameters from the default section,

  • conversions of values,

  • passing key/value-pairs with default argument,

  • non-strict mode allowing duplicate sections and keys.

NONSPACECRE = re.compile('\\S')
OPTCRE = re.compile('\n (?P<option>.*?) # very permissive!\n \\s*(?P<vi>=|:)\\s* # any number of space/tab,\n # followed by any of t, re.VERBOSE)
OPTCRE_NV = re.compile('\n (?P<option>.*?) # very permissive!\n \\s*(?: # any number of space/tab,\n (?P<vi>=|:)\\s* # optionally followed , re.VERBOSE)
SECTCRE = re.compile('\n \\[ # [\n (?P<header>[^]]+) # very permissive!\n \\] # ]\n ', re.VERBOSE)
add_section(section)[source]

Create a new section in the configuration.

Raise DuplicateSectionError if a section by the specified name already exists. Raise ValueError if name is DEFAULT.

Parameters

section (str or Section) – name or Section type

get(section, option, fallback=<object object>)[source]

Gets an option value for a given section.

Parameters
  • section (str) – section name

  • option (str) – option name

  • fallback – if the key is not found and fallback is provided, it will be returned. None is a valid fallback value.

Returns

Option object holding key/value pair

Return type

Option

has_option(section, option)[source]

Checks for the existence of a given option in a given section.

Parameters
  • section (str) – name of section

  • option (str) – name of option

Returns

whether the option exists in the given section

Return type

bool

has_section(section)[source]

Returns whether the given section exists.

Parameters

section (str) – name of section

Returns

wether the section exists

Return type

bool

items(section=<object object>)[source]

Return a list of (name, value) tuples for options or sections.

If section is given, return a list of tuples with (name, value) for each option in the section. Otherwise, return a list of tuples with (section_name, section_type) for each section.

Parameters

section (str) – optional section name, default UNSET

Returns

list of Section or Option objects

Return type

list

options(section)[source]

Returns list of configuration options for the named section.

Parameters

section (str) – name of section

Returns

list of option names

Return type

list

optionxform(optionstr)[source]

Converts an option key to lower case for unification

Parameters

optionstr (str) – key name

Returns

unified option name

Return type

str

read(filename, encoding=None)[source]

Read and parse a filename.

Parameters
  • filename (str) – path to file

  • encoding (str) – encoding of file, default None

read_file(f, source=None)[source]

Like read() but the argument must be a file-like object.

The f argument must be iterable, returning one line at a time. Optional second argument is the source specifying the name of the file being read. If not given, it is taken from f.name. If f has no name attribute, <???> is used.

Parameters
  • f – file like object

  • source (str) – reference name for file object, default None

read_string(string, source='<string>')[source]

Read configuration from a given string.

Parameters
  • string (str) – string containing a configuration

  • source (str) – reference name for file object, default ‘<string>’

remove_option(section, option)[source]

Remove an option.

Parameters
  • section (str) – section name

  • option (str) – option name

Returns

whether the option was actually removed

Return type

bool

remove_section(name)[source]

Remove a file section.

Parameters

name – name of the section

Returns

whether the section was actually removed

Return type

bool

section_blocks()[source]

Returns all section blocks

Returns

list of Section blocks

Return type

list

sections()[source]

Return a list of section names

Returns

list of section names

Return type

list

set(section, option, value=None)[source]

Set an option.

Parameters
  • section (str) – section name

  • option (str) – option name

  • value (str) – value, default None

to_dict()[source]

Transform to dictionary

Returns

dictionary with same content

Return type

dict

update_file(validate=True)[source]

Update the read-in configuration file.

Parameters

validate (Boolean) – validate format before writing

validate_format(**kwargs)[source]

Call ConfigParser to validate config

Parameters

kwargs – are passed to configparser.ConfigParser

write(fp, validate=True)[source]

Write an .ini-format representation of the configuration state.

Parameters
  • fp (file-like object) – open file handle

  • validate (Boolean) – validate format before writing

exception configupdater.configupdater.DuplicateOptionError(section, option, source=None, lineno=None)[source]

Bases: configparser.Error

Raised by strict parsers when an option is repeated in an input source.

Current implementation raises this exception only when an option is found more than once in a single file, string or dictionary.

exception configupdater.configupdater.DuplicateSectionError(section, source=None, lineno=None)[source]

Bases: configparser.Error

Raised when a section is repeated in an input source.

Possible repetitions that raise this exception are: multiple creation using the API or in strict parsers when a section is found more than once in a single input file, string or dictionary.

exception configupdater.configupdater.MissingSectionHeaderError(filename, lineno, line)[source]

Bases: configparser.ParsingError

Raised when a key-value pair is found before any section header.

exception configupdater.configupdater.NoConfigFileReadError[source]

Bases: configparser.Error

Raised when no configuration file was read but update requested.

exception configupdater.configupdater.NoOptionError(option, section)[source]

Bases: configparser.Error

A requested option was not found.

exception configupdater.configupdater.NoSectionError(section)[source]

Bases: configparser.Error

Raised when no section matches a requested option.

class configupdater.configupdater.Option(key, value, container, delimiter='=', space_around_delimiters=True, line=None)[source]

Bases: configupdater.configupdater.Block

Option block holding a key/value pair.

key

name of the key

Type

str

value

stored value

Type

str

updated

indicates name change or a new section

Type

bool

add_line(line)[source]

Add a line to the current block

Parameters

line (str) – one line to add

property key
set_values(values, separator='\n', indent=' ')[source]

Sets the value to a given list of options, e.g. multi-line values

Parameters
  • values (iterable) – sequence of values

  • separator (str) – separator for values, default: line separator

  • indent (str) – indentation depth in case of line separator

property value
exception configupdater.configupdater.ParsingError(source=None, filename=None)[source]

Bases: configparser.Error

Raised when a configuration file does not follow legal syntax.

append(lineno, line)[source]
property filename

Deprecated, use `source’.

class configupdater.configupdater.Section(name, container, **kwargs)[source]

Bases: configupdater.configupdater.Block, configupdater.configupdater.Container, collections.abc.MutableMapping

Section block holding options

name

name of the section

Type

str

updated

indicates name change or a new section

Type

bool

add_comment(line)[source]

Add a Comment object to the section

Used during initial parsing mainly

Parameters

line (str) – one line in the comment

add_option(entry)[source]

Add an Option object to the section

Used during initial parsing mainly

Parameters

entry (Option) – key value pair as Option object

add_space(line)[source]

Add a Space object to the section

Used during initial parsing mainly

Parameters

line (str) – one line that defines the space, maybe whitespaces

insert_at(idx)[source]

Returns a builder inserting a new block at the given index

Parameters

idx (int) – index where to insert

items()[source]

Return a list of (name, option) tuples for each option in this section.

Returns

list of (name, Option) tuples

Return type

list

property name
option_blocks()[source]

Returns option blocks

Returns

list of Option blocks

Return type

list

options()[source]

Returns option names

Returns

list of option names as strings

Return type

list

set(option, value=None)[source]

Set an option for chaining.

Parameters
  • option (str) – option name

  • value (str) – value, default None

to_dict()[source]

Transform to dictionary

Returns

dictionary with same content

Return type

dict

class configupdater.configupdater.Space(container)[source]

Bases: configupdater.configupdater.Block

Vertical space block of new lines

Module contents