API

This page documents the API for the cfgclasses package, the high-level structures such as the parse_args() entry point as well as the provided helper functions such as arg().

cfgclasses

cfgclasses are representations of a python tools CLI configuration options built on dataclasses. This allows individual tools to focus on specifying their configuration structure without the overhead of interacting with argparse and the typeless Namespace it returns.

The primary entrypoint for this module is the parse_args() function.

cfgclasses.parse_args(cls, argv, prog=None)

Parse the arguments vector into an instance of the given class.

Parameters:

  • cls (Type[TypeVar(_T)]) – The class to parse the arguments into.

  • argv (Sequence[str]) – The arguments vector to parse.

  • prog (Optional[str]) – The name of the program to display in the help message.

Return type:

cls

Returns:

An instance of the given class with the parsed arguments.

cfgclasses.parse_args_with_submodes(cls, argv, submodes, prog=None)

Parse the arguments vector into an instance of this class and a submode.

The submode will be one of the provided submodes classes populated with the CLI arguments.

Parameters:

  • cls (Type[TypeVar(_T)]) – The class to parse the arguments into.

  • argv (Sequence[str]) – The arguments vector to parse.

  • submodes (dict[str, Type[TypeVar(_U)]]) – Mapping of submode name to submode classes to parse.

  • prog (Optional[str]) – The name of the program to display in the help message.

Return type:

tuple[cls, submode]

Returns:

A tuple of the top-level config and the submode config.

Raises:

ValueError – If no submodes are provided.

Alternative forms that allow for the parsing of unknown arguments are also provided.

cfgclasses.parse_known_args(cls, argv, prog=None)

Parse the known arguments from the input vector into an instance of the given class.

Parameters:

  • cls (Type[TypeVar(_T)]) – The class to parse the arguments into.

  • argv (Sequence[str]) – The arguments vector to parse.

  • prog (Optional[str]) – The name of the program to display in the help message.

Return type:

tuple[cls, list[str]]

Returns:

An instance of the given class with the parsed arguments, plus a list of unknown arguments.

cfgclasses.parse_known_args_with_submodes(cls, argv, submodes, prog=None)

Parse the known arguments from the input vector into an instance of this class and a submode.

The submode will be one of the provided submodes classes populated with the CLI arguments.

Parameters:

  • cls (Type[TypeVar(_T)]) – The class to parse the arguments into.

  • argv (Sequence[str]) – The arguments vector to parse.

  • submodes (dict[str, Type[TypeVar(_U)]]) – Mapping of submode name to submode classes to parse.

  • prog (Optional[str]) – The name of the program to display in the help message.

Return type:

tuple[cls, submode, list[str]]

Returns:

A tuple of the top-level config, the submode config and a list of unknown arguments.

Raises:

ValueError – If no submodes are provided.

Additionally the following functions are provided to simplify the creation of the class fields.

cfgclasses.arg(helpstr, *optnames, positional=False, metavar=None, choices=None, default=<dataclasses._MISSING_TYPE object>, default_factory=<dataclasses._MISSING_TYPE object>, transform=None, transform_type=None)

Create a dataclass field with additional cfgclasses options stored.

Parameters:

  • helpstr (str) – Help string for this fields argument.

  • optnames (str) – Optional list of option names for this fields argument. E.g. ["-v", "--verbose"].

  • positional (bool) – If true, use a positional argument for this field. Cannot be used with optnames.

  • metavar (Optional[str]) – Metavar to display alongside the argument for the field.

  • choices (Optional[list[Any]]) – List of valid choices for the value of this field.

  • default (Any) – Default value for the field if not given on the CLI.

  • default_factory (Any) – Default factory to construct an instance of the field if not given on the CLI.

  • transform (Optional[Callable[[Any], Any]]) – Function to transform the value of the field after parsing from the CLI.

  • transform_type (Optional[Type[Any]]) – Input type for the transform function. I.e. the type read from the CLI.

Return type:

Any

Returns:

The resulting dataclass field.

