Configuration Schema#

In order to simplify the usage of the PeakRDL configuration TOML, a simple configuration validation and data extraction schema is provided.

This provides an intuitive way for plugin developers to define what TOML configuration options exist, as well as their expected datatypes.

Example#

Consider an exporter plugin that wants to define some additional configuration options for the PeakRDL TOML as follows:

[my-exporter]
# Expects an integer
max_depth = 1234

# Expects a list of strings
prefixes = ["my_prefix", "other_prefix"]

# Expects a file path
extra_file_path = "../path/to/thing.txt"

The expected datatype structure of these options can be defined in the descriptor class as follows:

from peakrdl.plugins.exporter import ExporterSubcommandPlugin
from peakrdl.config import schema

class MyExporter(ExporterSubcommandPlugin):

    cfg_schema = {
        "max_depth": schema.Integer(),
        "prefixes": [schema.String()],
        "extra_file_path": schema.FilePath(),
    }

Then, when performing the export in the do_export() method, the values of these options can be queried as follows:

def do_export(self, top_node: 'AddrmapNode', options: 'argparse.Namespace') -> None:
    self.cfg['max_depth']
    self.cfg['prefixes']
    self.cfg['extra_file_path']

Lists and Mappings#

When defining your configuration schema, lists and mapping schemas can be defined using a shorthand notation.

A list of uniform element types can be defined by enclosing the element’s schema in a list:

# Defines a schema for a list of integers
[schema.Integer()]

A mapping of fixed key:value pairs can be defined as a dictionary that describes each mapping member:

{
    "an_integer": schema.Integer(),
    "a_string": schema.String(),
}

A mapping that accepts any user-defined keys with a uniform value:

{"*": schema.Integer()}

Default values#

After extraction, if a configuration value is not explicitly specified by the user, the resulting configuration data structure will contain the following:

Fixed mappings will contain all the expected keys. Values will contain their default value as specified by this section.
A mapping with user-defined keys will default to be empty.
A list will default to be empty
All other values will default to None

Schema Object Reference#

Base Datatypes#

class peakrdl.config.schema.String#: Matches a string.

class peakrdl.config.schema.Integer#: Matches an integer.

class peakrdl.config.schema.Float#: Matches a float.

class peakrdl.config.schema.Boolean#: Matches a boolean.

class peakrdl.config.schema.DateTime#: Matches a date + time.

class peakrdl.config.schema.Date#: Matches a date.

class peakrdl.config.schema.Time#: Matches a time.

class peakrdl.config.schema.AnyType#: Wildcard. Matches any type.

Paths#

class peakrdl.config.schema.Path(shall_exist: bool = True)#: Matches any path

class peakrdl.config.schema.FilePath(shall_exist: bool = True)#: Matches a path to a file

class peakrdl.config.schema.DirectoryPath(shall_exist: bool = True)#: Matches a path to a directory

Python Objects#

class peakrdl.config.schema.PythonObjectImport#: Matches a string that specifies a Python object to import. For example: "my.module.path:ObjectName"

Misc#

class peakrdl.config.schema.Choice(choices: List[str])#: Schema that matches against a specific set of allowed strings

Configuration Schema

Contents