frontends.cli.utils

abort_click_on

abort_click_on(
    *kinds: type[Exception],
) -> Callable[[Callable[..., Any]], Callable[..., Any]]

Returns a decorator that catches all exceptions of type kinds, logs them, then raises a click.Exception.

Decorator factory function that returns an exception handling decorator for use with click CLI programs. When an error of type kinds is encountered it is logged at CRITICAL level. The error is also logged with a full stack trace at DEBUG level for later inspection. After logging, a click.Exception exception is raised, which click will handle to gracefully exit the program.

Example

Consider the simple function square_root.

def square_root(arg: float):
    if arg < 0.0
        raise ValueError("Cannot compute square root of negative value.")
    return arg**0.5

If this is called with a negative value by a click program, we'll get a crash with a stack trace.

Using the abort_click_on decorator

@abort_click_on(ValueError)
def square_root(arg: float):
    if arg < 0.0
        raise ValueError("Cannot compute square root of negative value.")
    return arg**0.5

We instead get a clean exit:

CRITICAL: Cannot compute square root of negative value.
Aborted!

describe_item

describe_item(
    graph: TrustableGraph, item_name: str, statement: bool
) -> str

Describes item and formats item details as a human-readable output.

Parameters:

Name	Type	Description	Default
graph	TrustableGraph	Graph to use for describing the item	required
item_name	str	Item name to be described	required
statement	bool	If statement of the item should be included in the output	required

filter_unreviewed_items

filter_unreviewed_items(
    graph: TrustableGraph, items: list[str]
) -> list

Returns a list of unreviewed items from the supplied list of items. Error for any items that are not in the graph.

Parameters:

Name	Type	Description	Default
graph	TrustableGraph	Graph used to check review status.	required
items	list[str]	a list of strings to check	required

Return: list of strings, from the items argument, that are in the graph and unreviewed.

parse_ranks

parse_ranks(rank_list_str: str) -> list[list[str]]

Parse the 'list as string' of a rank tuple into a Python list.

validate_trudag_version

validate_trudag_version(graph_source: Path) -> None

Compare the trudag version with the version used to generate the dotfile.

Raises:

Type	Description
VersionError	If the trudag version and the version used to generate the dotfile have different dotfile formatting.