Welcome to ConfigFile’s documentation!

This library provides the ConfigFile class, whose goal is to provide an interface for parsing, modifying and writing configuration files.

Main features:

• Support for subsections. Support for sectionless options (root options).
• Read from multiple sources (files, file-like objects, dictionaries or special compatible objects) and compose them in a single ConfigFile object.
• When importing and exporting it is possible to choose what to do with options only existing in the source, only existing in the destination, or existing in both with different values.
• Import a configuration source into a particular subsection of an existing object. Export only a particular subsection of an existing object.
• Preserve the order of sections and options when exporting. Try the best to preserve any comments too.
• Access sections and options with the root('Section', 'Subsection')['option'] syntax or the root('Section')('Subsection')['option'] syntax.
• save references to subsections with e.g. subsection = section('Section', 'Subsection').
• Interpolation of option values between sections when importing.

Author: Dario Giovannetti <dev@dariogiovannetti.net>

License: GPLv3

GitHub: https://www.github.com/kynikos/lib.py.configfile

Issue tracker: https://www.github.com/kynikos/lib.py.configfile/issues

Note: as it is clear by reading this page, the documentation is still in a poor state. If you manage to understand how this library works and want to help documenting it, you are welcome to fork the GitHub repository and request to pull your improvements. Everything is written in docstrings in the only python module of the package.

Also, if you have any questions, do not hesitate to ask in the issue tracker, or write the author an email!

Examples

Basic usage

Suppose you have these two files:

/path/to/file:

root_option = demo

[Section1]
test = ok
retest = no
test3 = yes

[Section2.Section2A]
foo = fooo

[Section3]
bar = yay

/path/to/other_file:

[Section2C]
an_option = 2

Now run this script:

from configfile import ConfigFile

conf = ConfigFile("/path/to/file")

conf("Section2").upgrade("path/to/other_file")

option = conf("Section2", "Section2C")["an_option"]
print(option, type(option))  # 2 <class 'str'>

option = conf("Section2")("Section2C").get_int("an_option")
print(option, type(option))  # 2 <class 'int'>

conf.export_add("/path/to/file")

conf["root_option"] = "value"

conf("Section3").export_reset("/path/to/another_file")

You will end up with these files (/path/to/other_file is left untouched):

/path/to/file:

root_option = demo

[Section1]
test = ok
retest = no
test3 = yes

[Section2.Section2A]
foo = fooo

[Section2.Section2C]
an_option = 2

[Section3]
bar = yay

/path/to/another_file:

bar = yay

Interpolation

Suppose you have this file:

/path/to/file:

[Section1]
option = foo ${$:Section2$:optionA$}

[Section1.Section2]
optionA = some value
optionB = ${optionA$} test
optionC = test ${$:optionA$}

[Section3]
option = ${Section1$:Section2$:optionA$} bar

Now run this script:

from configfile import ConfigFile

conf = ConfigFile("/path/to/file", interpolation=True)

print(conf('Section1')['option'])  # foo some value
print(conf('Section1', 'Section2')['optionA'])  # some value
print(conf('Section1', 'Section2')['optionB'])  # some value test
print(conf('Section1', 'Section2')['optionC'])  # test some value
print(conf('Section3')['option'])  # some value bar

Module contents

class configfile.Section(name=None, parent=None, safe_calls=False, inherit_options=False, subsections=True, ignore_case=True)

Bases: object

The class for a section in the configuration file, including the root section. You should never need to instantiate this class directly, use ConfigFile instead.

_PARSE_SECTION = '^\\s*\\[(.+)\\]\\s*$'

_PARSE_OPTION = '^\\s*([^\\=]+?)\\s*\\=\\s*(.*?)\\s*$'

_PARSE_COMMENT = '^\\s*[#;]{1}\\s*(.*?)\\s*$'

_PARSE_IGNORE = '^\\s*$'

_SECTION_SUB = '^[a-zA-Z_]+(?:\\.?[a-zA-Z0-9_]+)*$'

_SECTION_PLAIN = '^[a-zA-Z_]+[a-zA-Z0-9_]*$'

