[](https://github.com/KAUTH/auto-click-auto/blob/master/LICENSE).
[](https://pypi.org/project/quick-click-auto/)
# quick-click-auto
Enable quick tab autocompletion for complex Click CLI applications.
`quick-click-auto` is a small Python library that is used to quickly add tab shell completion support for
_Bash_ (version 4.4 and up), _Zsh_ for [Click](https://click.palletsprojects.com/en/8.1.x/#) CLI programs, and can be easily integrated as a Click command:
```commandline
foo-bar shell-completion
```
## Why this fork exists
This project is a modified version of [auto-click-auto](https://github.com/KAUTH/auto-click-auto) by [KAUTH](https://github.com/KAUTH).
The original project is licensed under the [MIT License](https://github.com/nimrod-a/quick-click-auto/blob/main/LICENSE).
The main difference of this fork is the way shell completion is implemented.
In the original version, `auto-click-auto` generates the command completion scripts everytime the shell is opened.
According to the official [Click docs](https://click.palletsprojects.com/en/stable/shell-completion/#enabling-completion), this has perfomance drawbacks:
> Using eval means that the command is invoked and evaluated every time a shell is started, which can delay shell responsiveness
This Fork aims to solve the perfomace hit by utilizing Clicks alternative approach:
> To speed [command completion] up, write the generated script to a file, then source that
**This alternative approach enables quickly adding command completion to complex CLI applications, where auto-click-auto may lead to reduced performance.**
It is important to note that the improved performance only applies when `quick-click-auto` is used as a seperate click command.
In contrast to auto-click-auto, **this project currently does not automatically enable command autocompletion**.
*Due to the specific target group and the substantial changes to the original codebase needed to implement this approach, I have decided to create a detached fork, instead of contributing upstream.*
For more information, take a look at [Implementation](#implementation).
## Installation
```commandline
pip install quick-click-auto
```
## Usage
There are two functions that `quick-click-auto` makes available: `enable_click_shell_completion` (general use)
and `enable_click_shell_completion_option` (to be used as a decorator).
In the function docstrings, you can find a detailed analysis of the available parameters and their use.
`quick-click-auto` will print the relative output when a shell completion is activated for the first time and can be
set to an extra verbosity if you want to display information about already configured systems or debug.
Here are some typical ways to enable autocompletion with `quick-click-auto`:
1) **Make shell completion a command (or subcommand of a group)**
Example:
```python
import click
from quick_click_auto import enable_click_shell_completion
from quick_click_auto.constants import ShellType
@click.group()
def cli():
"""Simple CLI program."""
pass
@cli.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 command that greets NAME for a total of COUNT times."""
for x in range(count):
click.echo(f"Hello {name}!")
@cli.group()
def config():
"""Program configuration."""
pass
@config.command()
def shell_completion():
"""Activate shell completion for this program."""
enable_click_shell_completion(
program_name="example",
shells={ShellType.BASH, ShellType.ZSH},
verbose=True,
)
```
## Implementation
`quick-click-auto` enables tab autocompletion based on [Click's documentation](https://click.palletsprojects.com/en/8.1.x/shell-completion/).
To enable command completion in Click CLI applications, the user needs to manually register a special function with the shell. The exact script varies depending on which shell is used.
The approach used by `auto-click-auto` is to add a line to the shell configuration file, which generates the command completion scripts everytime the shell is started:
```commandline
eval "$(_FOO_BAR_COMPLETE=shell_source foo-bar)"
```
As said, this may lead to delayed shell responsiveness, especially in complex CLI applications. On the upside, it can enable completley automatic shell autocompletion.
`quick-click-auto` on the other hand generates the command completion scripts only once and then sources them in the shell configuration file.
This is especially useful when integrating quick-click-auto as configuration command or a CLI option and greatly improves perfomance.
Raw data
{
"_id": null,
"home_page": "https://github.com/nimrod-a/quick-click-auto",
"name": "quick-click-auto",
"maintainer": "Nim",
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": "nim@systemli.org",
"keywords": "click, autocomplete, shell",
"author": "Nim",
"author_email": "nim@systemli.org",
"download_url": "https://files.pythonhosted.org/packages/47/71/fad1f942314896fd7336c1bbae970fff21d46e44fa5f1a2e50bc88e67dec/quick_click_auto-1.0.5.tar.gz",
"platform": null,
"description": "[](https://github.com/KAUTH/auto-click-auto/blob/master/LICENSE).\n[](https://pypi.org/project/quick-click-auto/)\n\n# quick-click-auto\nEnable quick tab autocompletion for complex Click CLI applications. \n\n`quick-click-auto` is a small Python library that is used to quickly add tab shell completion support for\n_Bash_ (version 4.4 and up), _Zsh_ for [Click](https://click.palletsprojects.com/en/8.1.x/#) CLI programs, and can be easily integrated as a Click command: \n```commandline\nfoo-bar shell-completion\n```\n\n## Why this fork exists\nThis project is a modified version of [auto-click-auto](https://github.com/KAUTH/auto-click-auto) by [KAUTH](https://github.com/KAUTH).\nThe original project is licensed under the [MIT License](https://github.com/nimrod-a/quick-click-auto/blob/main/LICENSE).\n\nThe main difference of this fork is the way shell completion is implemented. \n\nIn the original version, `auto-click-auto` generates the command completion scripts everytime the shell is opened.\nAccording to the official [Click docs](https://click.palletsprojects.com/en/stable/shell-completion/#enabling-completion), this has perfomance drawbacks: \n> Using eval means that the command is invoked and evaluated every time a shell is started, which can delay shell responsiveness\n\n This Fork aims to solve the perfomace hit by utilizing Clicks alternative approach:\n> To speed [command completion] up, write the generated script to a file, then source that\n\n**This alternative approach enables quickly adding command completion to complex CLI applications, where auto-click-auto may lead to reduced performance.**\n\nIt is important to note that the improved performance only applies when `quick-click-auto` is used as a seperate click command. \n\nIn contrast to auto-click-auto, **this project currently does not automatically enable command autocompletion**. \n\n*Due to the specific target group and the substantial changes to the original codebase needed to implement this approach, I have decided to create a detached fork, instead of contributing upstream.*\n\nFor more information, take a look at [Implementation](#implementation).\n\n## Installation\n```commandline\npip install quick-click-auto\n```\n\n## Usage\nThere are two functions that `quick-click-auto` makes available: `enable_click_shell_completion` (general use)\nand `enable_click_shell_completion_option` (to be used as a decorator).\n\nIn the function docstrings, you can find a detailed analysis of the available parameters and their use.\n\n`quick-click-auto` will print the relative output when a shell completion is activated for the first time and can be\nset to an extra verbosity if you want to display information about already configured systems or debug.\n\nHere are some typical ways to enable autocompletion with `quick-click-auto`:\n\n\n1) **Make shell completion a command (or subcommand of a group)**\n\nExample:\n```python\nimport click\n\nfrom quick_click_auto import enable_click_shell_completion\nfrom quick_click_auto.constants import ShellType\n\n\n@click.group()\ndef cli():\n \"\"\"Simple CLI program.\"\"\"\n pass\n\n\n@cli.command()\n@click.option('--count', default=1, help='Number of greetings.')\n@click.option('--name', prompt='Your name', help='The person to greet.')\ndef hello(count, name):\n \"\"\"Simple command that greets NAME for a total of COUNT times.\"\"\"\n for x in range(count):\n click.echo(f\"Hello {name}!\")\n\n\n@cli.group()\ndef config():\n \"\"\"Program configuration.\"\"\"\n pass\n\n\n@config.command()\ndef shell_completion():\n \"\"\"Activate shell completion for this program.\"\"\"\n enable_click_shell_completion(\n program_name=\"example\",\n shells={ShellType.BASH, ShellType.ZSH},\n verbose=True,\n )\n```\n\n\n## Implementation\n`quick-click-auto` enables tab autocompletion based on [Click's documentation](https://click.palletsprojects.com/en/8.1.x/shell-completion/).\n\nTo enable command completion in Click CLI applications, the user needs to manually register a special function with the shell. The exact script varies depending on which shell is used.\n\nThe approach used by `auto-click-auto` is to add a line to the shell configuration file, which generates the command completion scripts everytime the shell is started: \n```commandline\neval \"$(_FOO_BAR_COMPLETE=shell_source foo-bar)\"\n```\nAs said, this may lead to delayed shell responsiveness, especially in complex CLI applications. On the upside, it can enable completley automatic shell autocompletion.\n\n`quick-click-auto` on the other hand generates the command completion scripts only once and then sources them in the shell configuration file.\n\nThis is especially useful when integrating quick-click-auto as configuration command or a CLI option and greatly improves perfomance. ",
"bugtrack_url": null,
"license": "MIT",
"summary": " Enable quick tab autocompletion for complex Click CLI applications. ",
"version": "1.0.5",
"project_urls": {
"Documentation": "https://github.com/nimrod-a/quick-click-auto/blob/main/README.md",
"Homepage": "https://github.com/nimrod-a/quick-click-auto",
"Repository": "https://github.com/nimrod-a/quick-click-auto"
},
"split_keywords": [
"click",
" autocomplete",
" shell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "234a4b3ea7762d2af3bd15fb41e12b54cad4d870c09e91ccef9d8832958616f3",
"md5": "a2f3139efb51cbe3ba1d0765f1b25320",
"sha256": "b29f321c602d26797acde972b5258ab58184ee9438f87812240e97e0ebf98895"
},
"downloads": -1,
"filename": "quick_click_auto-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2f3139efb51cbe3ba1d0765f1b25320",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 10114,
"upload_time": "2025-01-24T16:21:15",
"upload_time_iso_8601": "2025-01-24T16:21:15.619570Z",
"url": "https://files.pythonhosted.org/packages/23/4a/4b3ea7762d2af3bd15fb41e12b54cad4d870c09e91ccef9d8832958616f3/quick_click_auto-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4771fad1f942314896fd7336c1bbae970fff21d46e44fa5f1a2e50bc88e67dec",
"md5": "d1ad64328476ab2158c3d63a5cc9234f",
"sha256": "97b5ed70f47ed6de8d82f8acc3fae3078a24f2251dd45242c875bc51f5dfb618"
},
"downloads": -1,
"filename": "quick_click_auto-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "d1ad64328476ab2158c3d63a5cc9234f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 7619,
"upload_time": "2025-01-24T16:21:17",
"upload_time_iso_8601": "2025-01-24T16:21:17.717507Z",
"url": "https://files.pythonhosted.org/packages/47/71/fad1f942314896fd7336c1bbae970fff21d46e44fa5f1a2e50bc88e67dec/quick_click_auto-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-24 16:21:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nimrod-a",
"github_project": "quick-click-auto",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "quick-click-auto"
}
JSON
