Uploaded example.

Author: ggirelli

README.md

@@ -1 +1,42 @@
-# python-click-autocomplete-example
+# python-click-autocomplete-example
+
+This is an example on how to setup shell autocompletion in your python scripts reading input via [click](https://github.com/pallets/click/), especially when working on a Python package using [Poetry](https://github.com/python-poetry/poetry).
+
+## Requirements
+
+To test this example you will need:
+
+* **Python v3.8+**
+* **Poetry**
+
+## Usage
+
+Set up the environment with:
+
+```bash
+git clone https://github.com/ggirelli/python-click-autocomplete-example.git
+cd python-click-autocomplete-example
+poetry install
+poetry shell
+```
+
+This example package provides you with two scripts:
+
+* `clicko` is a placeholder mimicking a normal script with subcommands and commands.
+* `clicko-autocomplete` can be used to enable autocompletion for the `clicko` script.
+
+Currently, autocompletion is supported for `bash`, `fish`, and `zsh`. To activate it, simply run:
+
+```bash
+clicko-autocomplete -s SHELL_TYPE
+```
+
+The default `SHELL_TYPE` is `bash`.
+
+Now, you should be able to test autocompletion by typing `clicko <TAB> <TAB>`.
+
+## How does it work
+
+The `clicko-autocomplete` script is able to generate and install shell autocompletion configuration files, stored by default in the `autocomplete` subfolder of this package. This is done by exploiting the in-built autocompletion tools served by `click`.
+
+To read more on autocompletion with `click`, check out [their documentation](https://click.palletsprojects.com/en/8.0.x/shell-completion/).

clickomplete/__init__.py

@@ -0,0 +1,15 @@
+"""
+@author: Gabriele Girelli
+@contact: gigi.ga90@gmail.com
+"""
+
+from importlib.metadata import version
+from typing import List
+
+try:
+    __version__ = version(__name__)
+except Exception as e:
+    raise e
+
+__all__ = ["__version__"]
+__path__: List[str]

clickomplete/autocomplete/.clicko-complete.bash

@@ -0,0 +1,29 @@
+_clicko_completion() {
+    local IFS=$'\n'
+    local response
+
+    response=$(env COMP_WORDS="${COMP_WORDS[*]}" COMP_CWORD=$COMP_CWORD _CLICKO_COMPLETE=bash_complete $1)
+
+    for completion in $response; do
+        IFS=',' read type value <<< "$completion"
+
+        if [[ $type == 'dir' ]]; then
+            COMREPLY=()
+            compopt -o dirnames
+        elif [[ $type == 'file' ]]; then
+            COMREPLY=()
+            compopt -o default
+        elif [[ $type == 'plain' ]]; then
+            COMPREPLY+=($value)
+        fi
+    done
+
+    return 0
+}
+
+_clicko_completion_setup() {
+    complete -o nosort -F _clicko_completion clicko
+}
+
+_clicko_completion_setup;
+

clickomplete/autocomplete/.clicko-complete.fish

@@ -0,0 +1,22 @@
+function _clicko_completion;
+    set -l response;
+
+    for value in (env _CLICKO_COMPLETE=fish_complete COMP_WORDS=(commandline -cp) COMP_CWORD=(commandline -t) clicko);
+        set response $response $value;
+    end;
+
+    for completion in $response;
+        set -l metadata (string split "," $completion);
+
+        if test $metadata[1] = "dir";
+            __fish_complete_directories $metadata[2];
+        else if test $metadata[1] = "file";
+            __fish_complete_path $metadata[2];
+        else if test $metadata[1] = "plain";
+            echo $metadata[2];
+        end;
+    end;
+end;
+
+complete --no-files --command clicko --arguments "(_clicko_completion)";
+

clickomplete/autocomplete/.clicko-complete.zsh

@@ -0,0 +1,35 @@
+#compdef clicko
+
+_clicko_completion() {
+    local -a completions
+    local -a completions_with_descriptions
+    local -a response
+    (( ! $+commands[clicko] )) && return 1
+
+    response=("${(@f)$(env COMP_WORDS="${words[*]}" COMP_CWORD=$((CURRENT-1)) _CLICKO_COMPLETE=zsh_complete clicko)}")
+
+    for type key descr in ${response}; do
+        if [[ "$type" == "plain" ]]; then
+            if [[ "$descr" == "_" ]]; then
+                completions+=("$key")
+            else
+                completions_with_descriptions+=("$key":"$descr")
+            fi
+        elif [[ "$type" == "dir" ]]; then
+            _path_files -/
+        elif [[ "$type" == "file" ]]; then
+            _path_files -f
+        fi
+    done
+
+    if [ -n "$completions_with_descriptions" ]; then
+        _describe -V unsorted completions_with_descriptions -U
+    fi
+
+    if [ -n "$completions" ]; then
+        compadd -U -V unsorted -a completions
+    fi
+}
+
+compdef _clicko_completion clicko;
+

clickomplete/const.py

@@ -0,0 +1,6 @@
+"""
+@author: Gabriele Girelli
+@contact: gigi.ga90@gmail.com
+"""
+
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])

clickomplete/scripts/__init__.py