_OPTION = '^[a-zA-Z_]+[a-zA-Z0-9_]*$'

_VALUE = '^.*$'

_SECTION_SEP = '.'

_OPTION_SEP = ' = '

_SECTION_MARKERS = '[{}]'

_COMMENT_MARKER = '# '

_INTERPOLATION_SPECIAL = '$'

_INTERPOLATION_SPECIAL_ESC = '$$'

_INTERPOLATION_START = '${'

_INTERPOLATION_SEP = '$:'

_INTERPOLATION_END = '$}'

_INTERPOLATION_SPLIT = '(\\$\\$|\\$\\{|\\$:|\\$\\})'

_GET_BOOLEAN_TRUE = ('true', '1', 'yes', 'on', 'enabled')

_GET_BOOLEAN_FALSE = ('false', '0', 'no', 'off', 'disabled')

_GET_BOOLEAN_DEFAULT = None

_DICT_CLASS

alias of collections.OrderedDict

_EMPTY_SECTION()

__init__(name=None, parent=None, safe_calls=False, inherit_options=False, subsections=True, ignore_case=True)

Constructor.

Parameters:

• name (str) – The name of the section.
• parent (Section) – A reference to the parent section object.
• safe_calls (bool) – If True, when calling a non-existent subsection, its closest existing ancestor is returned.
• inherit_options (bool) – Whether the section will inherit the options from its ancestors.
• subsections (bool) – If True, subsections are enabled; otherwise they are disabled.
• ignore_case (bool) – If True, section and option names will be compared ignoring case differences; regular expressions will use re.I flag.

__call__(*path, **kwargs)

Enables calling directly the object with a string or sequence of strings, returning the corresponding subsection object, if existent.

Parameters:

• path (str) – A sequence of strings, representing a relative path of section names to the target descendant subsection, whose name is the last item.
• safe (bool) – If True, when calling a non-existent subsection, its closest existing ancestor is returned.

_finalize_call(safe, sname)

Auxiliary method for __call__().

Process a not-found section name.

__getitem__(opt)

Returns the value for the option specified.

Parameters:opt (str) – The name of the option whose value must be returned.

__setitem__(opt, val)

Stores the provided value in the specified option.

Parameters:

• opt (str) – The name of the option.
• val (str) – The new value for the option.

__delitem__(opt)

Deletes the specified option.

Parameters:opt (str) – The name of the option that must be deleted.

__iter__()

Lets iterate over the options of the section (for example with a for loop).

__contains__(item)

If item is a Section object, this method returns True if item (the object, not its name) is a subsection of self; otherwise this returns True if item is the name of an option in self.

Parameters:item (Section or str) – A Section object or the name of an option.

set(opt, val)

This is an alias for __setitem__().

make_subsection(name)

Create an empty subsection under the current section if it does not exist.

Parameters:name (str) – The name of the new subsection.

delete()

Delete the current section.

upgrade(*sources, **kwargs)

Import sections and options from a file, file-like object, dictionary or special object with upgrade mode.

If an option already exists, change its value; if it does not exist, create it and store its value. For example:

{A:a,B:b,C:c} upgrade {A:d,D:e} => {A:d,B:b,C:c,D:e}

See _import_object() for object compatibility.

Parameters:

• sources – A sequence of files, file-like objects, dictionaries and/or special objects.
• interpolation (bool) – Enable/disable value interpolation.

update(*sources, **kwargs)

Import sections and options from a file, file-like object, dictionary or special object with update mode.

If an option already exists, change its value; if it does not exist, do not do anything. For example:

{A:a,B:b,C:c} update {A:d,D:e} => {A:d,B:b,C:c}

See _import_object() for object compatibility.

Parameters:

• sources – A sequence of files, file-like objects, dictionaries and/or special objects.
• interpolation (bool) – Enable/disable value interpolation.

reset(*sources, **kwargs)

Import sections and options from a file, file-like object, dictionary or special object with reset mode.

Delete all options and subsections and recreate everything from the importing object. For example:

{A:a,B:b,C:c} reset {A:d,D:e} => {A:d,D:e}

See _import_object() for object compatibility.

Parameters:

