fix: Use Click v8.x native shell completion

* Use click v8.x's native shell completions to produce pyhf shell completions
  for the CLI API.
   - c.f. https://click.palletsprojects.com/en/stable/shell-completion/
* Remove shellcomplete extra.
* Update tests for CLI API.
* Extend documentation for producing shell completions for Bash, Zsh, and
  Fish shells.

Author: matthewfeickert

pyproject.toml

@@ -64,7 +64,6 @@ Homepage = "https://github.com/scikit-hep/pyhf"
 "Source Code" = "https://github.com/scikit-hep/pyhf"
 
 [project.optional-dependencies]
-shellcomplete = ["click_completion"]
 jax = [
     "jax>=0.4.1",  # c.f. PR #2079
     "jaxlib>=0.4.1",  # c.f. PR #2079
@@ -76,7 +75,7 @@ contrib = [
     "requests>=2.22.0",
 ]
 backends = ["pyhf[jax,minuit]"]
-all = ["pyhf[backends,xmlio,contrib,shellcomplete]"]
+all = ["pyhf[backends,xmlio,contrib]"]
 
 # Developer extras
 [dependency-groups]

src/pyhf/cli/complete.py

@@ -1,30 +1,66 @@
-'''Shell completions for pyhf.'''
+"""Shell completions for pyhf."""
 
 import click
 
-try:
-    import click_completion
-
-    click_completion.init()
-
-    @click.command(help='Generate shell completion code.', name='completions')
-    @click.argument(
-        'shell',
-        required=False,
-        type=click_completion.DocumentedChoice(click_completion.core.shells),
-    )
-    def cli(shell):
-        '''Generate shell completion code for various shells.'''
-        click.echo(click_completion.core.get_code(shell, prog_name='pyhf'))
-
-except ImportError:
-
-    @click.command(help='Generate shell completion code.', name='completions')
-    @click.argument('shell', default=None)
-    def cli(shell):
-        """Placeholder for shell completion code generatioon function if necessary dependency is missing."""
-        click.secho(
-            "This requires the click_completion module.\n"
-            "You can install it with the shellcomplete extra:\n"
-            "python -m pip install 'pyhf[shellcomplete]'"
+
+@click.command(help="Generate shell completion code.", name="completions")
+@click.argument(
+    "shell",
+    required=False,
+    type=click.Choice(["bash", "zsh", "fish"], case_sensitive=False),
+)
+def cli(shell):
+    """Generate shell completion code for various shells.
+
+    Supported shells: bash, zsh, fish
+
+    To enable completion, run the appropriate command for your shell:
+
+    \b
+    Bash:
+      mkdir -p ~/.completions
+      _PYHF_COMPLETE=bash_source pyhf > ~/.completions/pyhf-complete.sh
+      echo ". ~/.completions/pyhf-complete.sh" >> ~/.bashrc
+
+    \b
+    Zsh:
+      mkdir -p ~/.completions
+      _PYHF_COMPLETE=zsh_source pyhf > ~/.completions/pyhf-complete.zsh
+      echo ". ~/.completions/pyhf-complete.zsh" >> ~/.zshrc
+
+    \b
+    Fish:
+      _PYHF_COMPLETE=fish_source pyhf >> ~/.config/fish/completions/pyhf.fish
+    """
+    if shell is None:
+        click.echo(cli.get_help(click.Context(cli)))
+        return
+
+    click.echo(f"To enable {shell} completion for pyhf run in your {shell} shell:\n")
+
+    if shell == "bash":
+        click.echo(
+            click.style(
+                "mkdir -p ~/.completions\n"
+                + "_PYHF_COMPLETE=bash_source pyhf > ~/.completions/pyhf-complete.sh\n"
+                + 'echo -e "\\n. ~/.completions/pyhf-complete.sh" >> ~/.bashrc\n',
+                bold=True,
+            )
+        )
+    elif shell == "zsh":
+        click.echo(
+            click.style(
+                "mkdir -p ~/.completions\n"
+                + "_PYHF_COMPLETE=zsh_source pyhf > ~/.completions/pyhf-complete.zsh\n"
+                + 'echo -e "\\n. ~/.completions/pyhf-complete.zsh" >> ~/.zshrc\n',
+                bold=True,
+            )
+        )
+    elif shell == "fish":
+        click.echo(
+            click.style(
+                "_PYHF_COMPLETE=fish_source pyhf >> ~/.config/fish/completions/pyhf.fish\n",
+                bold=True,
+            )
         )
+    click.echo("and then source your shell configuration or restart your shell.")

tests/test_cli.py

@@ -1,21 +1,40 @@
 from click.testing import CliRunner
-import sys
-import importlib
 
 
-def test_shllcomplete_cli(isolate_modules):
+def test_shell_completion_cli_bash():
     from pyhf.cli.complete import cli
 
     runner = CliRunner()
-    result = runner.invoke(cli, ['bash'])
-    assert 'complete -F _pyhf_completion -o default pyhf' in result.output
+    result = runner.invoke(cli, ["bash"])
+    assert result.exit_code == 0
+    assert "_PYHF_COMPLETE=bash_source" in result.output
+    assert ".bashrc" in result.output
 
 
-def test_shllcomplete_cli_missing_extra(isolate_modules):
-    sys.modules['click_completion'] = None
-    importlib.reload(sys.modules['pyhf.cli.complete'])
+def test_shell_completion_cli_zsh():
     from pyhf.cli.complete import cli
 
     runner = CliRunner()
-    result = runner.invoke(cli, ['bash'])
-    assert 'You can install it with the shellcomplete extra' in result.output
+    result = runner.invoke(cli, ["zsh"])
+    assert result.exit_code == 0
+    assert "_PYHF_COMPLETE=zsh_source" in result.output
+    assert ".zshrc" in result.output
+
+
+def test_shell_completion_cli_fish():
+    from pyhf.cli.complete import cli
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["fish"])
+    assert result.exit_code == 0
+    assert "_PYHF_COMPLETE=fish_source" in result.output
+    assert "fish/completions" in result.output
+
+
+def test_shell_completion_cli_no_shell():
+    from pyhf.cli.complete import cli
+
+    runner = CliRunner()
+    result = runner.invoke(cli)
+    assert result.exit_code == 0
+    assert "Generate shell completion code" in result.output