feature: Support distributed shell completion scripts (like man pages)

[pawamoy]

Note: I opened the same issue on uv's tracker, see astral-sh/uv#11354.

---

Given pipx already supports manual pages (see #1047), I was wondering if you would also consider supporting shell completion scripts. Surely if pipx can instruct authors to put their manual pages in specific data paths in Python distributions (sdists, wheels), for pipx to symlink them in a given location at install time, and to instruct users to add this location to their man configuration, it could do a similar thing for shell completion scripts?

We're currently trying to add shell completion scripts into a project, and we're following the usual route of:

• add a "completions" flag/command to the CLI
• tell users how to run the command and redirect its output in a standard location (or if not standard how to then configure their shell to load the completions)
• optionally add an "install completions" flag/command that does the above automatically

Even with an "install completions" command, it's quite cumbersome for users:

• They have to read our docs (web/CLI help) to learn whether we implemented completions, and how we implemented them.
• They then have to run the documented commands after each installation of the package (completions could have changed).
• Each project has to pollute their CLI with such completion flags/commands.

I think it would be much, much easier for both users and authors if authors could just distribute shell completion scripts that installers like pipx would symlink in central locations, that users could then easily load 🙂

Note that I searched in both yours and uv's trackers and couldn't find any similar feature request or discussion (sorry if I missed it). I also understand this feature would not be backed by a standard (I believe?), though manual pages are not backed by one either.

---

Before (best-case scenario):

• user installs package A: pipx install pkg-a
• user installs completions for package A: pkg-a --install-completions (also each time package is upgraded)
• user installs package B: pipx install pkg-b
• user installs completions for package B: pkg-b install-shell-completions --shell=zsh (also each time package is upgraded)
• etc.

After:

• user configures shell once to load completions from pipx's completions directory
• user installs package A: pipx install pkg-a
• user installs package B: pipx install pkg-b
• etc.