Merge pull request #8 from explosion/error-maps

Author: ines

README.md

@@ -2,7 +2,7 @@
 
 # radicli: Radically lightweight command-line interfaces
 
-`radicli` is a small, zero-dependency Python package for creating command line interfaces, built on top of Python's [`argparse`](https://docs.python.org/3/library/argparse.html) module. It introduces minimal overhead, preserves your original Python functions and uses type hints to parse values provided on the CLI. It supports all common types out-of-the-box, including complex ones like `List[str]`, `Literal` and `Enum`, and allows registering custom types with custom converters.
+`radicli` is a small, zero-dependency Python package for creating command line interfaces, built on top of Python's [`argparse`](https://docs.python.org/3/library/argparse.html) module. It introduces minimal overhead, preserves your original Python functions and uses type hints to parse values provided on the CLI. It supports all common types out-of-the-box, including complex ones like `List[str]`, `Literal` and `Enum`, and allows registering custom types with custom converters, as well as custom CLI-only error handling.
 
 > **Important note:** This package aims to be a simple option based on the requirements of our libraries. If you're looking for a more full-featured CLI toolkit, check out [`typer`](https://typer.tiangolo.com), [`click`](https://click.palletsprojects.com) or [`plac`](https://plac.readthedocs.io/en/latest/).
 
