Add test for --shell-completion --help, and document workaround

Author: rsokl

hydra/_internal/utils.py

@@ -545,6 +545,13 @@ def __repr__(self) -> str:
             return f"Install or Uninstall shell completion:\n{_get_completion_help()}"
 
     if sys.version_info >= (3, 14):
+        # Python 3.14+ adds help message validation via ArgumentParser._check_help,
+        # which calls formatter._expand_help(action) to validate that action.help
+        # is a string that can be used in string formatting (e.g., "text %(prog)s").
+        # This breaks our LazyCompletionHelp because `_expand_help` expects an actual
+        # string.
+        # It is safe to disable this validation temporarily because LazyCompletionHelp.
+        # __repr__() returns a plain string (no % formatting)
         original_check_help = argparse.ArgumentParser._check_help  # type: ignore
         argparse.ArgumentParser._check_help = (  # type: ignore
             lambda self, action: None

tests/test_hydra.py

@@ -841,6 +841,24 @@ def test_help(
     assert_text_same(result, expected.format(script=script))
 
 
+def test_shell_completion_help(tmpdir: Path) -> None:
+    """Test that --shell-completion --help works (regression test for Python 3.14+ argparse)."""
+    # This test ensures that the LazyCompletionHelp workaround in utils.py works correctly
+    # In Python 3.14+, argparse validates that help is a string, but we use a lazy callable
+    # The workaround temporarily disables _check_help validation
+    cmd = [
+        "examples/tutorials/basic/your_first_hydra_app/1_simple_cli/my_app.py",
+        f'hydra.run.dir="{str(tmpdir)}"',
+        "hydra.job.chdir=True",
+        "--shell-completion",
+        "--help",
+    ]
+    result, _err = run_python_script(cmd)
+    # When both flags are present, --help takes precedence and shows help text
+    assert "powered by hydra" in result.lower()
+    assert not _err
+
+
 @mark.parametrize(
     "overrides,expected",
     [