• sources – A sequence of files, file-like objects, dictionaries and/or special objects.
• interpolation (bool) – Enable/disable value interpolation.

add(*sources, **kwargs)

Import sections and options from a file, file-like object, dictionary or special object with add mode.

If an option already exists, do not do anything; if it does not exist, create it and store its value. For example:

{A:a,B:b,C:c} add {A:d,D:e} => {A:a,B:b,C:c,D:e}

See _import_object() for object compatibility.

Parameters:

• sources – A sequence of files, file-like objects, dictionaries and/or special objects.
• interpolation (bool) – Enable/disable value interpolation.

_import(sources, overwrite=True, add=True, reset=False, interpolation=False)

Parse some files, file-like objects, dictionaries or special objects and add their configuration to the existing one.

Distinction between the various source types is done automatically.

Parameters:

• sources – A sequence of all the file names, file-like objects, dictionaries or special objects to be parsed; a value of None will be ignored (useful for creating empty objects that will be populated programmatically).
• overwrite (bool) – This sets whether the next source in the chain overwrites already imported sections and options; see _import_object() for more details.
• add (bool) – This sets whether the next source in the chain adds non-pre-existing sections and options; see _import_object for more details.
• reset (bool) – This sets whether the next source in the chain removes all the data added by the previous sources.
• interpolation (bool) – If True, option values will be interpolated using values from other options through the special syntax ${section$:section$:option$}. Options will be interpolated only once at importing: all links among options will be lost after importing.

_open_file(cfile)

Open config file for reading.

Parameters:cfile (str) – The name of the file to be parsed.

_parse_file(stream)

Parse a text file and translate it into a compatible object, thus making it possible to import it.

Parameters:stream – a file-like object to be read from.

_parse_subsections(re)

Parse the sections hierarchy in a section line of a text file and return them in a list.

Parameters:re – regular expression object.

_import_object(cobj, overwrite=True, add=True, reset=False)

Import sections and options from a compatible object.

Parameters:

• cobj –

  A special object composed of dictionaries (or compatible mapping object) and tuples to be imported; a section is represented by a 2-tuple: its first value is a mapping object that associates the names of options to their values; its second value is a mapping object that associates the names of subsections to their 2-tuples. For example:

  cobj = (
      {
          'option1': 'value',
          'option2': 'value'
      },
      {
          'sectionA': (
              {
                  'optionA1': 'value',
                  'optionA2': 'value',
              },
              {
                  'sectionC': (
                      {
                          'optionC1': 'value',
                          'optionC2': 'value',
                      },
                      {},
                  ),
              },
          ),
          'sectionB': (
              {
                  'optionB1': 'value',
                  'optionB2': 'value'
              },
              {},
          ),
      },
  )
  

• overwrite (bool) – Whether imported data will overwrite pre-existing data.
• add (bool) – Whether non-pre-existing data will be imported.
• reset (bool) – Whether pre-existing data will be cleared.

_import_object_option(overwrite, add, reset, opt, val)

Auxiliary method for _import_object().

Import the currently-examined option.

_import_object_subsection(overwrite, add, reset, sec, secd)

Auxiliary method for _import_object().

Import the currently-examined subsection.

_import_object_subsection_create(overwrite, add, sec, secd)

Auxiliary method for _import_object_subsection().

Import the currently-examined subsection.

_interpolate()

Interpolate values among different options.

The $ sign is a special character: a $ not followed by $, {, : or } will be left $; $$ will be translated as $ both inside or outside an interpolation path; ${ will be considered as the beginning of an interpolation path, unless it is found inside another interpolation path, and in the latter case it will be left ${; $: will be considered as a separator between sections of an interpolation path, unless it is found outside of an interpolation path, and in the latter case it will be left $:; $} will be considered as the end of an interpolation path, unless it is found outside of an interpolation path, and in the latter case it will be left $}.

Normally all paths will be resolved based on the root section of the file; anyway, if the interpolation path has only one item, it will be resolved as an option relative to the current section; otherwise, if the path starts with $:, the first item will be considered as a section (or an option, if last in the list) relative to the current section.

get(opt, fallback=None, inherit_options=None)

Returns the value for the option specified.

