add argcomplete support

README.md

@@ -15,14 +15,17 @@ Features:
 - 𝕡𝕣𝕖𝕥𝕥𝕪 𝕡𝕣𝕚𝕟𝕥𝕚𝕟𝕘
 - support for argparse actions
 - auto shortcuts generation: `--verbose -> -v, --foo_bar -> --fb`
+- auto completion in shell (with [argcomplete](https://argcomplete.readthedocs.io/en/latest/))
 
 ------
 
 ## install
 
 ```text
 pip install argser
-pip install argser tabulate  # for fancy table support
+pip install argser[tabulate]  # for fancy tables support
+pip install argser[argcomplete]  # for shell auto completion
+pip install argser[all]
 ```
 
 ## [docs](https://argser.readthedocs.io/en/latest/)

argser/fields.py

@@ -17,6 +17,8 @@ def __init__(
         help=None,
         metavar=None,
         action='store',
+        # argcomplete
+        completer=None,
         # extra
         bool_flag=True,
         one_dash=False,
@@ -43,6 +45,8 @@ def __init__(
         self.help = help
         self._metavar = metavar
         self.action = action
+        # argcomplete
+        self.completer = completer
         # extra
         self.bool_flag = bool_flag
         self.one_dash = one_dash
@@ -96,22 +100,26 @@ def inject_bool(self, parser: ArgumentParser):
             params['help'] = IGNORE
             parser.add_argument(*self.names(prefix='no-'), action='store_false', **params)
             parser.set_defaults(**{self.dest: self.default})
-        else:
-            params = self.params(type=str2bool)
-            parser.add_argument(*self.names(), **params)
+            return action
+        params = self.params(type=str2bool)
+        return parser.add_argument(*self.names(), **params)
 
     def inject(self, parser: ArgumentParser):
         if self.type is bool:
-            return self.inject_bool(parser)
-        params = self.params()
-        action = params.get('action')
-        if action in (
-            'store_const', 'store_true', 'store_false', 'append_const', 'version', 'count'
-        ) and 'type' in params:
-            params.pop('type')
-        if action in ('store_true', 'store_false', 'count', 'version') and 'metavar' in params:
-            params.pop('metavar')
-        parser.add_argument(*self.names(), **params)
+            action = self.inject_bool(parser)
+        else:
+            params = self.params()
+            action = params.get('action')
+            if action in (
+                'store_const', 'store_true', 'store_false', 'append_const', 'version', 'count'
+            ) and 'type' in params:
+                params.pop('type')
+            if action in ('store_true', 'store_false', 'count', 'version') and 'metavar' in params:
+                params.pop('metavar')
+            action = parser.add_argument(*self.names(), **params)
+        if callable(self.completer):
+            action.completer = self.completer
+        return action
 
 
 class PosArg(Arg):

argser/parser.py

@@ -185,6 +185,14 @@ def _add_prefixed_key(source: dict, target: dict, prefix: str):
             target[m[1]] = value
 
 
+def _setup_argcomplete(parser, **kwargs):
+    try:
+        import argcomplete
+        argcomplete.autocomplete(parser, **kwargs)
+    except ImportError:
+        logger.log(VERBOSE, "argcomplete is not installed")
+
+
 def parse_args(
     args_cls: Type[Args],
     args=None,
@@ -197,6 +205,7 @@ def parse_args(
     override=False,
     parser_kwargs=None,
     tabulate_kwargs=None,
+    argcomplete_kwargs=None,
     **kwargs,
 ) -> Args:
     """
@@ -220,12 +229,15 @@ def parse_args(
         cols: number of columns. Can be 'auto' - len(args)/N, int - just number of columns,
         'sub' / 'sub-auto' / 'sub-INT' - split by sub-commands,
         gap: string, space between tables/columns
+    :param argcomplete_kwargs: argcomplete kwargs
     :param kwargs: params for tabulate and parser - tabulate_ARG=VAL or parser_ARG=VAL
     """
     tabulate_kwargs = tabulate_kwargs or {}
     _add_prefixed_key(kwargs, tabulate_kwargs, 'tabulate_')
     parser_kwargs = parser_kwargs or {}
     _add_prefixed_key(kwargs, parser_kwargs, 'parser_')
+    argcomplete_kwargs = argcomplete_kwargs or {}
+    _add_prefixed_key(kwargs, argcomplete_kwargs, 'argcomplete_')
 
     if isinstance(args, str):
         args_to_parse = shlex.split(args)
@@ -236,15 +248,14 @@ def parse_args(
         args_cls,
         override=override,
         bool_flag=bool_flag,
-        help_format=help_format,
-        keep_default_help=keep_default_help,
         one_dash=one_dash,
     )
     if make_shortcuts:
         _make_shortcuts_sub_wise(args, sub_commands)
     if help_color:
         parser_kwargs.setdefault('formatter_class', ColoredHelpFormatter)
     parser = _make_parser('root', args, sub_commands, **parser_kwargs)
+    _setup_argcomplete(parser, **argcomplete_kwargs)
 
     namespace = parser.parse_args(args_to_parse)
     logger.log(VERBOSE, namespace)

docs/source/conf.py

@@ -40,8 +40,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'm2r',
+    'sphinx.ext.autodoc',
     'sphinxcontrib.apidoc',
+    'm2r',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/installation.rst

@@ -4,4 +4,5 @@ Installation
 .. code-block::
 
   pip install argser
-  pip install argser tabulate  # for fancy table support
+  pip install argser[tabulate]  # for fancy table support
+  pip install argser[argcomplete]  # for shell auto completion

pyproject.toml

@@ -18,6 +18,7 @@ classifiers = [
 [tool.poetry.dependencies]
 python = "^3.6"
 tabulate = {version = "^0.8.5", optional = true}
+argcomplete = {version = "^1.10", optional = true}
 
 [tool.poetry.dev-dependencies]
 pytest = "^5.2"
@@ -29,6 +30,8 @@ m2r = "^0.2.1"
 
 [tool.poetry.extras]
 tabulate = ["tabulate"]
+argcomplete = ["argcomplete"]
+all = ["tabulate", "argcomplete"]
 
 [build-system]
 requires = ["poetry>=0.12"]