@@ -234,6 +234,56 @@ $ python cli.py hey --name Alex --age 35
 $ python cli.py greet person --name Alex --age 35
 ```
 
+### Error handling
+
+One common problem when adding CLIs to a code base is error handling. When called in a CLI context, you typically want to pretty-print any errors and avoid long tracebacks. However, you don't want to use those errors and plain `SystemExit`s with no traceback in helper functions that are used in other places, or when the CLI functions are called directly from Python or during testing.
+
+To solve this, `radicli` lets you provide an error map via the `errors` argument on initialization. It maps `Exception` types like `ValueError` or fully custom error subclasses to handler functions. If an error of that type is raised, the handler is called and will receive the error. The handler can optionally return an exit code – in this case, `radicli` will perform a `sys.exit` using that code. If no error code is returned, no exit is performed and the handler can either take care of the exiting itself or choose to not exit.
+
+```python
+from radicli import Radicli
+from termcolor import colored
+
+def pretty_print_error(error: Exception) -> int:
+    print(colored(f"🚨 {error}", "red"))
+    return 1
+
+cli = Radicli(errors={ValueError: handle_error})
+
+@cli.command("hello", name=Arg("--name"))
+def hello(name: str):
+    if name == "Alex":
+        raise ValueError("Invalid name")
+```
+
+```
+$ python cli.py hello --name Alex
+🚨 Invalid name
+```
+
+```bash
+>>> hello("Alex")
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+ValueError: Invalid name
+```
+
+This approach is especially powerful with custom error subclasses. Here you can decide which arguments the error should take and how this information should be displayed on the CLI vs. in a regular non-CLI context.
+
+```python
+class CustomError(Exception):
+    def __init__(self, text: str, additional_info: Any = "") -> None:
+        self.text = text
+        self.additional_info
+        self.message = f"{self.text} {self.additional_info}"
+        super().__init__(self.message)
+
+def handle_custom_error(error: CustomError) -> int:
+    print(colored(error.text, "red"))
+    print(error.additiona_info)
+    return 1
+```
+
 ## 🎛 API
 
 ### <kbd>dataclass</kbd> `Arg`
@@ -266,14 +316,15 @@ Internal representation of a CLI command. Can be accessed via `Radicli.commands`
 
 #### Attributes
 
-| Name          | Type                               | Description                                                                            |
-| ------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
-| `prog`        | `Optional[str]`                    | Program name displayed in `--help` prompt usage examples, e.g. `"python -m spacy"`.    |
-| `help`        | `str`                              | Help text for the CLI, displayed in top-level `--help`. Defaults to `""`.              |
-| `version`     | `Optional[str]`                    | Version available via `--version`, if set.                                             |
-| `converters`  | `Dict[Type, Callable[[str], Any]]` | Dict mapping types to global converter functions.                                      |
-| `commands`    | `Dict[str, Command]`               | The commands added to the CLI, keyed by name.                                          |
-| `subcommands` | `Dict[str, Dict[str, Command]]`    | The subcommands added to the CLI, keyed by parent name, then keyed by subcommand name. |
+| Name          | Type                                                          | Description                                                                                                                                                                              |
+| ------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prog`        | `Optional[str]`                                               | Program name displayed in `--help` prompt usage examples, e.g. `"python -m spacy"`.                                                                                                      |
+| `help`        | `str`                                                         | Help text for the CLI, displayed in top-level `--help`. Defaults to `""`.                                                                                                                |
+| `version`     | `Optional[str]`                                               | Version available via `--version`, if set.                                                                                                                                               |
+| `converters`  | `Dict[Type, Callable[[str], Any]]`                            | Dict mapping types to global converter functions.                                                                                                                                        |
+| `errors`      | `Dict[Type[Exception], Callable[[Exception], Optional[int]]]` | Dict mapping errors types to global error handlers. If the handler returns an exit code, a `sys.exit` will be raised using that code. See [error handling](#error-handling) for details. |
+| `commands`    | `Dict[str, Command]`                                          | The commands added to the CLI, keyed by name.                                                                                                                                            |
+| `subcommands` | `Dict[str, Dict[str, Command]]`                               | The subcommands added to the CLI, keyed by parent name, then keyed by subcommand name.                                                                                                   |
 
 #### <kbd>method</kbd> `Radicli.__init__`
 
@@ -285,13 +336,14 @@ from radicli import Radicli
 cli = Radicli(prog="python -m spacy")
 ```
 
-| Argument     | Type                               | Description                                                                                                                                               |
-| ------------ | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `prog`       | `Optional[str]`                    | Program name displayed in `--help` prompt usage examples, e.g. `"python -m spacy"`.                                                                       |
-| `help`       | `str`                              | Help text for the CLI, displayed in top-level `--help`. Defaults to `""`.                                                                                 |
-| `version`    | `Optional[str]`                    | Version available via `--version`, if set.                                                                                                                |
-| `converters` | `Dict[Type, Callable[[str], Any]]` | Dict mapping types to converter functions. All arguments with these types will then be passed to the respective converter.                                |
-| `extra_key`  | `str`                              | Name of function argument that receives extra arguments if the `command_with_extra` or `subcommand_with_extra` decorator is used. Defaults to `"_extra"`. |
+| Argument     | Type                                                          | Description                                                                                                                                                                              |
+| ------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prog`       | `Optional[str]`                                               | Program name displayed in `--help` prompt usage examples, e.g. `"python -m spacy"`.                                                                                                      |
+| `help`       | `str`                                                         | Help text for the CLI, displayed in top-level `--help`. Defaults to `""`.                                                                                                                |
+| `version`    | `Optional[str]`                                               | Version available via `--version`, if set.                                                                                                                                               |
+| `converters` | `Dict[Type, Callable[[str], Any]]`                            | Dict mapping types to converter functions. All arguments with these types will then be passed to the respective converter.                                                               |
+| `errors`     | `Dict[Type[Exception], Callable[[Exception], Optional[int]]]` | Dict mapping errors types to global error handlers. If the handler returns an exit code, a `sys.exit` will be raised using that code. See [error handling](#error-handling) for details. |
+| `extra_key`  | `str`                                                         | Name of function argument that receives extra arguments if the `command_with_extra` or `subcommand_with_extra` decorator is used. Defaults to `"_extra"`.                                |
 
 #### <kbd>decorator</kbd> `Radicli.command`, `Radicli.command_with_extra`
 

radicli/__init__.py

@@ -5,8 +5,9 @@
 
 from .parser import ArgumentParser, HelpFormatter
 from .util import Arg, ArgparseArg, get_arg, join_strings, format_type, format_table
-from .util import format_arg_help, SimpleFrozenDict, CommandNotFoundError
-from .util import CliParserError, CommandExistsError, ConvertersType
+from .util import format_arg_help, expand_error_subclasses, SimpleFrozenDict
+from .util import CommandNotFoundError, CliParserError, CommandExistsError
+from .util import ConvertersType, ErrorHandlersType
 from .util import DEFAULT_CONVERTERS, DEFAULT_PLACEHOLDER
 
 # Make available for import
@@ -40,6 +41,7 @@ class Radicli:
     extra_key: str
     commands: Dict[str, Command]
     subcommands: Dict[str, Dict[str, Command]]
+    errors: ErrorHandlersType
     _subcommand_key: str
     _help_arg: str
 
@@ -50,6 +52,7 @@ def __init__(
         help: str = "",
         version: Optional[str] = None,
         converters: ConvertersType = SimpleFrozenDict(),
+        errors: Optional[ErrorHandlersType] = None,
         extra_key: str = "_extra",
     ) -> None:
         """Initialize the CLI and create the registry."""
@@ -61,6 +64,7 @@ def __init__(
         self.extra_key = extra_key
         self.commands = {}
         self.subcommands = {}
+        self.errors = dict(errors) if errors is not None else {}
         self._subcommand_key = "__subcommand__"  # should not conflict with arg name!
         self._help_arg = "--help"
 
@@ -231,7 +235,17 @@ def run(self, args: Optional[List[str]] = None) -> None:
             )
             sub = values.pop(self._subcommand_key, None)
             func = subcommands[sub].func if sub else cmd.func
-            func(**values)
+            # Catch specific error types (and their subclasses), and invoke
+            # their handler callback. Handlers can return an integer exit code,
+            # which will be passed to sys.exit.
+            errors_map = expand_error_subclasses(self.errors)
+            try:
+                func(**values)
+            except tuple(errors_map.keys()) as e:
+                handler = errors_map[e.__class__]
+                err_code = handler(e)
+                if err_code is not None:
+                    sys.exit(err_code)
 
     def parse(
         self,

radicli/tests/test_cli.py

@@ -1,4 +1,4 @@
-from typing import List, Iterator, Optional, Literal, TypeVar, Generic
+from typing import List, Iterator, Optional, Literal, TypeVar, Generic, Type
 from enum import Enum
 from dataclasses import dataclass
 import pytest
@@ -679,3 +679,50 @@ def child(a: str):
     assert ran_parent
     cli.run(["", "child", "--a", "hello"])
     assert ran_child
+
+
+@pytest.mark.parametrize(
+    "raise_error, handle_errors, handler_return, expect_handled, expect_exit",
+    [
+        (None, [KeyError], None, False, False),
+        (KeyError, [KeyError], None, True, False),
+        (KeyError, [KeyError], 1, True, True),
+        (KeyError, [], 1, True, True),
+        (KeyError, [ValueError], 1, True, True),
+    ],
+)
+def test_cli_errors(
+    raise_error: Optional[Type[Exception]],
+    handle_errors: List[Type[Exception]],
+    handler_return: Optional[int],
+    expect_handled: bool,
+    expect_exit: bool,
+):
+    handler_ran = False
+
+    def error_handler(e: Exception) -> Optional[int]:
+        nonlocal handler_ran
+        handler_ran = True
+        return handler_return
+
+    cli = Radicli(errors={e: error_handler for e in handle_errors})
+
+    @cli.command("test")
+    def test():
+        nonlocal ran
+        ran = True
+        if raise_error is not None:
+            raise raise_error
+
+    ran = False
+
+    if raise_error is not None and raise_error not in handle_errors:
+        with pytest.raises(raise_error):
+            cli.run(["", "test"])
+    elif expect_exit:
+        with pytest.raises(SystemExit):
+            cli.run(["", "test"])
+    else:
+        cli.run(["", "test"])
+        assert ran
+        assert handler_ran is expect_handled

radicli/util.py

@@ -17,6 +17,8 @@
 BASE_TYPES = [str, int, float, Path]
 ConverterType = Callable[[str], Any]
 ConvertersType = Dict[Union[Type, object], ConverterType]
+ErrorHandlerType = Callable[[Exception], Optional[int]]
+ErrorHandlersType = Dict[Type[Exception], ErrorHandlerType]
 
 
 class CliParserError(SystemExit):
@@ -246,6 +248,19 @@ def format_arg_help(text: Optional[str], max_width: int = 70) -> str:
     return (d.rsplit(".", 1)[0] if "." in d else d) + end
 
 
+def expand_error_subclasses(
+    errors: Dict[Type[Exception], ErrorHandlerType]
+) -> Dict[Type[Exception], ErrorHandlerType]:
+    """Map subclasses of errors to their parent's handler."""
+    output = {}
+    for err, callback in errors.items():
+        if hasattr(err, "__subclasses__"):
+            for subclass in err.__subclasses__():
+                output[subclass] = callback
+        output[err] = callback
+    return output
+
+
 def convert_existing_path(path_str: str) -> Path:
     path = Path(path_str)
     if not path.exists():