Parameters:

• opt (str) – The name of the option whose value must be returned.
• fallback (str or None) – If set to a string, and the option is not found, this method returns that string; if set to None (default) it returns KeyError.
• inherit_options (bool) – If True, if the option is not found in the current section, it is searched in the parent sections; note that this can be set as a default for the object, but this setting overwrites it only for this call.

get_str(opt, fallback=None, inherit_options=None)

This is an alias for get().

This will always return a string.

Parameters:

• opt (str) – The name of the option whose value must be returned.
• fallback (str or None) – If set to a string, and the option is not found, this method returns that string; if set to None (default) it returns KeyError.
• inherit_options (bool) – If True, if the option is not found in the current section, it is searched in the parent sections; note that this can be set as a default for the object, but this setting overwrites it only for this call.

get_int(opt, fallback=None, inherit_options=None)

This method tries to return an integer from the value of an option.

Parameters:

• opt (str) – The name of the option whose value must be returned.
• fallback (str or None) – If set to a string, and the option is not found, this method returns that string; if set to None (default) it returns KeyError.
• inherit_options (bool) – If True, if the option is not found in the current section, it is searched in the parent sections; note that this can be set as a default for the object, but this setting overwrites it only for this call.

get_float(opt, fallback=None, inherit_options=None)

This method tries to return a float from the value of an option.

Parameters:

• opt (str) – The name of the option whose value must be returned.
• fallback (str or None) – If set to a string, and the option is not found, this method returns that string; if set to None (default) it returns KeyError.
• inherit_options (bool) – If True, if the option is not found in the current section, it is searched in the parent sections; note that this can be set as a default for the object, but this setting overwrites it only for this call.

get_bool(opt, true=(), false=(), default=None, fallback=None, inherit_options=None)

This method tries to return a boolean status (True or False) from the value of an option.

Parameters:

• opt (str) – The name of the option whose value must be returned.
• true (tuple) – A tuple with the strings to be recognized as True.
• false (tuple) – A tuple with the strings to be recognized as False.
• default – If the value is neither in true nor in false tuples, return this boolean status; if set to None, it raises a ValueError exception.
• fallback – If set to None (default), and the option is not found, it raises KeyError; otherwise this value is evaluated with the true and false tuples, or the default value.
• inherit_options (bool) – If True, if the option is not found in the current section, it is searched in the parent sections; note that this can be set as a default for the object, but this setting overwrites it only for this call.

Note that the characters in the strings are compared in lowercase, so there is no need to specify all casing variations of a string.

_get_ancestors()

Return a list with the ancestors of the current section, but not the current section itself.

_get_descendants()

Return a list with the descendants of the current section, but not the current section itself.

get_options(ordered=True, inherit_options=None)

Return a dictionary with a copy of option names as keys and their values as values.

Parameters:

• ordered (bool) – If True, return an ordered dictionary; otherwise return a normal dictionary.
• inherit_options (bool) – If True, options are searched also in the parent sections; note that this can be set as a default for the object, but this setting overwrites it only for this call.

get_sections()

Return a view of the names of the child sections.

get_tree(ordered=True, path=False)

Return a compatible object with options and subsections.

Parameters:

• ordered (bool) – If True, the object uses ordered dictionaries; otherwise it uses normal dictionaries.
• path (bool) – If True, return the current section as a subsection of the parent sections.

_recurse_tree(ordered=True)

Auxiliary recursor for get_tree().

_export(targets, overwrite=True, add=True, reset=False, path=True)

Export the configuration to one or more files.

Parameters:

• targets – A sequence with the target file names.
• overwrite (bool) – This sets whether sections and options in the file are overwritten; see _import_object for more details.
• add (bool) – This sets whether non-pre-existing sections and option are added; see _import_object for more details.
• path (bool) – If True, section names are exported with their full path.

export_upgrade(*targets, **kwargs)

Export sections and options to one or more files with upgrade mode.

If an option already exists, change its value; if it does not exist, create it and store its value. For example:

{A:d,D:e} upgrade {A:a,B:b,C:c} => {A:d,B:b,C:c,D:e}

See _export_file() for object compatibility.

