Merge pull request #700 from insanum/argcomplete

feat: Support shell completion using argcomplete

docs/README.md

@@ -22,11 +22,12 @@ Requirements
 * [httplib2](https://github.com/httplib2/httplib2)
 * [Google OAuth Library](https://github.com/googleapis/google-auth-library-python-oauthlib)
 * [parsedatetime](https://github.com/bear/parsedatetime)
+* [argcomplete](https://kislyuk.github.io/argcomplete)
 * A love for the command line!
 
 ### Optional packages
 
-* [vobject](http://vobject.skyhouseconsulting.com) Python module
+* [vobject](https://py-vobject.github.io/) Python module
   Used for ics/vcal importing.
 
 Installation
@@ -98,6 +99,7 @@ Features
  * work against specific calendars (by calendar name w/ regex)
  * flag file support for specifying option defaults
  * colored output and unicode character support
+ * custom shell completion for bash, zsh, fish, etc
  * super fun hacking with shell scripts, cron, screen, tmux, conky, etc
 
 Screenshots
@@ -165,6 +167,22 @@ authentication process will proceed. Simply follow the instructions.
    In most shells, putting a space before the command will keep it, and therefore your secrets, out of history. Check with `history | tail`.
 7. This should automatically open the OAuth2 authorization screen in your default browser.
 
+#### Shell completion
+
+gcalcli provides command completion you can configure in bash, zsh, fish, etc using the [https://kislyuk.github.io/argcomplete/] library.
+
+To enable it, follow argcomplete's setup instructions to ensure your shell can find the completion hooks.
+
+```shell
+gcalcli <TAB>
+add
+agenda
+agendaupdate
+...
+```
+
+NOTE: Setup for fish and other shells is currently explained [under "contrib"](https://github.com/kislyuk/argcomplete/tree/develop/contrib) instead of their main docs, and their centralized "global activation" mechanism doesn't seem to be supported yet for those shells.
+
 #### HTTP Proxy Support
 
 gcalcli will automatically work with an HTTP Proxy simply by setting up some

gcalcli/argparsers.py

@@ -4,8 +4,10 @@
 import copy as _copy
 import datetime
 import locale
-from shutil import get_terminal_size
 import sys
+from shutil import get_terminal_size
+
+import argcomplete  # type: ignore
 
 import gcalcli
 
@@ -432,4 +434,7 @@ def get_argument_parser():
             '--use_reminders', action=DeprecatedStoreTrue,
             help=argparse.SUPPRESS)
 
+    # Enrich with argcomplete options.
+    argcomplete.autocomplete(parser)
+
     return parser

gcalcli/cli.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# PYTHON_ARGCOMPLETE_OK
 #
 # ######################################################################### #
 #                                                                           #

pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
   "httplib2",
   "google_auth_oauthlib",
   "parsedatetime",
+  "argcomplete",
 ]
 
 [project.urls]