Complete environment description (#4397)

* completers: env: Add env var's description

* news: Add complete-environment-description

* completers: env: Use generator

* completers: env: Show var type in display

* tests: completers: env: Update tests

news/complete-environment-description.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Show environment variables' type and descriptions when completing them.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

tests/completers/test_environment_completer.py

@@ -1,5 +1,6 @@
 import pytest
 
+from xonsh.environ import Env, Var
 from xonsh.parsers.completion_context import CompletionContextParser
 from xonsh.completers.environment import complete_environment_vars
 
@@ -18,7 +19,19 @@ def parser():
     ),
 )
 def test_simple(cmd, xession, monkeypatch, parser):
-    monkeypatch.setitem(xession.env, "WOW", 1)
+    monkeypatch.setattr(xession, "env", Env({"WOW": 1}))
 
     context = parser.parse(cmd, len(cmd))
-    assert complete_environment_vars(context) == ({"$WOW"}, 3)
+    comps, lprefix = complete_environment_vars(context)
+    assert lprefix == 3
+    assert set(comps) == {"$WOW"}
+
+
+def test_rich_completions(xession, monkeypatch, parser):
+    monkeypatch.setattr(xession, "env", Env({"WOW": 1}))
+    xession.env.register("WOW", type=int, doc="Nice Docs!")
+
+    context = parser.parse("$WO", 3)
+    completion = next(complete_environment_vars(context)[0])
+    assert completion.display == "$WOW [int]"
+    assert completion.description == "Nice Docs!"

xonsh/completers/environment.py

@@ -4,6 +4,7 @@ from xonsh.completers.tools import (
     contextual_completer,
     non_exclusive_completer,
     get_filter_function,
+    RichCompletion,
 )
 
 
@@ -25,6 +26,14 @@ def complete_environment_vars(context: CompletionContext):
     key = prefix[dollar_location + 1 :]
     lprefix = len(key) + 1
     filter_func = get_filter_function()
-    env_names = XSH.env
+    env = XSH.env
 
-    return {"$" + k for k in env_names if filter_func(k, key)}, lprefix
+    return (
+        RichCompletion(
+            "$" + k,
+            display=f"${k} [{type(v).__name__}]",
+            description=env.get_docs(k).doc,
+        )
+        for k, v in env.items()
+        if filter_func(k, key)
+    ), lprefix