Skip to content

Name the zsh completion function _<prog> so autoload works#1866

Open
apoorva-01 wants to merge 1 commit into
fastapi:masterfrom
apoorva-01:fix/zsh-completion-autoload-name
Open

Name the zsh completion function _<prog> so autoload works#1866
apoorva-01 wants to merge 1 commit into
fastapi:masterfrom
apoorva-01:fix/zsh-completion-autoload-name

Conversation

@apoorva-01

@apoorva-01 apoorva-01 commented Jun 29, 2026

Copy link
Copy Markdown

Fixes #1864.

Problem

zsh autoloads a completion from a file in $fpath named after the command (say _prog), and the autoload convention requires the function that file defines to match the filename. Typer generated the function as _<prog>_completion, so when it's loaded that way the completion silently fails. zsh autoloads _prog, finds no _prog function, and falls back to filename completion instead of command completion:

#compdef hf
_hf_completion() { ... }     # autoloaded file is named "_hf", so there's no "_hf" function
compdef _hf_completion hf

It hits two paths. Packaging (prog --show-completion=zsh > $fpath/_hf), which is what the issue reports. And --install-completion, which writes the script to ~/.zfunc/_<prog> and adds fpath+=~/.zfunc; autoload -Uz compinit, so the same autoload route.

Fix

Generate _<prog> instead of _<prog>_completion. The #compdef/compdef lines already register the completion, so the _completion suffix wasn't buying anything, and dropping it makes the function name match the autoloaded filename:

#compdef hf
_hf() { ... }
compdef _hf hf

The zsh script is rendered in two places, get_completion_script (the --show-completion/--install-completion path) and ZshComplete.source() (the _<PROG>_COMPLETE=source_zsh runtime path), so I updated both to keep them consistent. It's zsh-only. bash/fish/PowerShell output is unchanged (bash keeps _<prog>_completion, which has no filename constraint).

Tests

Updated the three existing zsh completion assertions (test_completion.py, test_completion_show.py, test_completion_install.py) to expect _<prog> and to check the old _completion suffix is gone. They pass with the fix and fail without it. Full tests/test_completion/ suite passes locally (77 passed). ruff check/format clean.

zsh autoloads a completion from a file in $fpath named after the command
(e.g. _prog), and the function that file defines must match that filename.
Typer generated _<prog>_completion, so a completion installed the standard
packaged way - or via --install-completion, which writes the script to
~/.zfunc/_<prog> and autoloads it - silently failed: zsh autoloaded _prog
but the file defined no _prog function.

Generate _<prog> instead, in both the script shown by --show-completion /
--install-completion and the source emitted for the _<PROG>_COMPLETE=source_zsh
runtime path. The "#compdef"/"compdef" lines already register the completion,
so dropping the suffix changes nothing else. Bash output is unchanged.
@phalberg

Copy link
Copy Markdown
Contributor

Hey,
I am not maintainer of the project but nonetheless, some thoughts of this PR:

  1. Please follow the guidelines, as per: https://tiangolo.com/open-source/contributing/#start-with-a-discussion, the issue/discussion has never gotten approval from a maintainer to open a PR for it (yet).
  2. Please add a statement about AI usage (if any).

Thanks! I will not be replying to questions for this comment as I do not want to burden the maintainers time more.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

zsh --show-completion function name breaks autoload convention

3 participants