Support for shell completions

CHANGELOG.md

@@ -25,11 +25,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [tui] File name labels to image grid cells ([e64edd4]).
 - [tui] Support for terminal synchronized output ([ad059bb]).
 - [cli] `--long-help` command-line option for full help message ([d5852e6]).
+- [cli] Support for shell completions ([#4]).
+  - [argcomplete](https://github.com/kislyuk/argcomplete)>=2,<4 dependency
+  - `--completions` command-line option
 
 ### Removed
 - As much private API usage across the CLI and TUI code ([term-image#70]).
 
 [term-image#70]: https://github.com/AnonymouX47/term-image/pull/70
+[#4]: https://github.com/AnonymouX47/termvisage/pull/4
 [term-image@b4533d5]: https://github.com/AnonymouX47/term-image/commit/b4533d5697d41fe0742c2ac895077da3b8d889dc
 [term-image@8b0af4c]: https://github.com/AnonymouX47/term-image/pull/70/commits/8b0af4cd76c96187b95237e7bcd74ab5b16b2c82
 [1637a38]: https://github.com/AnonymouX47/termvisage/commit/1637a388affef84735805ac105b995cb2f25c005

requirements.txt

@@ -1,3 +1,4 @@
+argcomplete==3.0.8
 black==22.12.0
 flake8==5.0.4
 isort[colors]==5.12.0;python_version>="3.8"

setup.py

@@ -34,7 +34,7 @@
     license="MIT",
     classifiers=classifiers,
     python_requires=">=3.7",
-    install_requires=["term-image>=0.6,<0.7", "urwid>=2.1,<3.0"],
+    install_requires=["argcomplete>=2,<4", "term-image>=0.6,<0.7", "urwid>=2.1,<3.0"],
     entry_points={
         "console_scripts": ["termvisage=termvisage.__main__:main"],
     },

src/termvisage/__main__.py

@@ -14,6 +14,12 @@
 
 def main() -> int:
     """CLI execution entry-point"""
+    from argcomplete import autocomplete
+
+    from .parsers import parser
+
+    autocomplete(parser)
+
     from . import cli, logging, notify
     from .tui import main
 

src/termvisage/parsers.py

@@ -15,12 +15,56 @@
 from . import cli  # noqa: F401; prevents circular import of `.config` (below)
 from . import __version__
 
+COMPLETIONS = """First, if `termvisage` was installed using `pipx`,
+run the following (outside any virtual environment):
+
+    pip install --user --upgrade argcomplete
+
+Then, follow the appropriate instructions for your shell:
+
+NOTE: If you add a command to your shell's config file, you will likely
+have to restart the shell or re-login for autocompletion to start working.
+
+Bash or Zsh:
+    Add the following to your shell's config file:
+
+        eval "$(register-python-argcomplete termvisage)"
+
+Tcsh:
+    Add the following to your shell's config file:
+
+        eval "$(register-python-argcomplete --shell tcsh termvisage)"
+
+Fish:
+    Run the following once to create new completion file:
+
+        register-python-argcomplete --shell fish termvisage \
+> ~/.config/fish/completions/termvisage.fish
+
+    OR add the following to your shell's config file:
+
+        register-python-argcomplete --shell fish termvisage | source
+
+Git Bash:
+    Add the following to your shell's config file:
+
+        export ARGCOMPLETE_USE_TEMPFILES=1
+        eval "$(register-python-argcomplete termvisage)"
+
+For other shells, see https://github.com/kislyuk/argcomplete/tree/develop/contrib
+"""
+
 
 class BasicHelpAction(Action):
     def __call__(self, *args):
         basic_parser.parse_args(["--help"])
 
 
+class CompletionsAction(Action):
+    def __call__(self, parser, *args):
+        parser.exit(message=COMPLETIONS)
+
+
 def rst_role_repl(match):
     if match.group(1) in {"option", "confval"}:
         return f"`{match.group(2)}`"
@@ -87,6 +131,12 @@ def strip_markup(string: str) -> str:
     version=__version__,
     help="Show the program version and exit",
 )
+basic_parser.add_argument(
+    "--completions",
+    nargs=0,
+    action=CompletionsAction,
+    help="Show instructions to enable shell completions and exit",
+)
 basic_parser.add_argument(
     "-S",
     "--style",
@@ -180,6 +230,12 @@ def strip_markup(string: str) -> str:
     version=__version__,
     help="Show the program version and exit",
 )
+general.add_argument(
+    "--completions",
+    nargs=0,
+    action=CompletionsAction,
+    help="Show instructions to enable shell completions and exit",
+)
 general.add_argument(
     "--query-timeout",
     type=float,