Configuration parsing and validation.

This module provides parse_config which turns a dictionary of stringy keys and values into a structured and typed configuration object.

For example, an INI file like the following:

simple = true
cards = clubs, spades, diamonds
nested.once = 1
nested.really.deep = 3 seconds
some_file = /var/lib/whatever.txt
sample_rate = 37.1%
interval = 30 seconds

Might be parsed like the following. Note: when running under the baseplate server, The config_parser.items(...) step is taken care of for you and raw_config is passed as the only argument to your factory function.

>>> raw_config = dict(config_parser.items("app:main"))

>>> CARDS = config.OneOf(clubs=1, spades=2, diamonds=3, hearts=4)
>>> cfg = config.parse_config(raw_config, {
...     "simple": config.Boolean,
...     "cards": config.TupleOf(CARDS),
...     "nested": {
...         "once": config.Integer,
...         "really": {
...             "deep": config.Timespan,
...         },
...     },
...     "some_file": config.File(mode="r"),
...     "optional": config.Optional(config.Integer, default=9001),
...     "sample_rate": config.Percent,
...     "interval": config.Fallback(config.Timespan, config.Integer),
... })

>>> print(cfg.simple)

>>> print(
[1, 2, 3]

>>> print(cfg.nested.really.deep)

>>> cfg.some_file.close()

>>> cfg.sample_rate

>>> print(cfg.interval)


baseplate.config.parse_config(config, spec)

Parse options against a spec and return a structured representation.

  • config (dict) – The raw stringy configuration dictionary.
  • spec (dict) – A specification of what the config should look like.

ConfigurationError The configuration violated the spec.


A structured configuration object.

Value Types

Each option can have a type specified. Some types compose with other types to make complicated expressions.


A raw string.


A floating-point number.

baseplate.config.Integer(text=None, base=10)

An integer.

To prevent mistakes, this will raise an error if the user attempts to configure a non-whole number.

Parameters:base (int) – (Optional) If specified, the base of the integer to parse.

True or False, case insensitive.


A remote endpoint to connect to.

Returns an EndpointConfiguration.

If the endpoint is a hostname:port pair, the family will be socket.AF_INET and address will be a two-tuple of host and port, as expected by socket.

If the endpoint contains a slash (/), it will be interpreted as a path to a UNIX domain socket. The family will be socket.AF_UNIX and address will be the path as a string.


A span of time.

This takes a string of the form “1 second” or “3 days” and returns a datetime.timedelta representing that span of time.

Units supported are: milliseconds, seconds, minutes, hours, days.


A base64 encoded block of data.

This is useful for arbitrary binary blobs.


A path to a file.

This takes a path to a file and returns an open file object, like returned by open().

Parameters:mode (str) – an optional string that specifies the mode in which the file is opened.

A percentage.

This takes a string of the form “37.2%” or “44%” and returns a float in the range [0.0, 1.0].


A Unix user name.

The parsed value will be the integer user ID.


A Unix group name.

The parsed value will be the integer group ID.


One of several choices.

For each option, the name is what should be in the configuration file and the value is what it is mapped to.

For example:

OneOf(hearts="H", spades="S")

would parse:




A comma-delimited list of type T.

At least one value must be provided. If you want an empty list to be a valid choice, wrap with Optional().

If you need something custom or fancy for your application, just use a callable which takes a string and returns the parsed value or raises ValueError.

Combining Types

These options are used in combination with other types to form more complex configurations.

baseplate.config.Optional(T, default=None)

An option of type T, or default if not configured.

baseplate.config.Fallback(T1, T2)

An option of type T1, or if that fails to parse, of type T2.

This is useful for backwards-compatible configuration changes.


A group of options of a given type.

This is useful for providing data to the application without the application having to know ahead of time all of the possible keys.

[app:main] = 1383890000 = 1317610000 = 325165000 = 263447000 = 207645000
>>> cfg = config.parse_config(raw_config, {
...     "population": config.DictOf(config.Integer),
... })

>>> len(cfg.population)

>>> cfg.population["br"]

It can also be combined with other configuration specs or parsers to parse more complicated structures:

[app:main] = 1383890000 = Beijing = 1317610000 = New Delhi = 325165000 = Washington D.C. = 263447000 = Jakarta = 207645000 = Brasília
>>> cfg = config.parse_config(raw_config, {
...     "countries": config.DictOf({
...         "population": config.Integer,
...         "capital": config.String,
...     }),
... })

>>> len(cfg.countries)

>>> cfg.countries["cn"].capital

>>> cfg.countries["id"].population

Data Types

class baseplate.config.EndpointConfiguration

A description of a remote endpoint.

This is a 2-tuple of (family and address).

One of socket.AF_INET or socket.AF_UNIX.
An address appropriate for the family.


exception baseplate.config.ConfigurationError(key, error)

Raised when the configuration violates the spec.