Add colored CLI help formatting and respect NO_COLOR (#109)

* Add a colored help formatter

Compared to click's default formatter, this highlights options, usuage,
headings and formats option lists in a linear style (descriptions of
options are on a new line). Options are also aligned so that single-dash
options like "-v" stand-out more.

This will also respect the NO_COLOR envirornment variable now.

Also adds a short "-g" option for "--group-errors".

This is loosely inspired by spin [1].

[1] https://github.com/scientific-python/spin/blob/edbd6572f7fc53fa0914fe6337b1bb2599e457fa/spin/color_format.py

* Respect NO_COLOR environment variable for logged output too

* Fix stubtest & typing errors

* Remove unused noqa comment

Author: lagru

docs/command_line.md

@@ -3,6 +3,9 @@
 The reference for docstub's command line interface.
 It uses [Click](https://click.palletsprojects.com/en/stable/), so [shell completion](https://click.palletsprojects.com/en/stable/shell-completion/) can be enabled.
 
+Colored command line output can be disabled by [setting the environment variable `NO_COLOR=1`](https://no-color.org).
+
+
 ## `docstub`
 
 <!--- The following block is checked by the test suite --->
@@ -14,8 +17,10 @@ Usage: docstub [OPTIONS] COMMAND [ARGS]...
   Generate Python stub files from docstrings.
 
 Options:
-  --version   Show the version and exit.
-  -h, --help  Show this message and exit.
+      --version
+          Show the version and exit.
+  -h, --help
+          Show this message and exit.
 
 Commands:
   clean  Clean the cache.
@@ -35,35 +40,43 @@ Usage: docstub run [OPTIONS] PACKAGE_PATH
 
   Generate Python stub files.
 
-  Given a `PACKAGE_PATH` to a Python package, generate stub files for it. Type
+  Given a PACKAGE_PATH to a Python package, generate stub files for it. Type
   descriptions in docstrings will be used to fill in missing inline type
   annotations or to override them.
 
 Options:
-  -o, --out-dir PATH     Set output directory explicitly. Stubs will be
-                         directly written into that directory while preserving
-                         the directory structure under `PACKAGE_PATH`.
-                         Otherwise, stubs are generated inplace.
-  --config PATH          Set one or more configuration file(s) explicitly.
-                         Otherwise, it will look for a `pyproject.toml` or
-                         `docstub.toml` in the current directory.
-  --ignore GLOB          Ignore files matching this glob-style pattern. Can be
-                         used multiple times.
-  --group-errors         Group identical errors together and list where they
-                         occurred. Will delay showing errors until all files
-                         have been processed. Otherwise, simply report errors
-                         as the occur.
-  --allow-errors INT     Allow this many or fewer errors. If docstub reports
-                         more, exit with error code '1'. This is useful to
-                         adopt docstub gradually.   [default: 0; x>=0]
-  -W, --fail-on-warning  Return non-zero exit code when a warning is raised.
-                         Will add to '--allow-errors'.
-  --no-cache             Ignore pre-existing cache and don't create a new one.
-  -v, --verbose          Print more details. Use once to show information
-                         messages. Use -vv to print debug messages.
-  -q, --quiet            Print less details. Use once to hide warnings. Use
-                         -qq to completely silence output.
-  -h, --help             Show this message and exit.
+  -o, --out-dir PATH
+          Set output directory explicitly. Stubs will be directly written into
+          that directory while preserving the directory structure under
+          PACKAGE_PATH. Otherwise, stubs are generated inplace.
+      --config PATH
+          Set one or more configuration file(s) explicitly. Otherwise, it will
+          look for a `pyproject.toml` or `docstub.toml` in the current
+          directory.
+      --ignore GLOB
+          Ignore files matching this glob-style pattern. Can be used multiple
+          times.
+  -g, --group-errors
+          Group identical errors together and list where they occurred. Will
+          delay showing errors until all files have been processed. Otherwise,
+          simply report errors as the occur.
+      --allow-errors INT
+          Allow this many or fewer errors. If docstub reports more, exit with
+          error code 1. This is useful to adopt docstub gradually.   [default:
+          0; x>=0]
+  -W, --fail-on-warning
+          Return non-zero exit code when a warning is raised. Will add to
+          --allow-errors.
+      --no-cache
+          Ignore pre-existing cache and don't create a new one.
+  -v, --verbose
+          Print more details. Use once to show information messages. Use -vv to
+          print debug messages.
+  -q, --quiet
+          Print less details. Use once to hide warnings. Use -qq to completely
+          silence output.
+  -h, --help
+          Show this message and exit.
 ```
 
 <!--- end cli-docstub-run --->
@@ -83,11 +96,14 @@ Usage: docstub clean [OPTIONS]
   one exists, remove it.
 
 Options:
-  -v, --verbose  Print more details. Use once to show information messages.
-                 Use -vv to print debug messages.
-  -q, --quiet    Print less details. Use once to hide warnings. Use -qq to
-                 completely silence output.
-  -h, --help     Show this message and exit.
+  -v, --verbose
+          Print more details. Use once to show information messages. Use -vv to
+          print debug messages.
+  -q, --quiet
+          Print less details. Use once to hide warnings. Use -qq to completely
+          silence output.
+  -h, --help
+          Show this message and exit.
 ```
 
 <!--- end cli-docstub-clean --->

pyproject.toml

@@ -104,6 +104,7 @@ ignore = [
     "PLR2004",  # Magic value used in comparison
     "ISC001",   # Conflicts with formatter
     "RET504",   # Assignment before `return` statement facilitates debugging
+    "RUF012",   # Mutable class attributes should be annotated with `typing.ClassVar`
     "PTH123",   # Using builtin open() instead of Path.open() is fine
     "SIM108",   # Terniary operator is always more readable
     "SIM103",   # Don't recommend returning the condition directly

src/docstub-stubs/_cli.pyi

@@ -11,9 +11,11 @@ from pathlib import Path
 from typing import Literal
 
 import click
+from _typeshed import Incomplete
 
 from ._analysis import PyImport, TypeCollector, TypeMatcher, common_known_types
 from ._cache import CACHE_DIR_NAME, FileCache, validate_cache
+from ._cli_help import HelpFormatter
 from ._config import Config
 from ._path_utils import (
     STUB_HEADER_COMMENT,
@@ -37,6 +39,9 @@ def _collect_type_info(
 ) -> tuple[dict[str, PyImport], dict[str, PyImport]]: ...
 def _format_unknown_names(names: Iterable[str]) -> str: ...
 def log_execution_time() -> None: ...
+
+click.Context.formatter_class = HelpFormatter
+
 @click.group()
 def cli() -> None: ...
 def _add_verbosity_options(func: Callable) -> Callable: ...

src/docstub-stubs/_cli_help.pyi

@@ -0,0 +1,44 @@
+# File generated with docstub
+
+import logging
+import os
+import re
+from collections.abc import Sequence
+from typing import IO, Any, ClassVar
+
+import click
+from click.formatting import iter_rows, measure_table, wrap_text
+
+logger: logging.Logger
+
+try:
+    from click._compat import should_strip_ansi as _click_should_strip_ansi
+
+except Exception:
+
+    def _click_should_strip_ansi(
+        stream: IO[Any] | None = ..., color: bool | None = ...
+    ) -> bool: ...
+
+def should_strip_ansi(
+    stream: IO[Any] | None = ..., color: bool | None = ...
+) -> bool: ...
+
+class HelpFormatter(click.formatting.HelpFormatter):
+    strip_ansi: bool
+
+    rule_defs: ClassVar[dict[str, tuple[str, str]]]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+    def write_dl(
+        self,
+        rows: Sequence[tuple[str, str]],
+        *args: Any,
+        **kwargs: Any,
+    ) -> None: ...
+    def write_heading(self, heading: str) -> None: ...
+    def write_usage(
+        self, prog: str, args: str = ..., prefix: str | None = ...
+    ) -> None: ...
+    def _highlight_last(self, *, n: int, rules: list[str]) -> None: ...
+    def _highlight(self, string: str, *, rules: list[str]) -> str: ...

src/docstub-stubs/_report.pyi

@@ -8,6 +8,8 @@ from typing import Any, ClassVar, Literal, Self, TextIO
 
 import click
 
+from ._cli_help import should_strip_ansi
+
 logger: logging.Logger
 
 @dataclasses.dataclass(kw_only=True, slots=True, frozen=True)

src/docstub/_cli.py

@@ -15,6 +15,7 @@
     common_known_types,
 )
 from ._cache import CACHE_DIR_NAME, FileCache, validate_cache
+from ._cli_help import HelpFormatter
 from ._config import Config
 from ._path_utils import (
     STUB_HEADER_COMMENT,
@@ -213,7 +214,11 @@ def log_execution_time():
         logger.info("Finished in %s", formated_duration)
 
 
+# Overwrite click's default formatter class (stubtest balks at this)
 # docstub: off
+click.Context.formatter_class = HelpFormatter
+
+
 @click.group()
 # docstub: on
 @click.version_option(__version__)
@@ -262,7 +267,7 @@ def _add_verbosity_options(func):
     metavar="PATH",
     help="Set output directory explicitly. "
     "Stubs will be directly written into that directory while preserving the directory "
-    "structure under `PACKAGE_PATH`. "
+    "structure under PACKAGE_PATH. "
     "Otherwise, stubs are generated inplace.",
 )
 @click.option(
@@ -283,6 +288,7 @@ def _add_verbosity_options(func):
     help="Ignore files matching this glob-style pattern. Can be used multiple times.",
 )
 @click.option(
+    "-g",
     "--group-errors",
     is_flag=True,
     help="Group identical errors together and list where they occurred. "
@@ -296,15 +302,15 @@ def _add_verbosity_options(func):
     show_default=True,
     metavar="INT",
     help="Allow this many or fewer errors. "
-    "If docstub reports more, exit with error code '1'. "
+    "If docstub reports more, exit with error code 1. "
     "This is useful to adopt docstub gradually. ",
 )
 @click.option(
     "-W",
     "--fail-on-warning",
     is_flag=True,
     help="Return non-zero exit code when a warning is raised. "
-    "Will add to '--allow-errors'.",
+    "Will add to --allow-errors.",
 )
 @click.option(
     "--no-cache",
@@ -329,7 +335,7 @@ def run(
 ):
     """Generate Python stub files.
 
-    Given a `PACKAGE_PATH` to a Python package, generate stub files for it.
+    Given a PACKAGE_PATH to a Python package, generate stub files for it.
     Type descriptions in docstrings will be used to fill in missing inline type
     annotations or to override them.
     \f
@@ -456,7 +462,8 @@ def run(
         logger.warning("Syntax errors: %i", syntax_error_count)
     if unknown_type_names:
         logger.warning(
-            "Unknown type names: %i",
+            "Unknown type names: %i (locations: %i)",
+            len(set(unknown_type_names)),
             len(unknown_type_names),
             extra={"details": _format_unknown_names(unknown_type_names)},
         )