Fix shtab bash completions list choices on <TAB><TAB> for types that accept other values

[mauvilsa]

What does this PR do?

Some types have choices but also accept other values, e.g. int | None or SomeEnum | list[SomeEnum]. For these, bash completions require a prefix before completing a choice (#851). Otherwise a single TAB would insert the only choice, e.g. null, when the user wants to type a number. However, the prefix was also required on , so the choices were never listed, and the user had no way to know which prefix to type.

Now the two cases are handled differently. Without a prefix, a single TAB (COMP_TYPE=9) still completes nothing, while (COMP_TYPE=63) lists the choices. When there is a single choice, bash inserts it even on , so an extra empty completion is added to make bash only list it.

Changes:

• _completions.py: in the bash typehint completion function, the prefix is only required when COMP_TYPE is not 63, and an empty completion is added when a single choice is listed without a prefix.
• pyproject.toml: the minimum is now shtab>=1.9.1. Older versions split the output of the completion function on whitespace, which drops the empty completion, so the single choice would be inserted. This also makes the exclusions of 1.8.2 and 1.9.0 unnecessary.
• test_shtab.py: the no-prefix cases now expect the choices to be listed. There is a new test that a single TAB completes nothing, and an interactive pty test checking that a single choice is listed on but not inserted. The pty setup is moved to an interactive_bash context manager shared with the existing interactive test.
• DOCUMENTATION.rst: the completion behavior section mentions this exception, and a note says the guidance requires bash 4 or newer, since older versions, e.g. bash 3.2 in macOS, don't set COMP_TYPE.

Before submitting

• Did you read the contributing guideline?
• If you used a coding agent, did you fully understand and validate all generated code and ensure it follows the contributing guidelines?
• Did you update the documentation? (readme and public docstrings)
• Did you write unit tests such that there is 100% coverage on related code? (required for bug fixes and new features)
• Did you verify that new and existing tests pass locally?
• If this is a bug fix, did you verify that the tests fail without the code fix?
• Did you make sure that all changes preserve backward compatibility?
• Did you update the CHANGELOG including a pull request link? (not for typos, docs, test updates, or minor internal changes/refactors)

[greptile-apps]

Greptile Summary

This PR corrects Bash completion behavior for type hints that offer explicit choices while also accepting arbitrary values.

• Distinguishes single-TAB insertion from double-TAB listing using COMP_TYPE.
• Prevents Bash from inserting a sole choice when the user only requested a list.
• Raises the minimum shtab version required to preserve empty completions.
• Adds direct and interactive coverage and documents the Bash version requirement.

Confidence Score: 5/5

The PR appears safe to merge, with the completion behavior covered through both direct function tests and an interactive Bash session.

No actionable failures remain; the implementation preserves single-TAB behavior, enables double-TAB listing, and verifies that a sole choice is not inserted.

Important Files Changed

Filename	Overview
jsonargparse/_completions.py	Separates single- and double-TAB handling and adds an empty completion to force list-only behavior for one choice.
jsonargparse_tests/test_shtab.py	Adds direct and PTY-backed coverage for no-prefix completion while extracting a reusable interactive Bash fixture.
pyproject.toml	Raises the optional shtab dependency minimum to the version that preserves empty completion entries.
DOCUMENTATION.rst	Documents the completion exception and the Bash 4+ requirement for guidance.
CHANGELOG.rst	Records the corrected double-TAB choice-listing behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Type accepts open values and has choices] --> B{Current word empty?}
    B -- No --> C[Generate prefix-matching choices]
    B -- Yes --> D{COMP_TYPE equals 63?}
    D -- No: single TAB --> E[Return no choices]
    D -- Yes: double TAB --> F[Generate all choices]
    F --> G{Exactly one choice?}
    G -- Yes --> H[Append empty completion]
    G -- No --> I[List choices]
    H --> I
    C --> J[Return matching choices]

Loading

_{Reviews (1): Last reviewed commit: "shtab bash completions now list the choi..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (945c917) to head (fa06ccd).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #976   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           27        27           
  Lines         9043      9043           
=========================================
  Hits          9043      9043           

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud