auto-click-auto

Common errors

• Shell autocompletion is not working after installing and configuring 'auto-click-auto'.

  cause This can happen if the `program_name` passed to `enable_click_shell_completion` does not match the actual executable name used to run your CLI, or if the shell's configuration (`~/.bashrc`, `~/.zshrc`, etc.) hasn't been reloaded or the necessary `eval` command hasn't been run after the initial setup. It might also be due to an unsupported shell version or type.
  fix Ensure `program_name` exactly matches how your CLI is invoked (e.g., if you run `my-app`, `program_name='my-app'`). After the first run of the CLI with `auto-click-auto` enabled, ensure you reload your shell (e.g., `source ~/.bashrc` or open a new terminal) or follow any specific instructions `auto-click-auto` prints to stdout. Double-check your shell version and type compatibility.

• Error: 'ShellType.POWERSHELL' is not a valid ShellType, or autocompletion does not work in PowerShell.

  cause `auto-click-auto` only supports Bash (4.4+), Zsh, and Fish. It does not provide built-in support for PowerShell or other shells.
  fix If you require PowerShell completion, `auto-click-auto` is not the right tool. You would need to explore Click's native methods for adding custom shell support (which is a more technical process) or look for other third-party Click extensions specifically designed for PowerShell completion, if available.

Warnings

• gotcha Click versions 8.0.0 and above include native shell completion features. While `auto-click-auto` simplifies the automatic setup, users should be aware of Click's built-in capabilities, which might be sufficient for some use cases.
  Fix: Review Click's official documentation on shell completion to understand the native options before deciding on `auto-click-auto`. If your needs are simple and manual setup is acceptable, native Click completion might be preferred.
• deprecated The project author has noted that `auto-click-auto` might be duplicating functionality now integrated into Click itself and "might need to be archived." This suggests potential long-term maintenance uncertainty or eventual deprecation if Click's native features fully encompass its purpose.
  Fix: Monitor the project's GitHub repository for updates regarding its status and any recommendations for migration to Click's native completion or alternative tools if it becomes archived. Consider this when choosing long-term dependencies.
• gotcha `auto-click-auto` explicitly supports Bash (version 4.4 and up), Zsh, and Fish. Autocompletion will not work out-of-the-box for other shell environments (e.g., PowerShell, older Bash versions).
  Fix: Verify that your target shell is one of the supported types and meets the minimum version requirements. For unsupported shells, you would need to implement custom completion logic or use another library like `click-completion` (though it's in maintenance mode for Click < 8.0).

Install

• pip install auto-click-auto Install with pip

Imports

• enable_click_shell_completion

  from auto_click_auto import enable_click_shell_completion

  Used for general, automatic enabling of shell completion within your Click application.
• enable_click_shell_completion_option

  from auto_click_auto import enable_click_shell_completion_option

  Intended to be used as a decorator on a Click command for enabling shell completion.
• ShellType

  from auto_click_auto.constants import ShellType

  Enum representing supported shell types (Bash, Zsh, Fish) for configuration.

Quickstart

This quickstart demonstrates integrating `auto-click-auto` into a basic Click CLI. The `enable_click_shell_completion` function is called at the end of the main CLI function, providing the program's executable name and a set of `ShellType` enums for which to enable completion.

import click
from auto_click_auto import enable_click_shell_completion
from auto_click_auto.constants import ShellType
import os # Only for example program_name, not strictly for auto-click-auto

@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='The person to greet.')
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")
    
    # Automatically enable shell completion for specified shells
    # Replace 'my-cli-app' with the actual executable name of your CLI
    # For testing, you might use 'python -m my_cli_module' as the program_name
    enable_click_shell_completion(
        program_name=os.path.basename(__file__).replace('.py', ''), # Derives name from script, adjust for packaged CLIs
        shells={ShellType.BASH, ShellType.ZSH, ShellType.FISH},
        # For debugging, add debug=True
    )

if __name__ == '__main__':
    hello()