Fix for Click 8.2 breaking change

CLAUDE.md

@@ -51,6 +51,12 @@ Use filesystem navigation tools to explore the codebase structure as needed.
 - For full coverage, use CI (see CI section below)
 - Some tests use: `bash scripts/test-coverage-xml.sh` (but this won't run all tests)
 
+#### CLI Testing Best Practices
+- When writing new CLI tests, use the `cli_runner()` helper from `tests/integration/functional/cli/utils.py` instead of directly instantiating `CliRunner()`
+- The helper handles Click version compatibility (Click 8.2+ removed the `mix_stderr` parameter)
+- Always check `result.exit_code` after invoking CLI commands to catch failures early
+- Existing tests with `CliRunner()` (no arguments) are fine - only new tests need the helper
+
 ## Development Workflow
 
 ### Prerequisites

src/zenml/cli/cli.py

@@ -137,17 +137,29 @@ def format_commands(
                 help_ = cmd.get_short_help_str(limit=formatter.width)
                 rows.append((tag.value, subcommand, help_))
             if rows:
-                colored_section_title = (
-                    "[dim cyan]Available ZenML Commands (grouped)[/dim cyan]"
-                )
-                with formatter.section(colored_section_title):
-                    formatter.write_dl(rows)  # type: ignore[arg-type]
-
-
-@click.group(cls=ZenMLCLI)
+                if isinstance(formatter, ZenFormatter):
+                    section_title = "[dim cyan]Available ZenML Commands (grouped)[/dim cyan]"
+                    with formatter.section(section_title):
+                        formatter.write_dl(rows)
+                else:
+                    # Fallback: use simple pairs without category and avoid rich markup in header
+                    section_title = "Available ZenML Commands"
+                    with formatter.section(section_title):
+                        pair_rows: List[Tuple[str, str]] = [
+                            (subcmd, help_) for _, subcmd, help_ in rows
+                        ]
+                        formatter.write_dl(pair_rows)
+
+
+@click.group(cls=ZenMLCLI, invoke_without_command=True)
 @click.version_option(__version__, "--version", "-v")
-def cli() -> None:
-    """CLI base command for ZenML."""
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """CLI base command for ZenML.
+
+    Args:
+        ctx: The click context.
+    """
     set_root_verbosity()
     source_context.set(SourceContextTypes.CLI)
     repo_root = Client.find_repository()
@@ -158,6 +170,15 @@ def cli() -> None:
         # packages directory
         source_utils.set_custom_source_root(source_root=os.getcwd())
 
+    # Manually show help and exit with code 0 when invoked without a subcommand.
+    # Click 8.2+ raises NoArgsIsHelpError before the callback runs when
+    # no_args_is_help=True. By relying solely on invoke_without_command=True
+    # and handling help here, we ensure consistent behavior across Click
+    # versions while leveraging our custom help formatter in ZenMLCLI.get_help().
+    if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
+        ctx.command.get_help(ctx)
+        ctx.exit(0)
+
 
 if __name__ == "__main__":
     cli()

src/zenml/cli/formatter.py

@@ -13,10 +13,52 @@
 #  permissions and limitations under the License.
 """Helper functions to format output for CLI."""
 
-from typing import Dict, Iterable, Iterator, Optional, Sequence, Tuple
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+)
 
 from click import formatting
-from click._compat import term_len
+
+if TYPE_CHECKING:
+    term_len: Callable[[str], int]
+else:
+    try:
+        from click.utils import term_len
+    except Exception:
+        from click._compat import term_len
+
+
+def _safe_width(
+    width: Optional[int], max_width: Optional[int], default: int = 80
+) -> int:
+    """Return a non-None width value suitable for wrapping.
+
+    Click sets width to None in some non-interactive contexts. This helper
+    ensures we always get a valid integer width, preferring the explicit width
+    first, then max_width, then a sensible default.
+
+    Args:
+        width: Explicit terminal or content width to use when available.
+        max_width: Upper bound to apply if width is not set or invalid.
+        default: Fallback width used when neither width nor max_width is a
+            positive integer.
+
+    Returns:
+        The effective positive integer width used for wrapping.
+    """
+    if isinstance(width, int) and width > 0:
+        return width
+    if isinstance(max_width, int) and max_width > 0:
+        return max_width
+    return default
 
 
 def measure_table(rows: Iterable[Tuple[str, ...]]) -> Tuple[int, ...]:
@@ -79,105 +121,114 @@ def write_dl(
         col_max: int = 30,
         col_spacing: int = 2,
     ) -> None:
-        """Writes a definition list into the buffer.
+        """Writes a definition list into the formatter buffer.
 
-        This is how options and commands are usually formatted.
+        Click 8.2 tightened validation so that definition list entries must be
+        pairs.  Our CLI groups commands in tagged triples, so we detect that
+        case and render it manually while delegating the standard behavior to
+        Click for the classic two-column output.  This keeps the formatter
+        compatible with both older Click releases (<8.2) and the newer ones
+        without sacrificing the custom grouped layout.
 
-        Arguments:
-            rows: a list of items as tuples for the terms and values.
-            col_max: the maximum width of the first column.
-            col_spacing: the number of spaces between the first and
-                            second column (and third).
-
-        The default behavior is to format the rows in a definition list
-        with rows of 2 columns following the format ``(term, value)``.
-        But for new CLI commands, we want to format the rows in a definition
-        list with rows of 3 columns following the format
-        ``(term, value, description)``.
+        Args:
+            rows: A sequence of tuples that represent the definition list
+                entries.
+            col_max: The maximum width of the first column.
+            col_spacing: The number of spaces between columns.
 
         Raises:
-            TypeError: if the number of columns is not 2 or 3.
+            TypeError: If the provided rows do not represent two or three
+                column entries.
         """
-        rows = list(rows)
+        normalized_rows: List[Tuple[str, ...]] = [tuple(row) for row in rows]
+
+        if not normalized_rows:
+            return
+
+        unique_lengths = {len(row) for row in normalized_rows}
+
+        if unique_lengths == {2}:
+            two_col_rows = [(row[0], row[1]) for row in normalized_rows]
+            super().write_dl(
+                two_col_rows, col_max=col_max, col_spacing=col_spacing
+            )
+            return
+
+        if unique_lengths == {3}:
+            self._write_triple_definition_list(
+                [(row[0], row[1], row[2]) for row in normalized_rows],
+                col_max=col_max,
+                col_spacing=col_spacing,
+            )
+            return
+
+        raise TypeError(
+            "Expected either two- or three-column definition list entries."
+        )
+
+    def _write_triple_definition_list(
+        self,
+        rows: List[Tuple[str, str, str]],
+        col_max: int,
+        col_spacing: int,
+    ) -> None:
         widths = measure_table(rows)
 
-        if len(widths) == 2:
-            first_col = min(widths[0], col_max) + col_spacing
-
-            for first, second in iter_rows(rows, len(widths)):
-                self.write(f"{'':>{self.current_indent}}{first}")
-                if not second:
-                    self.write("\n")
-                    continue
-                if term_len(first) <= first_col - col_spacing:
-                    self.write(" " * (first_col - term_len(first)))
-                else:
-                    self.write("\n")
-                    self.write(" " * (first_col + self.current_indent))
-
-                text_width = max(self.width - first_col - 2, 10)
-                wrapped_text = formatting.wrap_text(
-                    second, text_width, preserve_paragraphs=True
-                )
-                lines = wrapped_text.splitlines()
-
-                if lines:
-                    self.write(f"{lines[0]}\n")
-
-                    for line in lines[1:]:
-                        self.write(
-                            f"{'':>{first_col + self.current_indent}}{line}\n"
-                        )
-                else:
-                    self.write("\n")
-
-        elif len(widths) == 3:
-            first_col = min(widths[0], col_max) + col_spacing
-            second_col = min(widths[1], col_max) + col_spacing * 2
-
-            current_tag = None
-            for first, second, third in iter_rows(rows, len(widths)):
-                if current_tag != first:
-                    current_tag = first
-                    self.write("\n")
-                    # Adding [#431d93] [/#431d93] makes the tag colorful when
-                    # it is printed by rich print
-                    self.write(
-                        f"[#431d93]{'':>{self.current_indent}}{first}:[/#431d93]\n"
-                    )
-
-                if not third:
-                    self.write("\n")
-                    continue
-
-                if term_len(first) <= first_col - col_spacing:
-                    self.write(" " * self.current_indent * 2)
-                else:
-                    self.write("\n")
-                    self.write(" " * (first_col + self.current_indent))
-
-                self.write(f"{'':>{self.current_indent}}{second}")
-
-                text_width = max(self.width - second_col - 4, 10)
-                wrapped_text = formatting.wrap_text(
-                    third, text_width, preserve_paragraphs=True
-                )
-                lines = wrapped_text.splitlines()
-
-                if lines:
-                    self.write(
-                        " "
-                        * (second_col - term_len(second) + self.current_indent)
-                    )
-                    self.write(f"{lines[0]}\n")
-
-                    for line in lines[1:]:
-                        self.write(
-                            f"{'':>{second_col + self.current_indent * 4}}{line}\n"
-                        )
-                else:
-                    self.write("\n")
-        else:
+        if len(widths) < 3:
             raise TypeError(
-                "Expected either three or two columns for definition list"
+                "Expected three columns for tagged definition list entries."
             )
+
+        # Compute target column offsets with spacing applied
+        first_col = min(widths[0], col_max) + col_spacing
+        second_col = min(widths[1], col_max) + col_spacing * 2
+
+        current_tag: Optional[str] = None
+
+        for first, second, third in iter_rows(rows, 3):
+            # Print a category header when the tag changes
+            if current_tag != first:
+                current_tag = first
+                self.write("\n")
+                self.write(
+                    f"[#431d93]{'':>{self.current_indent}}{first}:[/#431d93]\n"
+                )
+
+            # Preserve behavior for empty third-column values
+            if not third:
+                self.write("\n")
+                continue
+
+            # Layout for the command name column
+            if term_len(first) <= first_col - col_spacing:
+                self.write(" " * (self.current_indent * 2))
+            else:
+                self.write("\n")
+                self.write(" " * (first_col + self.current_indent))
+
+            # Command name with current indentation
+            self.write(f"{'':>{self.current_indent}}{second}")
+
+            # Wrap and render the description using a safe width calculation
+            effective_width = _safe_width(
+                self.width, getattr(self, "max_width", None)
+            )
+            text_width = max(effective_width - second_col - 4, 10)
+            wrapped_text = formatting.wrap_text(
+                third, text_width, preserve_paragraphs=True
+            )
+            lines = wrapped_text.splitlines()
+
+            if lines:
+                # First line appears on the same row as the command name
+                self.write(
+                    " " * (second_col - term_len(second) + self.current_indent)
+                )
+                self.write(f"{lines[0]}\n")
+
+                # Continuation lines align with the description column
+                for line in lines[1:]:
+                    self.write(" " * (second_col + self.current_indent))
+                    self.write(f"{line}\n")
+            else:
+                self.write("\n")

tests/integration/functional/cli/test_base.py

@@ -17,8 +17,8 @@
 from pathlib import Path
 
 import pytest
-from click.testing import CliRunner
 
+from tests.integration.functional.cli.utils import cli_runner
 from zenml.cli.base import ZENML_PROJECT_TEMPLATES, clean, init
 from zenml.constants import CONFIG_FILE_NAME, REPOSITORY_DIRECTORY_NAME
 from zenml.utils import yaml_utils
@@ -27,8 +27,9 @@
 
 def test_init_creates_zen_folder(tmp_path: Path) -> None:
     """Check that init command creates a .zen folder."""
-    runner = CliRunner()
-    runner.invoke(init, ["--path", str(tmp_path)])
+    runner = cli_runner()
+    result = runner.invoke(init, ["--path", str(tmp_path), "--test"])
+    assert result.exit_code == 0, f"Command failed: {result.output}"
     assert (tmp_path / REPOSITORY_DIRECTORY_NAME).exists()
 
 
@@ -44,17 +45,19 @@ def test_init_creates_from_templates(
     tmp_path: Path, template_name: str
 ) -> None:
     """Check that init command checks-out template."""
-    runner = CliRunner()
-    runner.invoke(
+    runner = cli_runner()
+    result = runner.invoke(
         init,
         [
             "--path",
             str(tmp_path),
             "--template",
             template_name,
             "--template-with-defaults",
+            "--test",
         ],
     )
+    assert result.exit_code == 0, f"Command failed: {result.output}"
     assert (tmp_path / REPOSITORY_DIRECTORY_NAME).exists()
     files_in_top_level = set([f.lower() for f in os.listdir(str(tmp_path))])
     must_have_files = {
@@ -75,8 +78,9 @@ def test_clean_user_config(clean_client) -> None:
     user_id = yaml_contents["user_id"]
     analytics_opt_in = yaml_contents["analytics_opt_in"]
     version = yaml_contents["version"]
-    runner = CliRunner()
-    runner.invoke(clean, ["--yes", True])
+    runner = cli_runner()
+    result = runner.invoke(clean, ["--yes", True])
+    assert result.exit_code == 0, f"Command failed: {result.output}"
     new_yaml_contents = yaml_utils.read_yaml(str(global_zen_config_yaml))
     assert user_id == new_yaml_contents["user_id"]
     assert analytics_opt_in == new_yaml_contents["analytics_opt_in"]