fairical.scripts.utils

Tools for command-line applications.

Functions

prepare_and_backup(path)

Ensure parent directory exists and back-up copies.

save_csv_with_backups(path, data)

Save a dictionary into a CSV file with path checking and backup.

save_json_with_backup(path, data)

Save a dictionary into a JSON file with path checking and backup.

validate_metrics(ctx, param, value)

Validate a user defined metric for support.

validate_scores_json(ctx, param, value)

Validate one or more JSON files against a predefined data model.

validate_solutions_json(ctx, param, value)

Validate one or more JSON files against a predefined data model.

validate_thresholds(ctx, param, value)

Validate a threshold setup.

verbosity_option(logger[, short_name, name, ...])

Click-option decorator that adds a -v/--verbose option to a cli.
fairical.scripts.utils.prepare_and_backup(path)[source]

Ensure parent directory exists and back-up copies.

This function will check that the directory leading to a file path exists and will created it otherwise. It will also check if the file does not already exists, and back it up otherwise.

Parameters:

path (Path) – The full path of the file to ensure the parent directory exists and that it is properly backed-up if necessary.

Return type:

None

fairical.scripts.utils.save_json_with_backup(path, data)[source]

Save a dictionary into a JSON file with path checking and backup.

This function will save a dictionary into a JSON file. It will check the existence of the directory leading to the file and create it if necessary. If the file already exists on the destination folder, it is backed-up before a new file is created with the new contents.

Parameters:

  • path (Path) – The full path where to save the JSON data.

  • data (dict) – The data to save on the JSON file.

Return type:

None

fairical.scripts.utils.save_csv_with_backups(path, data)[source]

Save a dictionary into a CSV file with path checking and backup.

This function will save a dictionary into a CSV file. It will check the existence of the directory leading to the file and create it if necessary. If the file already exists on the destination folder, it is backed-up before a new file is created with the new contents.

Parameters:

  • path (Path) – The full path where to save the CSV data.

  • data (dict[str, Any]) – The data to save on the CSV file.

fairical.scripts.utils.validate_scores_json(ctx, param, value)[source]

Validate one or more JSON files against a predefined data model.

This function is intended to be used as a Click argument callback. It opens the given file path, parses its JSON content, and validates it against the library data model. If any validation error occurs, a click.BadParameter is raised to inform the user.

Parameters:

  • ctx (Context) – The Click execution context.

  • param (Parameter) – The parameter that triggered the callback.

  • value (Sequence[Path]) – Path to the JSON files to load and validate.

Return type:

list[tuple[Path, Scores] | tuple[tuple[Path, Scores], tuple[Path, Solutions]]]

Returns:

The parsed and validated JSON content as a list, where each element is either a a tuple mapping filename to scores, or a tuple containing two entries, the first mapping a filename to scores and a second (to be used for selecting a priori thresholds and systems) mapping a filename to pre-calculated solutions.

Raises:

click.BadParameter – If the file cannot be read, contains invalid JSON, or fails data model validation.

fairical.scripts.utils.validate_solutions_json(ctx, param, value)[source]

Validate one or more JSON files against a predefined data model.

This function is intended to be used as a Click argument callback. It opens the given file path, parses its JSON content, and validates it against the library data model. If any validation error occurs, a click.BadParameter is raised to inform the user.

Parameters:

  • ctx (Context) – The Click execution context.

  • param (Parameter) – The parameter that triggered the callback.

  • value (Sequence[Path]) – Path to the JSON files to load and validate.

Return type:

dict[str, Solutions]

Returns:

The parsed and validated JSON content as a dictionary, where keys represent the basename of files without extension.

Raises:

click.BadParameter – If the file cannot be read, contains invalid JSON, or fails data model validation.

fairical.scripts.utils.validate_metrics(ctx, param, value)[source]

Validate a user defined metric for support.

Parameters:

  • ctx (Context) – The Click execution context.

  • param (Parameter) – The parameter that triggered the callback.

  • value (Sequence[str]) – The value to validate.

Return type:

tuple[str, ...]

Returns:

The validated metrics.

Raises:

click.BadParameter – If one or more of the provided metrics do not validate correctly.

fairical.scripts.utils.validate_thresholds(ctx, param, value)[source]

Validate a threshold setup.

Parameters:

  • ctx (Context) – The Click execution context.

  • param (Parameter) – The parameter that triggered the callback.

  • value (int | None) – The value to validate.

Return type:

None | list[float]

Returns:

The validated threshold, as our API likes it.

Raises:

click.BadParameter – If the threshold cannot be validated.

fairical.scripts.utils.verbosity_option(logger, short_name='v', name='verbose', dflt=0, **kwargs)[source]

Click-option decorator that adds a -v/--verbose option to a cli.

This decorator adds a click option to your CLI to set the log-level on a provided logging.Logger. You must specifically determine the logger that will be affected by this CLI option, via the logger option.

@verbosity_option(logger=logger)

The verbosity option has the “count” type, and has a default value of 0. At each time you provide -v options on the command-line, this value is increased by one. For example, a CLI setting of -vvv will set the value of this option to 3. This is the mapping between the value of this option (count of -v CLI options passed) and the log-level set at the provided logger:

  • 0 (no -v option provided): logger.setLevel(logging.ERROR)

  • 1 (-v): logger.setLevel(logging.WARNING)

  • 2 (-vv): logger.setLevel(logging.INFO)

  • 3 (-vvv or more): logger.setLevel(logging.DEBUG)

Parameters:

  • logger (Logger) – The logging.Logger to be set.

  • short_name (str) – Short name of the option. If not set, then use v

  • name (str) – Long name of the option. If not set, then use verbose – this will also become the name of the contextual parameter for click.

  • dlft – The default verbosity level to use (defaults to 0).

  • **kwargs (Any) – Further keyword-arguments to be forwarded to the underlying click.option()

Return type:

Callable[..., Any]

Returns:

A callable, that follows the click-framework policy for option decorators. Use it accordingly.