10. TOMLParams class

class tomlparams.TOMLParams(defaults: dict | str, name: str = None, params_name: str = 'tomlparams', env_var: str = None, base_params_stem: str = 'base', standard_params_dir: str = None, user_params_dir: str = None, verbose: bool | None = True, check_types: TypeChecking = TypeChecking.WARN, type_check_env_var: str = None)

TOML-based parameter files made better

Args:

defaults: Specifies the default values, and types of all parameters

to be allowed when reading TOML files. Can be a string-keyed Python dictionary (potentially nested) or a string, specifying the name of the TOML file containing the default values. Such a default TOML file may not include inclusions. If using a TOML file, absolute paths can be anywhere; relative paths will be taken to refer to the standard parameters directory.

name: The (stem) name of the TOML file to use.

If None (the default), ‘base’ (or any other base name provided as base_params_stem, see below) will be used.

If ‘default’ or ‘defaults’, the default values will be used, i.e. no TOML files will be read other than (if using a file) the defaults file.

If anything else, the name will be searched for in the standard_params_dir and the user_params_dir; it should only exist in one of those places.

params_name: If standard params or user params directories are

not provided, explicitly, they are based on this value, which defaults to ‘tomlparams’, meaning that if not specified the standard parameters directory will be ~/tomlparams, and the user parameters directory will be ~/usertomlparams.

env_var: The name of an environment variable to look up if

name is not set (i.e. is passed in as None). This defaults to TOMLPARAMS. If TOMLPARAMS is set, for example, ‘foo’, that will be used as the TOML file stem name for parameter loading.

base_params_stem: value to use for name (the TOML file stem)

if name is passed as None. Defaults to ‘base’.

standard_params_dir: Absolute or relative path for the standard

parameters directory. If not set, ~/tomlparams will be used, or ‘~/{params_name}’ if params_name has been set. This path will often be under source control as part of the project using TOMLParams.

user_params_dir: Absolute or relative path for the user

parameters directory. If not set, ~/usertomlparams will be used, or ‘~/user{params_name}’ if params_name has been set. This path will usually not be under source control.

verbose: Set to False to disable output to standard out

check_types: Controls whether to do type checking of values from

TOML files. When type checking is used, the expected type is determined by defaults (the default Python dictionary or TOML file), not by type hinting. By default (WARN = tomlparams.WARN), types not consistent those in defaults generate a warning. Set to ERROR (tomlparams.ERROR) to cause an exception to be raised. Set to OFF (tomlparams.OFF) to disable type checking.

type_check_env_var: The name of an environment variable to

use to override check_types. Defaults to ‘TOMLPARAMSCHECKING’. If this environment variable exists, it should be set to one of ‘warn’, ‘error’, or ‘off’, and that value will override the value of check_types passed in.