click-complete


Nameclick-complete JSON
Version 0.1.0 PyPI version JSON
download
home_pagehttps://github.com/xMohnad/click-complete
SummaryGenerate shell completion scripts for Click apps.
upload_time2025-02-12 05:12:03
maintainerNone
docs_urlNone
authorxMohnad
requires_python>=3.7
licenseMIT
keywords click shell auto-complete automation
VCS
bugtrack_url
requirements click typing-extensions shellingham
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # `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"
}
        
Elapsed time: 0.56737s