completions 0.0.8
Shell completions made easy.
License: MIT
Requires Python: >=3.4,<4.0

# completions

[![pypi][1]][2] [![tag][3]][4] [![travis][5]][6] [![codacy quality][7]][8] ![pyver][11]

Shell completions for your program made easy.

## Installation
```shell
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`][12]:
`example.yaml`
```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`:
![command][13]
![option][14]

### Generating completion scripts
- Bash
    ```shell
    > 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
    ```shell
    > 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
    ```shell
    > 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
    ```shell
    > completions generate --shell bash --config example.yaml --auto
    ```

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

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

### Python API
```python
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)
```

[1]: https://img.shields.io/pypi/v/completions.svg?style=flat-square
[2]: https://pypi.org/project/completions/
[3]: https://img.shields.io/github/tag/pwwang/completions.svg?style=flat-square
[4]: https://github.com/pwwang/completions
[5]: https://img.shields.io/travis/pwwang/completions.svg?style=flat-square
[6]: https://travis-ci.org/pwwang/completions
[7]: https://img.shields.io/codacy/grade/98c8035ccd4c4f97b454086271a1b1c1.svg?style=flat-square
[8]: https://app.codacy.com/project/pwwang/completions/dashboard
[11]: https://img.shields.io/pypi/pyversions/completions.svg?style=flat-square
[12]: https://github.com/pwwang/simpleconf
[13]: https://raw.githubusercontent.com/pwwang/completions/master/examples/command.png
[14]: https://raw.githubusercontent.com/pwwang/completions/master/examples/option.png