clack package

(C)ommand (L)ine (A)pplication (C)onfig (K)it

A wrapper around the argparse library that aims to handle _all_ application configuration.

class Config(_case_sensitive=None, _env_prefix=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_parse_none_str=None, _secrets_dir=None, **values)

Bases: BaseSettings

Default CLI arguments / app configuration.

Parameters:

• _case_sensitive (bool | None) –

• _env_prefix (str | None) –

• _env_file (Union[Path, str, List[Union[Path, str]], Tuple[Union[Path, str], ...], None]) –

• _env_file_encoding (str | None) –

• _env_ignore_empty (bool | None) –

• _env_nested_delimiter (str | None) –

• _env_parse_none_str (str | None) –

• _secrets_dir (str | Path | None) –

• values (Any) –

config_file

classmethod from_cli_args(argv)

Dummy function so this class follows ClackConfig protocol.

Parameters:

argv (Sequence[str]) –

Return type:

TypeVar(Config_T, bound= ClackConfig)

logs

model_computed_fields = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'env_file': None, 'env_file_encoding': None, 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_parse_none_str': None, 'env_prefix': '', 'extra': 'ignore', 'frozen': True, 'json_file': None, 'json_file_encoding': None, 'protected_namespaces': ('model_', 'settings_'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_file': None, 'yaml_file_encoding': None}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'config_file': FieldInfo(annotation=Union[ClackConfigFile, NoneType], required=False), 'logs': FieldInfo(annotation=List[Log], required=False, default=[]), 'verbose': FieldInfo(annotation=int, required=False, default=0)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

classmethod settings_customise_sources(settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings)

Customize where we load our application config from.

Parameters:

• settings_cls (Type[BaseSettings]) –

• init_settings (PydanticBaseSettingsSource) –

• env_settings (PydanticBaseSettingsSource) –

• dotenv_settings (PydanticBaseSettingsSource) –

• file_secret_settings (PydanticBaseSettingsSource) –

Return type:

Tuple[PydanticBaseSettingsSource, ...]

verbose

Parser(*args, **kwargs)

Wrapper for argparse.ArgumentParser.

Parameters:

• args (Any) –

• kwargs (Any) –

Return type:

ArgumentParser

class YAMLConfigFile(path)

Bases: object

A clack YAML configuration file.

This class is useful as a way to conveniently get/set configuration values in/to your current application’s config file.

Parameters:

path (Union[str, Path]) –

extensions = ['yml', 'yaml']

get(key)

Getter for values in this config file.

Parameters:

key (str) –

Return type:

Union[Ok[Any, ErisError], Err[Any, ErisError]]

classmethod new(path, **kwargs)

Construct a new YAMLConfigFile object.

Parameters:

• path (Union[str, Path]) –

• kwargs (Any) –

Return type:

YAMLConfigFile

set(key, value, *, allow_new=False)

Setter for values in this config file.

Parameters:

• key (str) –

• value (Any) –

• allow_new (bool) –

Return type:

Union[Ok[Any, ErisError], Err[Any, ErisError]]

to_dict()

Converts this configuration file into a dict.

Return type:

Union[Ok[dict[str, Any], ErisError], Err[dict[str, Any], ErisError]]

clack_envvars_set(app_name, config_types, *, config_file=None, cfg=None)

Context manager that sets temporary envvars.

The following envvars are set on __enter__ and removed on __exit__:

• CLACK_APP_NAME

• CLACK_CONFIG_DEFAULTS

• CLACK_CONFIG_DICT

• CLACK_CONFIG_FILE

Parameters:

• app_name (str) –

• config_types (Iterable[Type[ClackConfig]]) –

• config_file (Path) –

• cfg (ClackConfig) –

Return type:

Iterator[None]

class comma_list_or_file

Bases: object

Namespace class for comma list CLI arguments.

These CLI arguments can either be a comma-separated list or a new-line separated file.

static help(msg)

Updates the help message of an argparse argument which accepts either a comma-separated list or a file containing values separated by newlines.

Parameters:

msg (str) –

Return type:

str

static parse(arg)

Used to interpret a CLI argument that is allowed to be either a comma-separated list or a file containing values separated by newlines.

Parameters:

arg (str) – This argument should be one of the following: [i] A comma-separated list of values. [ii] A filename corresponding to a file containing a list of newline-separated values.

Return type:

List[str]

Returns:

The list of corresponding option values.

filter_cli_args(args)

Filters args produced by ‘parser’ passed into clack.main_factory().

Used to filter out argparse arguments which were NOT specified on the command-line.

Parameters:

args (Union[Namespace, Mapping[str, Any]]) –

Return type:

dict[str, Any]

get_config(cfg_type)

Returns a clack configuration object of type cfg_type.

WARNING: This function should probably only be used when there is no way to pass the config object directly to the calling function.

Raises:

A RuntimeError if the CLACK_CONFIG_DICT envvar is not defined. –

Parameters:

cfg_type (Type[TypeVar(Config_T, bound= ClackConfig)]) –

Return type:

Optional[TypeVar(Config_T, bound= ClackConfig)]

main_factory(app_name, run=None, *, runners=None, parser=None)

Factory used to create a new main() function.

Return type:

ClackMain

Returns:

A generic main() function to be used as a script’s entry point.

Parameters:

• app_name (str) –

• run (ClackRunner) –

• runners (Iterable[ClackRunner]) –

• parser (ClackParser) –

new_command_factory(parser, *, dest='command', required=True, description=None, **kwargs)

Returns a new_command() function that can be used to add subcommands.

Parameters:

• parser (ArgumentParser) – The argparse parser that we want to add subcommands to.

• dest (str) – The attribute name that the subcommand name will be stored under inside the Namespace object.

• required (bool) – Will this subcommand be required or optional?

• description (str) – This argument describes what the subcommand is used for.

• kwargs (Any) – These keyword arguments are relayed to the parser.add_subparsers() function call.

Return type:

ClackNewCommand

register_runner_factory(mut_runner_registry)

Creates a decorator that can be used to register runner functions.

Parameters:

mut_runner_registry (MutableSequence[ClackRunner]) –

Return type:

Callable[[ClackRunner], ClackRunner]

Submodules

• clack.pytest_plugin module
  • MakeConfigFile
  • make_config_file_fixture()
• clack.types module
  • ClackConfig
    • ClackConfig.dict()
    • ClackConfig.from_cli_args()
  • ClackConfigFile
    • ClackConfigFile.extensions
    • ClackConfigFile.get()
    • ClackConfigFile.new()
    • ClackConfigFile.path
    • ClackConfigFile.set()
    • ClackConfigFile.to_dict()
  • ClackMain
  • ClackNewCommand
• clack.xdg module
  • get_base_dir()
  • get_full_dir()
  • init_full_dir()