Parameters:

• targets – A sequence with the target file names.
• path (bool) – If True, section names are exported with their full path.

export_update(*targets, **kwargs)

Export sections and options to one or more files with update mode.

If an option already exists, change its value; if it does not exist, do not do anything. For example:

{A:d,D:e} update {A:a,B:b,C:c} => {A:d,B:b,C:c}

See _export_file() for object compatibility.

Parameters:

• targets – A sequence with the target file names.
• path (bool) – If True, section names are exported with their full path.

export_reset(*targets, **kwargs)

Export sections and options to one or more files with reset mode.

Delete all options and subsections and recreate everything from the importing object. For example:

{A:d,D:e} reset {A:a,B:b,C:c} => {A:d,D:e}

See _export_file() for object compatibility.

Parameters:

• targets – A sequence with the target file names.
• path (bool) – If True, section names are exported with their full path.

export_add(*targets, **kwargs)

Export sections and options to one or more files with add mode.

If an option already exists, do not do anything; if it does not exist, create it and store its value. For example:

{A:d,D:e} add {A:a,B:b,C:c} => {A:a,B:b,C:c,D:e}

See _export_file() for object compatibility.

Parameters:

• targets – A sequence with the target file names.
• path (bool) – If True, section names are exported with their full path.

_export_file(cfile, overwrite=True, add=True, reset=False, path=True)

Export the sections tree to a file.

Parameters:

• efile (str) – The target file name.
• overwrite (bool) – Whether sections and options already existing in the file are overwritten.
• add (bool) – Whether non-pre-existing data will be exported.
• path (bool) – If True, section names are exported with their full path.

_export_file_existing_option(stream, line, re_option, readonly_section, remaining_options, overwrite, reset)

Auxiliary method for _export_file().

Write the option currently examined from the destination file.

_export_file_remaining_options(stream, readonly_section, remaining_options)

Auxiliary method for _export_file().

Write the options from the origin object that were not found in the destination file.

_export_file_existing_section(stream, line, re_section, ROOT_SECTION, BASE_SECTION, remaining_descendants, path)

Auxiliary method for _export_file().

Write the section currently examined from the destination file.

_export_file_remaining_sections(stream, BASE_SECTION, remaining_descendants, path)

Auxiliary method for _export_file().

Write the sections and their options from the origin object that were not found in the destination file.

_export_other_lines(stream, other_lines, readonly_section, reset)

Auxiliary method for _export_file().

_export_other_lines_before_existing_section(stream, other_lines, readonly_section, reset)

Auxiliary method for _export_file().

class configfile.ConfigFile(*sources, **kwargs)

Bases: configfile.Section

The main configuration object.

__init__(*sources, **kwargs)

Constructor.

Parameters:

• sources (str, dict or special object (see Section._import_object())) – A sequence of all the files, file-like objects, dictionaries and special objects to be parsed.
• mode (str) – This sets if and how the next source in the chain overwrites already imported sections and options; available choices are 'upgrade', 'update', 'reset' and 'add' (see the respective methods for more details).
• safe_calls (bool) – If True, when calling a non-existent subsection, its closest existing ancestor is returned.
• inherit_options (bool) – If True, if an option is not found in a section, it is searched in the parent sections.
• ignore_case (bool) – If True, section and option names will be compared ignoring case differences; regular expressions will use re.I flag.
• subsections (bool) – If True (default) subsections are allowed.
• interpolation (bool) – If True, option values will be interpolated using values from other options through the special syntax ${section$:section$:option$}. Options will be interpolated only once at importing: all links among options will be lost after importing.

exception configfile.ConfigFileError

Bases: Exception

The root exception, useful for catching generic errors from this module.

exception configfile.ParsingError

Bases: configfile.ConfigFileError

An error, overcome at parse time, due to bad file formatting.

exception configfile.NonExistentFileError

Bases: configfile.ConfigFileError

A non-existent configuration file.

exception configfile.InvalidFileError

Bases: configfile.ConfigFileError

An invalid configuration file.

exception configfile.InvalidObjectError

Bases: configfile.ConfigFileError

An invalid key found in an importing object.