@@ -0,0 +1,20 @@
+"""
+@author: Gabriele Girelli
+@contact: gigi.ga90@gmail.com
+"""
+
+from clickomplete.scripts import autocomplete, clicko
+
+import logging
+from rich.logging import RichHandler  # type: ignore
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(message)s",
+    handlers=[RichHandler(markup=True, rich_tracebacks=True)],
+)
+
+__all__ = [
+    "autocomplete",
+    "clicko",
+]

clickomplete/scripts/autocomplete.py

@@ -0,0 +1,84 @@
+"""
+@author: Gabriele Girelli
+@contact: gigi.ga90@gmail.com
+"""
+
+import click  # type: ignore
+import os
+from rich import print  # type: ignore
+from shutil import copyfile
+import sys
+
+from clickomplete import __path__, __version__
+from clickomplete.const import CONTEXT_SETTINGS
+
+
+@click.command(context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "--shell-type",
+    "-s",
+    help="shell type for which to activate autocompletion",
+    type=click.Choice(["bash", "zsh", "fish"], case_sensitive=False),
+    default="bash",
+    show_default=True,
+)
+@click.option(
+    "--regenerate",
+    help="to regenerate autocompletion file, mainly for developers",
+    type=click.BOOL,
+    default=False,
+    is_flag=True,
+)
+@click.version_option(__version__)
+def main(shell_type: str, regenerate: bool) -> None:
+    user_home_path = os.path.expanduser("~")
+    autocomplete_path = os.path.join(
+        __path__[0], "autocomplete", f".clicko-complete.{shell_type}"
+    )
+
+    if regenerate:
+        regenerate_autocompletion_files(shell_type, autocomplete_path)
+
+    if shell_type in ("bash", "zsh"):
+        autocomplete_bash_or_zsh(user_home_path, autocomplete_path, shell_type)
+    elif "fish" == shell_type:
+        autocomplete_fish(user_home_path, autocomplete_path)
+
+    print("Done. :thumbs_up: :smiley:")
+
+
+def regenerate_autocompletion_files(shell_type: str, autocomplete_path: str) -> None:
+    os.system(f"_CLICKO_COMPLETE={shell_type}_source clicko > {autocomplete_path}")
+    print(f"Regenerated {shell_type} completion file: {autocomplete_path}")
+
+
+def autocomplete_fish(user_home_path: str, autocomplete_path: str) -> None:
+    destination_path = os.path.join(
+        user_home_path, ".config/fish/completions/clicko.fish"
+    )
+
+    if os.path.isfile(destination_path):
+        print("Autocompletion was previously set up. Skipping.")
+        sys.exit()
+
+    copyfile(
+        autocomplete_path,
+        destination_path,
+    )
+
+
+def autocomplete_bash_or_zsh(
+    user_home_path: str, autocomplete_path: str, shell_type: str = "bash"
+) -> None:
+    assert shell_type in ("bash", "zsh")
+
+    autocompletion_string = f". {autocomplete_path} # CLICKO-AUTOCOMPLETE\n"
+    run_command_path = os.path.join(user_home_path, f".{shell_type}rc")
+
+    with open(run_command_path, "r") as OH:
+        if autocompletion_string in OH.readlines():
+            print("Autocompletion was previously set up. Skipping.")
+            sys.exit()
+
+    with open(run_command_path, "a+") as OH:
+        OH.write(f"\n{autocompletion_string}")

clickomplete/scripts/clicko.py

@@ -0,0 +1,78 @@
+"""
+@author: Gabriele Girelli
+@contact: gigi.ga90@gmail.com
+"""
+
+import click  # type: ignore
+from clickomplete import __version__
+from clickomplete.const import CONTEXT_SETTINGS
+import webbrowser
+import sys
+
+
+@click.group(
+    name="radiant",
+    context_settings=CONTEXT_SETTINGS,
+    help=f"""\b
+Version:    {__version__}
+Author:     Gabriele Girelli
+Docs:       http://github.com/python-click-autocomplete-example
+Code:       http://github.com/ggirelli/python-click-autocomplete-example
+
+Radial Image Analisys Toolkit (RadIAnTkit) is a Python3.6+ package containing
+tools for radial analysis of microscopy image.""",
+)
+@click.version_option(__version__)
+def main() -> None:
+    pass
+
+
+@click.command(
+    "_docs",
+    help="Open online documentation on your favorite browser.",
+)
+def open_documentation() -> None:
+    webbrowser.open("https://github.com/python-click-autocomplete-example/")
+    sys.exit()
+
+
+@click.command(
+    "command_1",
+    help="Does something.",
+)
+def command_1():
+    pass
+
+
+@click.command(
+    "command_2",
+    help="Does something else.",
+)
+def command_2():
+    pass
+
+
+main.add_command(open_documentation)
+main.add_command(command_1)
+main.add_command(command_2)
+
+
+@click.group(
+    name="subgroup_1",
+    context_settings=CONTEXT_SETTINGS,
+    help="Groups some sub-commands.",
+)
+def subgroup_1():
+    pass
+
+
+@click.command(
+    "command_1",
+    help="Does something new.",
+)
+def subgroup_1_command_1():
+    pass
+
+
+subgroup_1.add_command(subgroup_1_command_1)
+main.add_command(subgroup_1)