completions

Shell completions for your program made easy.

Installation

pip install completions
# install lastest version using poetry
git clone https://github.com/pwwang/completions
cd completions
poetry install

Usage

Defining your completions

You may define your completions, basically commands and options, by following schema (showed in yaml, but can be any format supported by python-simpleconf: example.yaml

program:
    # your program, or path to your program
    name: completions-example
    desc: Shell completions for your program made easy.
    # whether global options should be inherited by commands
    inherit: true
    # options or global options if you have commands
    options:
        -s: The shell, one of bash, fish, zsh and auto.
        --shell: The shell, one of bash, fish, zsh and auto.
        -a: Automatically write completions to destination file.
        --auto: Automatically write completions to destination file.
commands:
    # No other options for command, give the description
    self: Generate completions for myself.
    generate:
        desc: Generate completions from configuration files.
        options:
            -c: The configuration file to load.
            --config: The configuration file to load.

How it looks like in fish:

Generating completion scripts

• Bash

  > completions generate --shell bash \
      --config example.yaml > ~/bash_completion.d/completions.bash-completion
  

  You may need to source it in your .bashrc and restart your shell for the changes to take effect.
• Fish

  > completions generate --shell fish \
      --config example.yaml > ~/.config/fish/completions/completions.fish
  

  You may need to restart your shell for the changes to take effect.
• Zsh

  > completions generate --shell zsh \
      --config example.yaml > ~/.zsh-completions/_completions
  

  Make sure fpath+=~/.zsh-completions is put before compinit in you .zshrc

Saving completions scripts automatically

• Bash

  > completions generate --shell bash --config example.yaml --auto
  

• Fish

  > completions generate --shell fish --config example.yaml --auto
  

• Zsh

  > completions generate --shell zsh --config example.yaml --auto
  

Python API

from completions import Completions
completions = Completions(
    # if not given, will be read from sys.argv[0]
    name    = 'completions',
    # Add global options to commands
    inherit = True,
    desc    = 'Shell completions for your program made easy.')
completions.addOption(
    ['-s', '--shell'],
    'The shell, one of bash, fish, zsh and auto.')
completions.addOption(
    ['-a', '--auto'],
    'Automatically write completions to destination file.')
completions.addCommand(
    'self', 'Generate completions for myself.')
completions.addCommand(
    'generate', 'Generate completions from configuration files.')
completions.command('generate').addOption(
    ['-c', '--config'], 'The configuration file to load.')
completions.generate(shell = 'fish', auto = False)