pydoctor._configparser.IniConfigParser

INI parser with support for sections.

This parser somewhat ressembles configargparse.ConfigparserConfigFileParser. It uses configparser and evaluate values written with python list syntax.

With the following changes:

• Must be created with argument to bind the parser to a list of sections.
• Does not convert multiline strings to single line.
• Optional support for converting multiline strings to list (if ``split_ml_text_to_list=True``).
• Optional support for quoting strings in config file (useful when text must not be converted to list or when text should contain trailing whitespaces).
• Comments may only appear on their own in an otherwise empty line (like in configparser).

This config parser can be used to integrate with ``setup.cfg`` files.

Example:

    # this is a comment
    ; also a comment
    [my_super_tool]
    # how to specify a key-value pair:
    format-string: restructuredtext 
    # white space are ignored, so name = value same as name=value
    # this is why you can quote strings (double quotes works just as well)
    quoted-string = '       hello   mom...  '
    # how to set an arg which has action="store_true"
    warnings-as-errors = true
    # how to set an arg which has action="count" or type=int
    verbosity = 1
    # how to specify a list arg (eg. arg which has action="append")
    repeatable-option = ["https://docs.python.org/3/objects.inv",
                    "https://twistedmatrix.com/documents/current/api/objects.inv"]
    # how to specify a multiline text:
    multi-line-text = 
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        Vivamus tortor odio, dignissim non ornare non, laoreet quis nunc. 
        Maecenas quis dapibus leo, a pellentesque leo. 
    # how to specify a empty text:
    empty-text = 
    # this also works:
    empty-text = ''
    # how to specify a empty list:
    empty-list = []

If you use IniConfigParser(sections, split_ml_text_to_list=True), the same rules are applicable with the following changes:

    [my-software]
    # to specify a list arg (eg. arg which has action="append"), 
    # just enter one value per line (the list literal format can still be used):
    repeatable-option =
        https://docs.python.org/3/objects.inv
        https://twistedmatrix.com/documents/current/api/objects.inv
    # to specify a multiline text, you have to quote it:
    multi-line-text = '''
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        Vivamus tortor odio, dignissim non ornare non, laoreet quis nunc. 
        Maecenas quis dapibus leo, a pellentesque leo. 
        '''
    # how to specify a empty text:
    empty-text = ''
    # how to specify a empty list:
    empty-list = []
    # the following empty value would be simply ignored because we can't 
    # differenciate between simple value and list value without any data:
    totally-ignored-field = 

Usage:

>>> import configargparse
>>> parser = configargparse.ArgParser(
...             default_config_files=['setup.cfg', 'my_super_tool.ini'],
...             config_file_parser_class=configargparse.IniConfigParser(
...                 ['tool:my_super_tool', 'my_super_tool'], True),
...          )