fix: Use Click v8.x native shell completion #2639

matthewfeickert · 2025-11-21T19:09:12Z

Description

Resolves #2622

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.

Checklist Before Requesting Reviewer

Tests are passing
"WIP" removed from the title of the pull request
Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

Summarize commit messages into a comprehensive review of the PR

* 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.

matthewfeickert

The tab completions are currently very slow, so I'm not sure what's happening there.

Some of this is LLM generated to get a working scaffolding, so this shouldn't be merged until things are better understood and the docs are updated significantly.

codecov · 2025-11-21T19:16:27Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.23%. Comparing base (cad5592) to head (ddf9fde).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2639      +/-   ##
==========================================
- Coverage   98.23%   98.23%   -0.01%     
==========================================
  Files          65       65              
  Lines        4190     4188       -2     
  Branches      453      454       +1     
==========================================
- Hits         4116     4114       -2     
  Misses         45       45              
  Partials       29       29

Flag	Coverage Δ
contrib	`98.11% <100.00%> (-0.01%)`	⬇️
doctest	`98.23% <100.00%> (-0.01%)`	⬇️
unittests-3.10	`96.41% <100.00%> (-0.01%)`	⬇️
unittests-3.11	`96.41% <100.00%> (-0.01%)`	⬇️
unittests-3.12	`96.41% <100.00%> (-0.01%)`	⬇️
unittests-3.13	`96.41% <100.00%> (-0.01%)`	⬇️
unittests-3.9	`96.46% <100.00%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

kratsg · 2025-11-21T21:13:49Z

The tab completions are currently very slow, so I'm not sure what's happening there.

From the docs:

Using eval means that the command is invoked and evaluated every time a shell is started, which can delay shell responsiveness. To speed it up, write the generated script to a file, then source that. You can generate the files ahead of time and distribute them with your program to save your users a step.

If you generate it ahead of time, then it won't be as slow, but it's still going to be slow.

matthewfeickert · 2025-11-22T01:42:28Z

If you generate it ahead of time, then it won't be as slow, but it's still going to be slow.

This is actually how I was testing it, I just wrote the docs to be more trivial. Though I guess we should give people the best shot at having things not be horribly slow, so I should revise this.

matthewfeickert · 2025-11-22T07:51:04Z

From @henryiii:

Sounds like you need 3.15's lazy imports. 🙂 (Maybe https://github.com/scientific-python/lazy-loader would help in the interim)?

matthewfeickert · 2025-11-27T07:14:43Z

@kratsg This is ready for review. My suggestion is that even though we know this is slow for the time being (though would still be good to get your check on this also) that we move forward with it so that we can drop an outdated and deprecated dependency and extra`.

Copilot

Pull request overview

This PR migrates from the external click_completion library to Click v8.x's native shell completion functionality, simplifying the dependency structure and modernizing the shell completion implementation.

Key changes:

Replaced click_completion dependency with Click v8.x native shell completion API
Removed the shellcomplete optional dependency extra from pyproject.toml
Updated CLI tests to verify the new completion implementation for bash, zsh, and fish shells

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/pyhf/cli/complete.py	Migrated from click_completion to Click v8.x native completion API with inline documentation for bash, zsh, and fish shells
tests/test_cli.py	Replaced legacy tests with new tests for bash, zsh, and fish completion instructions, plus a test for no-shell invocation
pyproject.toml	Removed shellcomplete extra and updated the "all" extra to exclude it

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/pyhf/cli/complete.py

Copilot · 2025-11-27T07:15:21Z

src/pyhf/cli/complete.py

+    Bash:
+      mkdir -p ~/.completions
+      _PYHF_COMPLETE=bash_source pyhf > ~/.completions/pyhf-complete.sh
+      echo ". ~/.completions/pyhf-complete.sh" >> ~/.bashrc


The docstring instructions don't match the actual command output. The docstring shows:

echo ". ~/.completions/pyhf-complete.sh" >> ~/.bashrc

But the actual command output includes -e flag and \\n:

echo -e "\\n. ~/.completions/pyhf-complete.sh" >> ~/.bashrc

These should be consistent. Either update the docstring to match the output, or simplify the output to match the docstring.

* 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.

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-27T07:26:21Z

src/pyhf/cli/complete.py

+    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 -e "\n. ~/.completions/pyhf-complete.sh" >> ~/.bashrc
+
+    \b
+    Zsh:
+      mkdir -p ~/.completions
+      _PYHF_COMPLETE=zsh_source pyhf > ~/.completions/pyhf-complete.zsh
+      echo -e "\n. ~/.completions/pyhf-complete.zsh" >> ~/.zshrc
+
+    \b
+    Fish:
+      _PYHF_COMPLETE=fish_source pyhf >> ~/.config/fish/completions/pyhf.fish