cfgclasses.optional(helpstr, *optnames, positional=False, metavar=None, choices=None, transform=None, transform_type=None)

Create a field with cfgclasses options with a default of None.

Parameters:

  • helpstr (str) – Help string for this fields argument.

  • optnames (str) – Optional list of option names for this fields argument. E.g. ["-v", "--verbose"].

  • positional (bool) – If true, use a positional argument for this field. Cannot be used with optnames.

  • metavar (Optional[str]) – Metavar to display alongside the argument for the field.

  • choices (Optional[list[Any]]) – List of valid choices for the value of this field.

  • transform (Optional[Callable[[Any], Any]]) – Function to transform the value of the field after parsing from the CLI.

  • transform_type (Optional[Type[Any]]) – Input type for the transform function. I.e. the type read from the CLI.

Return type:

Any

Returns:

The resulting dataclass field.

At a lower level these functions instantiate these classes and add them to the dataclasses.field() metadata in the key cfgclasses.CFG_METADATA_FIELD.

cfgclasses.argspec.CFG_METADATA_FIELD = 'cfgclasses.configopts'

Key in the dataclasses field metadata to store the ConfigOpts in.

class cfgclasses.ConfigOpts(help='', metavar=None, choices=None, transform=None, transform_type=None, default=<factory>)

Data stored in a dataclass field’s metadata for customizing CLI options.

class cfgclasses.NonPositionalConfigOpts(help='', metavar=None, choices=None, transform=None, transform_type=None, default=<factory>, optnames=<factory>)

Config options for a non-positional argument.

There are also equivalents for the creation of nested dataclass definitions.

cfgclasses.cfgtransform(transform_type, transform)

Create a field for a nested dataclass with a transform.

Parameters:

  • transform_type (Type[TypeVar(_T)]) – The type that the transform function takes as input.

  • transform (Callable[[TypeVar(_T)], TypeVar(_U)]) – The transform function to apply.

Return type:

TypeVar(_U)

Returns:

The resulting dataclass field.

Which in turn creates a cfgclasses.ConfigClassTransform object in the key cfgclasses.CFG_METADATA_FIELD.

class cfgclasses.ConfigClassTransform(transform, transform_type)

Data stored in a dataclass field’s metadata for transforming config classes.

There is an additional submodule cfgclasses.transforms containing several common transform functions. See below.

Finally, the following decorators are provided to allow the creation of mutually exclusive groups of options, and adding validation functions to a config class definition respectively.

cfgclasses.mutually_exclusive(cls)

Decorator to mark a class as representing a mutually exclusive group.

Parameters:

cls (Type[TypeVar(_T)]) – The class to mark as mutually exclusive.

Return type:

Type[TypeVar(_T)]

Returns:

The modified input class.

cfgclasses.validator(func)

Decorator to mark a function as a validator for a config class.

Parameters:

func (Callable[[TypeVar(_T)], None]) – The function to mark as a validator.

Return type:

Callable[[TypeVar(_T)], None]

Returns:

The modified input function.

cfgclasses.transforms

Module defining common transform function patterns.

cfgclasses.transforms.filetext(filepath)

Transform function for loading text file contents.

Parameters:

filepath (Union[str, PurePath]) – Path of the file to be loaded.

Return type:

str

Returns:

The contents of the file as a string.

cfgclasses.transforms.filebytes(filepath)

Transform function for loading binary file contents.

Parameters:

filepath (Union[str, PurePath]) – Path of the file to be loaded.

Return type:

bytes

Returns:

The contents of the file as a byte array.

cfgclasses.transforms.jsonfile(filepath)

Transform function for loading JSON files.

Parameters:

filepath (Union[str, PurePath]) – Path of the file to be loaded.

Return type:

Any

Returns:

The loaded JSON contents of the file.

cfgclasses.transforms.picklefile(filepath)

Transform function for loading pickle files.

Parameters:

filepath (Union[str, PurePath]) – Path of the file to be loaded.

Return type:

Any

Returns:

The loaded pickle content of the file.