Automagic shell tab completion for Python CLI applications

Warnings

• gotcha Shell environment setup is crucial. Users must ensure their shell (e.g., bash, zsh) is configured to source completion scripts, and the `shtab`-generated script is placed in a directory where the shell looks for completions (e.g., `~/.bashrc.d/`, `$fpath` for zsh). In addition, both `shtab` and the application it's completing must be accessible/importable from the environment where the completion script is generated and used.
  Fix: Refer to `shtab` documentation for OS-specific installation steps for bash-completion or zsh completion. Ensure your shell config (`.bashrc`, `.zshrc`) properly sources completion files and that the generated script is in the correct location. Verify `shtab` and your application are in `PATH` and `PYTHONPATH` if necessary.
• gotcha By default, `shtab` may silently fail if it cannot import the requested application's parser object. This can lead to confusion if completion isn't working as expected without any error messages. Additionally, the `prog` argument of `argparse.ArgumentParser` must accurately reflect the executable's name for correct completion, especially when using `options.entry_points.console_scripts` or direct script execution.
  Fix: When using `shtab` from the CLI, add the `--error-unimportable` flag to get explicit error messages if the parser cannot be imported. Always ensure `argparse.ArgumentParser(prog="YOUR_CLI_NAME")` matches the name users will type, or use `shtab --prog=YOUR_CLI_NAME ...` to override it.

Install

• pip install shtab PyPI
• conda install -c conda-forge shtab Conda

Imports

• complete

  import shtab; shtab.complete(...)

  While 'from shtab import complete' might work, the documentation and common usage patterns often show `import shtab` and then `shtab.complete()` or `shtab.add_argument()` on the parser directly, especially when integrating with an existing application's parser.
• add_argument

  import shtab; shtab.add_argument(parser, ...)

  Used to add a completion argument directly to an argparse parser for library usage.

Quickstart

This quickstart demonstrates how to integrate `shtab` into an `argparse`-based CLI application. By calling `shtab.add_argument(parser)`, a hidden argument (e.g., `--print-completion`) is added to your parser, allowing users to generate completion scripts for their shell. Users would then run `python your_script.py --print-completion bash` to get the script and install it according to their shell's instructions (e.g., sourcing it in their `.bashrc`). The example includes common argparse features like choices and environment variable defaults.

import argparse
import shtab
import os

def get_main_parser():
    parser = argparse.ArgumentParser(prog='mycli', description='A simple CLI tool')
    parser.add_argument('--auth-key', type=str, default=os.environ.get('MYCLI_AUTH_KEY', ''), help='Authentication key')
    parser.add_argument('--output', '-o', choices=['json', 'yaml', 'text'], default='text', help='Output format')
    parser.add_argument('command', choices=['status', 'run', 'config'], help='Command to execute')
    return parser

if __name__ == '__main__':
    parser = get_main_parser()
    
    # Integrate shtab for completion. This creates a hidden argument like --print-completion
    shtab.add_argument(parser, shells=['bash', 'zsh', 'tcsh'])
    
    args = parser.parse_args()

    # Example of how a user would generate and install completion:
    # mycli --print-completion bash > ~/.bashrc.d/mycli.bash-completion
    # source ~/.bashrc.d/mycli.bash-completion
    
    print(f"Running command: {args.command}")
    if args.auth_key:
        print("Auth key provided.")
    else:
        print("No auth key provided.")
    print(f"Output format: {args.output}")