Help string support for fish

README.rst

@@ -282,6 +282,16 @@ or create new completion file, e.g::
 
     register-python-argcomplete --shell fish ~/.config/fish/completions/my-awesome-script.fish
 
+Completion Description For Fish
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+By default help string is added as completion description.
+
+.. image:: docs/fish_help_string.png
+
+You can disable this feature by removing ``_ARGCOMPLETE_DFS`` variable, e.g::
+
+    register-python-argcomplete --shell fish my-awesome-script | grep -v _ARGCOMPLETE_DFS | .
+
 Python Support
 --------------
 Argcomplete requires Python 2.7 or 3.5+.

argcomplete/__init__.py

@@ -199,6 +199,11 @@ def __call__(self, argument_parser, always_complete_options=True, exit_method=os
             debug("Invalid value for IFS, quitting [{v}]".format(v=ifs))
             exit_method(1)
 
+        dfs = os.environ.get("_ARGCOMPLETE_DFS")
+        if dfs and len(dfs) != 1:
+            debug("Invalid value for DFS, quitting [{v}]".format(v=dfs))
+            exit_method(1)
+
         comp_line = os.environ["COMP_LINE"]
         comp_point = int(os.environ["COMP_POINT"])
 
@@ -226,6 +231,12 @@ def __call__(self, argument_parser, always_complete_options=True, exit_method=os
 
         completions = self._get_completions(comp_words, cword_prefix, cword_prequote, last_wordbreak_pos)
 
+        if dfs:
+            display_completions = {key_part: value.replace(ifs, " ") if value else ""
+                                   for key, value in self.get_display_completions().items()
+                                   for key_part in key.split(" ")}
+            completions = [dfs.join((key, display_completions.get(key) or "")) for key in completions]
+
         debug("\nReturning completions:", completions)
         output_stream.write(ifs.join(completions).encode(sys_encoding))
         output_stream.flush()

argcomplete/shell_integration.py

@@ -46,6 +46,7 @@
 fishcode = r'''
 function __fish_%(executable)s_complete
     set -x _ARGCOMPLETE 1
+    set -x _ARGCOMPLETE_DFS \t
     set -x _ARGCOMPLETE_IFS \n
     set -x _ARGCOMPLETE_SUPPRESS_SPACE 1
     set -x _ARGCOMPLETE_SHELL fish

test/prog

@@ -31,12 +31,12 @@ def get_comp_point(*args, **kwargs):
 
 parser = argparse.ArgumentParser()
 subparsers = parser.add_subparsers()
-subparsers.add_parser('basic').add_argument('arg', choices=['foo', 'bar', 'baz'])
+subparsers.add_parser('basic', help='basic help\nnext line of help').add_argument('arg', choices=['foo', 'bar', 'baz'])
 subparsers.add_parser('space').add_argument('arg', choices=['foo bar', 'baz'])
 subparsers.add_parser('cont').add_argument('arg').completer = complete_cont
 subparsers.add_parser('spec').add_argument('arg', choices=['d$e$f', 'd$e$g', 'x!x', r'y\y'])
 subparsers.add_parser('quote').add_argument('arg', choices=["1'1", '2"2'])
-subparsers.add_parser('break').add_argument('arg', choices=['a:b:c', 'a:b:d'])
+subparsers.add_parser('break', help="break help").add_argument('arg', choices=['a:b:c', 'a:b:d'])
 subparsers.add_parser('env').add_argument('arg').completer = check_environ
 subparsers.add_parser('debug').add_argument('arg').completer = print_output
 subparsers.add_parser('point', add_help=False).add_argument('arg', nargs='*').completer = get_comp_point

test/test.py

@@ -74,8 +74,10 @@ def run_completer(self, parser, command, point=None, completer=autocomplete, **k
         with TemporaryFile() as t:
             os.environ["COMP_LINE"] = ensure_bytes(command) if USING_PYTHON2 else command
             os.environ["COMP_POINT"] = point
-            self.assertRaises(SystemExit, completer, parser, output_stream=t,
-                              exit_method=sys.exit, **kwargs)
+            with self.assertRaises(SystemExit) as cm:
+                completer(parser, output_stream=t, exit_method=sys.exit, **kwargs)
+            if cm.exception.code != 0:
+                raise Exception("Unexpected exit code %d" % cm.exception.code)
             t.seek(0)
             return t.read().decode(sys_encoding).split(IFS)
 
@@ -757,6 +759,24 @@ def test_shellcode_utility(self):
         sc = shellcode(["prog"], use_defaults=False, shell="woosh", complete_arguments=["-o", "nospace"])
         sc = shellcode(["prog"], shell="fish")
 
+    def test_option_help(self):
+        os.environ["_ARGCOMPLETE_DFS"] = "\t"
+        os.environ["_ARGCOMPLETE_SUPPRESS_SPACE"] = "1"
+        os.environ["_ARGCOMPLETE_SHELL"] = "fish"
+
+        p = ArgumentParser()
+        p.add_argument("--foo", help="foo" + IFS + "help")
+        p.add_argument("--bar", "--bar2", help="bar help")
+
+        completions = self.run_completer(p, "prog --f")
+        self.assertEqual(set(completions), set(["--foo\tfoo help"]))
+
+        completions = self.run_completer(p, "prog --b")
+        self.assertEqual(set(completions), set(["--bar\tbar help", "--bar2\tbar help"]))
+
+        os.environ["_ARGCOMPLETE_DFS"] = "invalid"
+        self.assertRaises(Exception, self.run_completer, p, "prog --b")
+
 class TestArgcompleteREPL(unittest.TestCase):
     def setUp(self):
         pass