The shell completion instructions are duplicated in both the docstring (lines 20-33) and the instructions dictionary (lines 42-55). This creates a maintenance burden where updates must be made in two places. Consider removing the detailed instructions from the docstring and keeping only the high-level description, or generate the help text dynamically from the instructions dictionary.

Suggested change

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 -e "\n. ~/.completions/pyhf-complete.sh" >> ~/.bashrc

\b

Zsh:

mkdir -p ~/.completions

_PYHF_COMPLETE=zsh_source pyhf > ~/.completions/pyhf-complete.zsh

echo -e "\n. ~/.completions/pyhf-complete.zsh" >> ~/.zshrc

\b

Fish:

_PYHF_COMPLETE=fish_source pyhf >> ~/.config/fish/completions/pyhf.fish

Supported shells: bash, zsh, fish.

When run, this command will print instructions for enabling shell completion

for the specified shell.

Copilot · 2025-11-27T07:26:22Z

src/pyhf/cli/complete.py

+            bold=True,
        )
+    )
+    click.echo("and then source your shell configuration or restart your shell.")


Missing capitalization at the start of the sentence. The sentence should begin with a capital letter for consistency with standard English grammar.

Suggested change

click.echo("and then source your shell configuration or restart your shell.")

click.echo("And then source your shell configuration or restart your shell.")

matthewfeickert self-assigned this Nov 21, 2025

matthewfeickert added this to pyhf v0.8.0 Nov 21, 2025

matthewfeickert added fix A bug fix CLI Affects the CLI API labels Nov 21, 2025

github-project-automation bot moved this to In progress in pyhf v0.8.0 Nov 21, 2025

matthewfeickert commented Nov 21, 2025

View reviewed changes

matthewfeickert added the dependencies Pull requests that update a dependency file label Nov 21, 2025

matthewfeickert force-pushed the fix/use-click-8-shell-completions branch 2 times, most recently from 63a065d to 0f7d17c Compare November 27, 2025 07:12

matthewfeickert marked this pull request as ready for review November 27, 2025 07:12

matthewfeickert requested review from Copilot and kratsg November 27, 2025 07:13

Copilot started reviewing on behalf of matthewfeickert November 27, 2025 07:13 View session

Copilot finished reviewing on behalf of matthewfeickert November 27, 2025 07:14

matthewfeickert added the build Changes that affect the build system or external dependencies label Nov 27, 2025

Copilot AI reviewed Nov 27, 2025

View reviewed changes

matthewfeickert force-pushed the fix/use-click-8-shell-completions branch from 0f7d17c to 65f1163 Compare November 27, 2025 07:22

matthewfeickert added 2 commits November 27, 2025 00:23

Put newline in shell docstring and simplify logic

ddf9fde

matthewfeickert force-pushed the fix/use-click-8-shell-completions branch from 65f1163 to ddf9fde Compare November 27, 2025 07:23

matthewfeickert requested a review from Copilot November 27, 2025 07:24

Copilot started reviewing on behalf of matthewfeickert November 27, 2025 07:24 View session

Copilot finished reviewing on behalf of matthewfeickert November 27, 2025 07:25

Copilot AI reviewed Nov 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: Use Click v8.x native shell completion #2639

fix: Use Click v8.x native shell completion #2639

matthewfeickert commented Nov 21, 2025 •

edited

Loading

Uh oh!

matthewfeickert left a comment

Uh oh!

codecov bot commented Nov 21, 2025 •

edited

Loading

Uh oh!

kratsg commented Nov 21, 2025

Uh oh!

matthewfeickert commented Nov 22, 2025

Uh oh!

matthewfeickert commented Nov 22, 2025

Uh oh!

matthewfeickert commented Nov 27, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 27, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Nov 27, 2025

Uh oh!

Copilot AI Nov 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	click.echo("and then source your shell configuration or restart your shell.")
	click.echo("And then source your shell configuration or restart your shell.")

fix: Use Click v8.x native shell completion #2639

Are you sure you want to change the base?

fix: Use Click v8.x native shell completion #2639

Conversation

matthewfeickert commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist Before Requesting Reviewer

Before Merging

Uh oh!

matthewfeickert left a comment

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

kratsg commented Nov 21, 2025

Uh oh!

matthewfeickert commented Nov 22, 2025

Uh oh!

matthewfeickert commented Nov 22, 2025

Uh oh!

matthewfeickert commented Nov 27, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 27, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matthewfeickert commented Nov 21, 2025 •

edited

Loading

codecov bot commented Nov 21, 2025 •

edited

Loading