# `click-complete` - Shell Completion for Click CLI Applications
`click-complete` is a Python library that simplifies the process of adding shell completion support to Click-based CLI applications.
______________________________________________________________________
## Features
- **Shell Completion Generation**: Automatically generate shell completion scripts for your Click CLI applications.
- **Customizable Options**: Add a `--completion` option to your CLI commands to generate completion scripts on the fly.
- **Support for Multiple Shells**: Currently supports `fish` shell, with extensibility for `bash` and `zsh`.
- **File Validation**: Includes a custom `FileType` parameter type for validating file paths and extensions.
______________________________________________________________________
## Installation
You can install `click-complete` via pip:
```bash
pip install click-complete
```
______________________________________________________________________
## Quick Start
### Adding Shell Completion to a Click Command
Use the `completion_option` decorator to add a `--completion` option to your Click command:
```python
import click
from click_complete import completion_option
@click.command()
@completion_option()
def mycli():
"""A sample CLI tool."""
click.echo("Welcome to my CLI!")
if __name__ == "__main__":
mycli()
```
Run the command with the `--completion` option to generate a completion script:
```bash
$ mycli --completion fish
# Fish completion script for mycli
```
### Adding a Completion Command to a Click Group
Use the `completion_command` function to add a dedicated `completion` command to your Click group:
```python
import click
from click_complete import completion_command
@click.group()
def cli():
"""A sample CLI group."""
pass
# Add the completion command
cli.add_command(completion_command(program_name="my_app"))
if __name__ == "__main__":
cli()
```
Run the `completion` command to generate a completion script:
```bash
$ my_app completion fish
# Fish completion script for my_app
```
### Validating File Paths
Use the `FileType` parameter type to validate file paths and extensions:
```python
import click
from click_complete import FileType
@click.command()
@click.argument("file", type=FileType([".json", ".txt"]))
def validate_file(file):
"""Validate a file path and extension."""
click.echo(f"File '{file}' is valid!")
if __name__ == "__main__":
validate_file()
```
Run the command with a valid file path:
```bash
$ validate_file example.json
File 'example.json' is valid!
```
______________________________________________________________________
## API Reference
### `get_completion`
```python
def get_completion(
cli: Union[click.Group, click.Command],
program_name: str,
shell: str
) -> str:
"""
Generate a shell completion script for the given CLI program.
Args:
cli: The Click command or group to generate completion for.
program_name: The name of the CLI program.
shell: The type of shell to generate completion for (e.g., 'fish').
Returns:
The completion script as a string.
Raises:
click.UsageError: If the specified shell is not supported or not found.
"""
```
### `completion_option`
```python
def completion_option(
*param_decls: str,
program_name: Optional[str] = None,
**kwargs: Any,
) -> _Decorator[FC]:
"""
A decorator to add an option for generating shell completion scripts.
Parameters:
param_decls: Names of the option (e.g., "--completion").
program_name: The name of the program. If not provided, it will be inferred.
kwargs: Additional keyword arguments passed to `click.option`.
Returns:
A Click decorator for adding the completion option.
"""
```
### `completion_command`
```python
def completion_command(
program_name: Optional[str] = None,
**kwargs: Any,
) -> click.Command:
"""
Create a Click command to generate shell autocompletion scripts.
Args:
program_name: The name of the program. If not provided, it will be inferred.
**kwargs: Additional keyword arguments to customize the `@click.command`.
Returns:
A Click command to handle autocompletion generation.
"""
```
### `FileType`
```python
class FileType(click.ParamType):
"""
Custom Click parameter type to validate file paths and extensions.
Args:
extensions: A list of valid file extensions (e.g., ['.json', '.txt']).
case_sensitive: If False, extension checks will be case-insensitive.
readable: If True, the file must be readable.
exists: If True, the file must exist.
resolve_path: If True, resolve the path to an absolute path.
writable: If True, the file must be writable.
executable: If True, the file must be executable.
"""
```
______________________________________________________________________
## Supported Shells
Currently, `click-complete` supports the following shells:
- `fish`
- `bash` (coming soon)
- `zsh` (coming soon)
______________________________________________________________________
## Contributing
Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/xMohnad/click-complete).
______________________________________________________________________
## License
`click-complete` is licensed under the MIT License. See [MIT License](https://opensource.org/licenses/MIT) for more details.
______________________________________________________________________
## Acknowledgments
- Built on top of the amazing [Click](https://click.palletsprojects.com/) library.
- Inspired by [shellingham](https://github.com/sarugaku/shellingham) for shell detection.
Raw data
{
"_id": null,
"home_page": "https://github.com/xMohnad/click-complete",
"name": "click-complete",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "click shell auto-complete automation",
"author": "xMohnad",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9c/be/f465ee0dddcf9d55f872e4b465823c533ae5a911d127aac97555678bb066/click_complete-0.1.0.tar.gz",
"platform": null,
"description": "# `click-complete` - Shell Completion for Click CLI Applications\n\n`click-complete` is a Python library that simplifies the process of adding shell completion support to Click-based CLI applications.\n\n______________________________________________________________________\n\n## Features\n\n- **Shell Completion Generation**: Automatically generate shell completion scripts for your Click CLI applications.\n- **Customizable Options**: Add a `--completion` option to your CLI commands to generate completion scripts on the fly.\n- **Support for Multiple Shells**: Currently supports `fish` shell, with extensibility for `bash` and `zsh`.\n- **File Validation**: Includes a custom `FileType` parameter type for validating file paths and extensions.\n\n______________________________________________________________________\n\n## Installation\n\nYou can install `click-complete` via pip:\n\n```bash\npip install click-complete\n```\n\n______________________________________________________________________\n\n## Quick Start\n\n### Adding Shell Completion to a Click Command\n\nUse the `completion_option` decorator to add a `--completion` option to your Click command:\n\n```python\nimport click\nfrom click_complete import completion_option\n\n@click.command()\n@completion_option()\ndef mycli():\n \"\"\"A sample CLI tool.\"\"\"\n click.echo(\"Welcome to my CLI!\")\n\nif __name__ == \"__main__\":\n mycli()\n```\n\nRun the command with the `--completion` option to generate a completion script:\n\n```bash\n$ mycli --completion fish\n# Fish completion script for mycli\n```\n\n### Adding a Completion Command to a Click Group\n\nUse the `completion_command` function to add a dedicated `completion` command to your Click group:\n\n```python\nimport click\nfrom click_complete import completion_command\n\n@click.group()\ndef cli():\n \"\"\"A sample CLI group.\"\"\"\n pass\n\n# Add the completion command\ncli.add_command(completion_command(program_name=\"my_app\"))\n\nif __name__ == \"__main__\":\n cli()\n```\n\nRun the `completion` command to generate a completion script:\n\n```bash\n$ my_app completion fish\n# Fish completion script for my_app\n```\n\n### Validating File Paths\n\nUse the `FileType` parameter type to validate file paths and extensions:\n\n```python\nimport click\nfrom click_complete import FileType\n\n@click.command()\n@click.argument(\"file\", type=FileType([\".json\", \".txt\"]))\ndef validate_file(file):\n \"\"\"Validate a file path and extension.\"\"\"\n click.echo(f\"File '{file}' is valid!\")\n\nif __name__ == \"__main__\":\n validate_file()\n```\n\nRun the command with a valid file path:\n\n```bash\n$ validate_file example.json\nFile 'example.json' is valid!\n```\n\n______________________________________________________________________\n\n## API Reference\n\n### `get_completion`\n\n```python\ndef get_completion(\n cli: Union[click.Group, click.Command],\n program_name: str,\n shell: str\n) -> str:\n \"\"\"\n Generate a shell completion script for the given CLI program.\n\n Args:\n cli: The Click command or group to generate completion for.\n program_name: The name of the CLI program.\n shell: The type of shell to generate completion for (e.g., 'fish').\n\n Returns:\n The completion script as a string.\n\n Raises:\n click.UsageError: If the specified shell is not supported or not found.\n \"\"\"\n```\n\n### `completion_option`\n\n```python\ndef completion_option(\n *param_decls: str,\n program_name: Optional[str] = None,\n **kwargs: Any,\n) -> _Decorator[FC]:\n \"\"\"\n A decorator to add an option for generating shell completion scripts.\n\n Parameters:\n param_decls: Names of the option (e.g., \"--completion\").\n program_name: The name of the program. If not provided, it will be inferred.\n kwargs: Additional keyword arguments passed to `click.option`.\n\n Returns:\n A Click decorator for adding the completion option.\n \"\"\"\n```\n\n### `completion_command`\n\n```python\ndef completion_command(\n program_name: Optional[str] = None,\n **kwargs: Any,\n) -> click.Command:\n \"\"\"\n Create a Click command to generate shell autocompletion scripts.\n\n Args:\n program_name: The name of the program. If not provided, it will be inferred.\n **kwargs: Additional keyword arguments to customize the `@click.command`.\n\n Returns:\n A Click command to handle autocompletion generation.\n \"\"\"\n```\n\n### `FileType`\n\n```python\nclass FileType(click.ParamType):\n \"\"\"\n Custom Click parameter type to validate file paths and extensions.\n\n Args:\n extensions: A list of valid file extensions (e.g., ['.json', '.txt']).\n case_sensitive: If False, extension checks will be case-insensitive.\n readable: If True, the file must be readable.\n exists: If True, the file must exist.\n resolve_path: If True, resolve the path to an absolute path.\n writable: If True, the file must be writable.\n executable: If True, the file must be executable.\n \"\"\"\n```\n\n______________________________________________________________________\n\n## Supported Shells\n\nCurrently, `click-complete` supports the following shells:\n\n- `fish`\n- `bash` (coming soon)\n- `zsh` (coming soon)\n\n______________________________________________________________________\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/xMohnad/click-complete).\n\n______________________________________________________________________\n\n## License\n\n`click-complete` is licensed under the MIT License. See [MIT License](https://opensource.org/licenses/MIT) for more details.\n\n______________________________________________________________________\n\n## Acknowledgments\n\n- Built on top of the amazing [Click](https://click.palletsprojects.com/) library.\n- Inspired by [shellingham](https://github.com/sarugaku/shellingham) for shell detection.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate shell completion scripts for Click apps.",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/xMohnad/click-complete/issues",
"Homepage": "https://github.com/xMohnad/click-complete",
"Source": "https://github.com/xMohnad/click-complete"
},
"split_keywords": [
"click",
"shell",
"auto-complete",
"automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "07b39468ebc484709b0dcfcbb7b15c471826354f1a202d9c18d81666996bcc3f",
"md5": "195d6e0f9560c3faa985a6d6b1087a97",
"sha256": "9f9b0e13466740fde55e3489291926f8bf7046bd9d6e9ae5d911e4c65b0b5d76"
},
"downloads": -1,
"filename": "click_complete-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "195d6e0f9560c3faa985a6d6b1087a97",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 11222,
"upload_time": "2025-02-12T05:12:02",
"upload_time_iso_8601": "2025-02-12T05:12:02.051668Z",
"url": "https://files.pythonhosted.org/packages/07/b3/9468ebc484709b0dcfcbb7b15c471826354f1a202d9c18d81666996bcc3f/click_complete-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9cbef465ee0dddcf9d55f872e4b465823c533ae5a911d127aac97555678bb066",
"md5": "3d5326de07e0bb3cc10c26f6fed3b067",
"sha256": "734378d788f5530cfb1f00883a211b674ccc9c67cceec2f527d620c22667e1cf"
},
"downloads": -1,
"filename": "click_complete-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "3d5326de07e0bb3cc10c26f6fed3b067",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10875,
"upload_time": "2025-02-12T05:12:03",
"upload_time_iso_8601": "2025-02-12T05:12:03.933405Z",
"url": "https://files.pythonhosted.org/packages/9c/be/f465ee0dddcf9d55f872e4b465823c533ae5a911d127aac97555678bb066/click_complete-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 05:12:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xMohnad",
"github_project": "click-complete",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"3.7.4.3"
]
]
},
{
"name": "shellingham",
"specs": [
[
">=",
"1.3.0"
]
]
}
],
"lcname": "click-complete"
}
JSON
