dom_toml.parser


Abstract base class for TOML configuration parsers.

New in version 0.2.0.

Classes:

AbstractConfigParser()

Abstract base class for TOML configuration parsers.

Exceptions:

BadConfigError(*args[, documentation])

Indicates an error in the TOML configuration.

Functions:

construct_path(path)

Construct a dotted path to a key.

class AbstractConfigParser[source]

Bases: ABC

Abstract base class for TOML configuration parsers.

Methods:

assert_indexed_type(obj, expected_type, path)

Assert that obj is of type expected_type, otherwise raise an error with a helpful message.

assert_type(obj, expected_type, path[, what])

Assert that obj is of type expected_type, otherwise raise an error with a helpful message.

assert_value_type(obj, expected_type, path)

Assert that the value obj is of type expected_type, otherwise raise an error with a helpful message.

parse(config[, set_defaults])

Parse the TOML configuration.

Attributes:

defaults

A mapping of key names to default values.

factories

A mapping of key names to default value factories.

keys

The keys to parse from the TOML file.

static assert_indexed_type(obj, expected_type, path, idx=0)[source]

Assert that obj is of type expected_type, otherwise raise an error with a helpful message.

Parameters
  • obj (Any) – The object to check the type of.

  • expected_type (Union[Type, Tuple[Type, …]]) – The expected type.

  • path (Iterable[str]) – The elements of the path to obj in the TOML mapping.

  • idx (int) – The index of obj in the array. Default 0.

static assert_type(obj, expected_type, path, what='type')[source]

Assert that obj is of type expected_type, otherwise raise an error with a helpful message.

Parameters
  • obj (Any) – The object to check the type of.

  • expected_type (Union[Type, Tuple[Type, …]]) – The expected type.

  • path (Iterable[str]) – The elements of the path to obj in the TOML mapping.

  • what (str) – What obj is, e.g. 'type', 'value type'. Default 'type'.

assert_value_type(obj, expected_type, path)[source]

Assert that the value obj is of type expected_type, otherwise raise an error with a helpful message.

Parameters
  • obj (Any) – The object to check the type of.

  • expected_type (Union[Type, Tuple[Type, …]]) – The expected type.

  • path (Iterable[str]) – The elements of the path to obj in the TOML mapping.

defaults

Type:    ClassVar[Dict[str, Any]]

A mapping of key names to default values.

New in version 0.3.0.

factories

Type:    ClassVar[Dict[str, Callable[…, Any]]]

A mapping of key names to default value factories.

New in version 0.3.0.

Note

If both a default and a factory are defined for a key the factory takes precedence.

Note

defaults and factories are reset for each subclass. To disable this behaviour set the inherit_defaults keyword argument on the class:

class MyParser(AbstractConfigParser, inherit_default=True):
        pass
abstract property keys

The keys to parse from the TOML file.

Return type

List[str]

parse(config, set_defaults=False)[source]

Parse the TOML configuration.

This function iterates over the list of keys given in keys. For each key, it searches for a method on the class called parse_<key>.

  • If the method exists, that method is called, passing the value as the only argument. The value returned from that method is included in the parsed configuration. The signature of those methods is:

    def visit_<key>(
        self,
        config: typing.Dict[str, typing.Any],
        ) -> typing.Any:
  • If the method doesn’t exist, the value is included in the parsed configuration unchanged.

  • Missing keys are ignored. Override this function in a subclass if you need that behaviour.

Once all keys have been parsed the configuration is returned.

Parameters

Changed in version 0.3.0: Added the set_defaults keyword argument.

Return type

Dict[str, Any]

exception BadConfigError(*args, documentation=None)[source]

Bases: ValueError

Indicates an error in the TOML configuration.

Parameters

documentation (Optional[str]) – A link to the documentation that explains the problematic option. This is not used by the class itself, except setting it as the documentation attribute, The intention is for code catching this exception to display this URL to the user. Default None.

Changed in version 0.6.0: Added the documentation keyword argument and attribute.

documentation

Type:    Optional[str]

A link to the documentation that explains the problematic option.

construct_path(path)[source]

Construct a dotted path to a key.

Parameters

path (Iterable[str]) – The path elements.

Return type

str