pydoctor._configparser

module documentation

(source)

Useful extension to configargparse config file parsers.

Provides configargparse.ConfigFileParser classes to parse TOML and INI files with **mandatory** support for sections. Useful to integrate configuration into project files like pyproject.toml or setup.cfg.

TomlConfigParser usage:

>>> TomlParser = TomlConfigParser(['tool.my_super_tool']) # Simple TOML parser.
>>> parser = ArgumentParser(..., default_config_files=['./pyproject.toml'], config_file_parser_class=TomlParser)

IniConfigParser works the same way (also it optionaly convert multiline strings to list with argument split_ml_text_to_list).

CompositeConfigParser usage:

>>> MY_CONFIG_SECTIONS = ['tool.my_super_tool', 'tool:my_super_tool', 'my_super_tool']
>>> TomlParser =  TomlConfigParser(MY_CONFIG_SECTIONS)
>>> IniParser = IniConfigParser(MY_CONFIG_SECTIONS, split_ml_text_to_list=True)
>>> MixedParser = CompositeConfigParser([TomlParser, IniParser]) # This parser supports both TOML and INI formats.
>>> parser = ArgumentParser(..., default_config_files=['./pyproject.toml', 'setup.cfg', 'my_super_tool.ini'], config_file_parser_class=MixedParser)

Class	`CompositeConfigParser`	A config parser that understands multiple formats.
Class	`IniConfigParser`	INI parser with support for sections.
Class	`TomlConfigParser`	TOML parser with support for sections.
Class	`ValidatorParser`	A parser that warns when unknown options are used. It must be created with a reference to the ArgumentParser object, so like:
Function	`get_toml_section`	Given some TOML data (as loaded with `toml.load()`), returns the requested section of the data. Returns `None` if the section is not found.
Function	`is_quoted`	Detect whether a string is a quoted representation.
Function	`parse_toml_section_name`	Parse a TOML section name to a sequence of strings.
Function	`toml_load`	Undocumented
Function	`unquote_str`	Unquote a maybe quoted string representation. If the string is not detected as being a quoted representation, it returns the same string as passed. It supports all kinds of python quotes: `"""`, `'''`, `"` and ...
Constant	`_QUOTED_STR_REGEX`	Undocumented
Constant	`_TRIPLE_QUOTED_STR_REGEX`	Undocumented

def get_toml_section(data: dict[str, Any], section: tuple[str, ...] | str) -> dict[str, Any] | None: (source) ¶

Given some TOML data (as loaded with toml.load()), returns the requested section of the data. Returns None if the section is not found.

@functools.lru_cache(maxsize=256, typed=True)

def is_quoted(text: str, triple: bool = True) -> bool: (source) ¶

Detect whether a string is a quoted representation.

Parameters
text:`str`	Undocumented
triple:`bool`	Also match tripple quoted strings.

Returns
`bool`	Undocumented

def parse_toml_section_name(section_name: str) -> tuple[str, ...]: (source) ¶

Parse a TOML section name to a sequence of strings.

The following names are all valid:

    "a.b.c"            # this is best practice -> returns ("a", "b", "c")
    " d.e.f "          # same as [d.e.f] -> returns ("d", "e", "f")
    " g .  h  . i "    # same as [g.h.i] -> returns ("g", "h", "i")
    ' j . "ʞ" . "l" '  # same as [j."ʞ"."l"], double or simple quotes here are supported. -> returns ("j", "ʞ", "l")

def toml_load(stream: TextIO) -> Any: (source) ¶

Undocumented

def unquote_str(text: str, triple: bool = True) -> str: (source) ¶

Unquote a maybe quoted string representation. If the string is not detected as being a quoted representation, it returns the same string as passed. It supports all kinds of python quotes: """, ''', " and '.

Parameters
text:`str`	Undocumented
triple:`bool`	Also unquote tripple quoted strings.

Returns
`str`	Undocumented

Raises
`ValueError`	If the string is detected as beeing quoted but literal_eval() fails to evaluate it as string. This would be a bug in the regex.

_QUOTED_STR_REGEX = (source) ¶

Undocumented

Value

re.compile(r'(^"(?:\\.|[^"\\])*"$)|(^\'(?:\\.|[^\'\\])*\'$)')

_TRIPLE_QUOTED_STR_REGEX = (source) ¶

Undocumented

Value

re.compile(r'(^"""(\s+)?(([^"]|"([^"]|"[^"]))*(""?)?)?(\s+)?(?:\\.|[^"\\])"""$)|↵
(^\'\'\'(\s+)?(([^\']|\'([^\']|\'[^\']))*(\'\'?)?)?(\s+)?(?:\\.|[^\'\\])\'\'\'$)'↵
,
           re.DOTALL)