[](https://github.com/KAUTH/auto-click-auto/actions/workflows/functional-tests.yml?query=workflow%3A%22Functional+tests%22)
[](https://pypi.python.org/pypi/auto-click-auto)
[](https://github.com/KAUTH/auto-click-auto/blob/master/LICENSE)
# auto-click-auto
Automatically enable tab autocompletion for shells in Click CLI applications.
`auto-click-auto` is a small Python library that is used to quickly and easily add tab shell completion support for
_Bash_ (version 4.4 and up), _Zsh_, and _Fish_, for [Click](https://click.palletsprojects.com/en/8.1.x/#) CLI programs.
## Installation
```commandline
pip install auto-click-auto
```
## Usage
There are two functions that `auto-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.
`auto-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 `auto-click-auto`:
1) **Check on every run of the CLI program if autocompletion is configured and enable it in case that it is not**
This way you can seamlessly enable shell autocompletion without the user having to run any extra commands.
Example:
```python
import click
from auto_click_auto import enable_click_shell_completion
from auto_click_auto.constants import ShellType
@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}!")
enable_click_shell_completion(
program_name="example-1", shells={ShellType.BASH, ShellType.FISH},
)
```
2) **Make shell completion a Click command option**
Example:
```python
import click
from auto_click_auto import enable_click_shell_completion_option
@click.command()
@enable_click_shell_completion_option(program_name="example-2")
@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}!")
```
3) **Make shell completion a command (or subcommand of a group)**
This implementation option might be useful if you already have a "configuration" command in your CLI program.
Example:
```python
import click
from auto_click_auto import enable_click_shell_completion
from auto_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-3",
shells={ShellType.BASH, ShellType.FISH, ShellType.ZSH},
verbose=True,
)
```
## Examples
To run the examples, fork this repository and follow the instructions at
https://github.com/KAUTH/auto-click-auto/tree/main/examples.
## Implementation
`auto-click-auto` enables tab autocompletion based on [Click's documentation](https://click.palletsprojects.com/en/8.1.x/shell-completion/).
## Name
`auto-click-auto`, as the name suggests, _auto_matically provides tab _auto_completion support for _Click_ CLI
applications.
## Why `auto-click-auto`?
In the search for other tools that enable shell completion for Click we come across a lot of repositories with example
code or gists. This adds a bit of complexity to adapting the code and adding it to our use case quickly.
A very nice tool is [`click-completion`](https://github.com/click-contrib/click-completion), which provides enhanced
completion for Click. `click-completion`:
- Adds automatic completion support for fish, Zsh, Bash and PowerShell
- Currently, has one extra dependency, in addition to Click
- Can customize the completion
However, it is important to note that this repository could be duplicating currently integrated Click functionality and
might need to be archived. You can monitor the issue
[here](https://github.com/click-contrib/click-completion/issues/41).
In summary, `auto-click-auto`:
- Has one specific purpose, it "automatically" enables shell completion for Click programs
- Does not have any 3rd party dependencies, besides Click
- Provides an option for seamless enabling of the shell completion
- Comes ready with ways to add shell completion as a command option or subcommand
- Has simple examples of how to quickly use the library
## Changelog
https://github.com/KAUTH/auto-click-auto/blob/main/CHANGELOG.md
## Contributing
You can always submit a PR if you want to suggest improvements or fix issues.
Check out the open issues at https://github.com/KAUTH/auto-click-auto/issues.
Raw data
{
"_id": null,
"home_page": "https://github.com/KAUTH/auto-click-auto",
"name": "auto-click-auto",
"maintainer": "Konstantinos Papadopoulos",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "konpap1996@yahoo.com",
"keywords": "click,autocomplete,shell",
"author": "Konstantinos Papadopoulos",
"author_email": "konpap1996@yahoo.com",
"download_url": "https://files.pythonhosted.org/packages/e1/63/ff54a6c21f2d0a0ab3e849e7d23e260de9ac587c8a51c48651f0ac7012fa/auto_click_auto-0.1.4.tar.gz",
"platform": null,
"description": "\n[](https://github.com/KAUTH/auto-click-auto/actions/workflows/functional-tests.yml?query=workflow%3A%22Functional+tests%22)\n[](https://pypi.python.org/pypi/auto-click-auto)\n[](https://github.com/KAUTH/auto-click-auto/blob/master/LICENSE)\n\n# auto-click-auto\nAutomatically enable tab autocompletion for shells in Click CLI applications.\n\n`auto-click-auto` is a small Python library that is used to quickly and easily add tab shell completion support for\n_Bash_ (version 4.4 and up), _Zsh_, and _Fish_, for [Click](https://click.palletsprojects.com/en/8.1.x/#) CLI programs.\n\n## Installation\n```commandline\npip install auto-click-auto\n```\n\n## Usage\nThere are two functions that `auto-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`auto-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 `auto-click-auto`:\n\n1) **Check on every run of the CLI program if autocompletion is configured and enable it in case that it is not**\n\nThis way you can seamlessly enable shell autocompletion without the user having to run any extra commands.\n\nExample:\n```python\nimport click\n\nfrom auto_click_auto import enable_click_shell_completion\nfrom auto_click_auto.constants import ShellType\n\n\n@click.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 program that greets NAME for a total of COUNT times.\"\"\"\n for x in range(count):\n click.echo(f\"Hello {name}!\")\n\n enable_click_shell_completion(\n program_name=\"example-1\", shells={ShellType.BASH, ShellType.FISH},\n )\n```\n\n2) **Make shell completion a Click command option**\n\nExample:\n```python\nimport click\n\nfrom auto_click_auto import enable_click_shell_completion_option\n\n\n@click.command()\n@enable_click_shell_completion_option(program_name=\"example-2\")\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 program that greets NAME for a total of COUNT times.\"\"\"\n for x in range(count):\n click.echo(f\"Hello {name}!\")\n```\n\n3) **Make shell completion a command (or subcommand of a group)**\n\nThis implementation option might be useful if you already have a \"configuration\" command in your CLI program.\n\nExample:\n```python\nimport click\n\nfrom auto_click_auto import enable_click_shell_completion\nfrom auto_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-3\",\n shells={ShellType.BASH, ShellType.FISH, ShellType.ZSH},\n verbose=True,\n )\n```\n\n## Examples\nTo run the examples, fork this repository and follow the instructions at\nhttps://github.com/KAUTH/auto-click-auto/tree/main/examples.\n\n## Implementation\n`auto-click-auto` enables tab autocompletion based on [Click's documentation](https://click.palletsprojects.com/en/8.1.x/shell-completion/).\n\n## Name\n`auto-click-auto`, as the name suggests, _auto_matically provides tab _auto_completion support for _Click_ CLI\napplications.\n\n## Why `auto-click-auto`?\nIn the search for other tools that enable shell completion for Click we come across a lot of repositories with example\ncode or gists. This adds a bit of complexity to adapting the code and adding it to our use case quickly.\n\nA very nice tool is [`click-completion`](https://github.com/click-contrib/click-completion), which provides enhanced\ncompletion for Click. `click-completion`:\n- Adds automatic completion support for fish, Zsh, Bash and PowerShell\n- Currently, has one extra dependency, in addition to Click\n- Can customize the completion\n\nHowever, it is important to note that this repository could be duplicating currently integrated Click functionality and\nmight need to be archived. You can monitor the issue\n[here](https://github.com/click-contrib/click-completion/issues/41).\n\nIn summary, `auto-click-auto`:\n- Has one specific purpose, it \"automatically\" enables shell completion for Click programs\n- Does not have any 3rd party dependencies, besides Click\n- Provides an option for seamless enabling of the shell completion\n- Comes ready with ways to add shell completion as a command option or subcommand\n- Has simple examples of how to quickly use the library\n\n## Changelog\nhttps://github.com/KAUTH/auto-click-auto/blob/main/CHANGELOG.md\n\n## Contributing\nYou can always submit a PR if you want to suggest improvements or fix issues.\nCheck out the open issues at https://github.com/KAUTH/auto-click-auto/issues.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Automatically enable tab autocompletion for shells in Click CLI applications.",
"version": "0.1.4",
"project_urls": {
"Documentation": "https://github.com/KAUTH/auto-click-auto/blob/main/README.md",
"Homepage": "https://github.com/KAUTH/auto-click-auto",
"Repository": "https://github.com/KAUTH/auto-click-auto"
},
"split_keywords": [
"click",
"autocomplete",
"shell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff87cf5625c09797d076b98606a235e9d1e03225ac1558e317905e364e9d398f",
"md5": "54644dbe9645ef673cd03d406ac9046a",
"sha256": "22ea4c9a8bb5c56c251ff1d070ac4dbdf2f047084960df818f909c139d0cae68"
},
"downloads": -1,
"filename": "auto_click_auto-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54644dbe9645ef673cd03d406ac9046a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 9578,
"upload_time": "2024-01-15T21:05:50",
"upload_time_iso_8601": "2024-01-15T21:05:50.018297Z",
"url": "https://files.pythonhosted.org/packages/ff/87/cf5625c09797d076b98606a235e9d1e03225ac1558e317905e364e9d398f/auto_click_auto-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e163ff54a6c21f2d0a0ab3e849e7d23e260de9ac587c8a51c48651f0ac7012fa",
"md5": "d0c4b74b58b2490f0f983f0616965d51",
"sha256": "f14f9cfadf0ba5f9ac0680c73fa0d0beb46e7e074a556f4057fe3aab999b53b8"
},
"downloads": -1,
"filename": "auto_click_auto-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "d0c4b74b58b2490f0f983f0616965d51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 9423,
"upload_time": "2024-01-15T21:05:51",
"upload_time_iso_8601": "2024-01-15T21:05:51.244395Z",
"url": "https://files.pythonhosted.org/packages/e1/63/ff54a6c21f2d0a0ab3e849e7d23e260de9ac587c8a51c48651f0ac7012fa/auto_click_auto-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-15 21:05:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KAUTH",
"github_project": "auto-click-auto",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "auto-click-auto"
}
JSON
