refactor(enums): add VariableSource for variables source field

Replace bare "dap"/"fallback" strings in variables.py with a
VariableSource(str, Enum), following the existing class X(str, Enum)
pattern. Update human-output f-strings in vars_cmd.py to use .value,
and sync tests to use the enum members explicitly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: TTTPOB

jupyter_jcli/commands/vars_cmd.py

@@ -59,8 +59,8 @@ def vars_cmd(ctx: Context, session_id: str, name: str | None, rich: bool, timeou
     Source
     ------
     When the kernel advertises debugger support the DAP inspectVariables
-    command is used (source="dap").  Otherwise a shell-channel code snippet
-    is executed as a fallback (source="fallback").
+    command is used (source=VariableSource.DAP).  Otherwise a shell-channel
+    code snippet is executed as a fallback (source=VariableSource.FALLBACK).
     """
     if rich and not name:
         emit_error("PARSE_ERROR", "--rich requires --name", ctx.use_json)
@@ -122,7 +122,7 @@ def _emit_list(ctx: Context, result: dict, session_id: str) -> None:
         return
 
     if not variables:
-        emit({"_human": f"No variables found (source: {source})"}, use_json=False)
+        emit({"_human": f"No variables found (source: {source.value})"}, use_json=False)
         return
 
     lines = [f"{'NAME':<24} {'TYPE':<20} {'VALUE':<40}"]
@@ -137,7 +137,7 @@ def _emit_list(ctx: Context, result: dict, session_id: str) -> None:
         lines.append(f"{name:<24} {typ:<20} {value:<40}")
 
     lines.append("")
-    lines.append(f"source: {source}  |  {len(variables)} variable(s)")
+    lines.append(f"source: {source.value}  |  {len(variables)} variable(s)")
     lines.append(f"hint: {_ORDERING_NOTE}")
     emit({"_human": "\n".join(lines)}, use_json=False)
 
@@ -151,7 +151,7 @@ def _emit_single(ctx: Context, result: dict, session_id: str) -> None:
         f"name:  {str(result['name'])}",
         f"type:  {str(result['type'])}",
         f"value: {str(result['value'])}",
-        f"source: {result['source']}",
+        f"source: {result['source'].value}",
     ]
     if "data" in result:
         mimetypes = list(result["data"].keys())

jupyter_jcli/variables.py

@@ -4,6 +4,17 @@
 
 import itertools
 import typing as t
+from enum import Enum
+
+
+class VariableSource(str, Enum):
+    """Which mechanism supplied the variable metadata.
+
+    Used for human-readable display only; not dispatched on.
+    """
+
+    DAP = "dap"
+    FALLBACK = "fallback"
 
 
 class VariablesUnavailable(Exception):
@@ -131,7 +142,7 @@ def list_variables(kernel, *, timeout: float = 5.0) -> dict[str, t.Any]:
     Returns:
         Dict with keys:
           - "variables": list of {"name", "type", "value", "variables_reference"}
-          - "source": "dap" or "fallback"
+          - "source": VariableSource (DAP or FALLBACK)
 
     Raises:
         VariablesUnavailable: if neither path succeeds.
@@ -151,14 +162,14 @@ def list_variables(kernel, *, timeout: float = 5.0) -> dict[str, t.Any]:
             wsc = kernel._manager.client
             raw = _dap_inspect_variables(wsc, timeout=timeout)
             variables = [_normalise_dap_variable(v) for v in raw]
-            return {"variables": variables, "source": "dap"}
+            return {"variables": variables, "source": VariableSource.DAP}
         except Exception:
             pass  # fall through to fallback
 
     # Shell-channel fallback
     try:
         variables = _fallback_list_variables(kernel)
-        return {"variables": variables, "source": "fallback"}
+        return {"variables": variables, "source": VariableSource.FALLBACK}
     except ValueError as e:
         raise VariablesUnavailable(str(e)) from e
     except Exception as e:
@@ -184,7 +195,7 @@ def inspect_variable(
     Returns:
         Dict with keys:
           - "name", "type", "value", "variables_reference"
-          - "source": "dap" or "fallback"
+          - "source": VariableSource (DAP or FALLBACK)
           - "data", "metadata" (only when rich=True and DAP succeeds)
 
     Raises:
@@ -206,7 +217,7 @@ def inspect_variable(
                 }
                 result["data"] = body.get("data", {})
                 result["metadata"] = body.get("metadata", {})
-                result["source"] = "dap"
+                result["source"] = VariableSource.DAP
                 return result
             else:
                 raw_all = _dap_inspect_variables(wsc, timeout=timeout)
@@ -218,7 +229,7 @@ def inspect_variable(
                         f"Variable '{name}' not found in kernel namespace"
                     )
                 result = _normalise_dap_variable(match)
-                result["source"] = "dap"
+                result["source"] = VariableSource.DAP
                 return result
         except VariablesUnavailable:
             raise
@@ -233,7 +244,7 @@ def inspect_variable(
             raise VariablesUnavailable(
                 f"Variable '{name}' not found in kernel namespace"
             )
-        match["source"] = "fallback"
+        match["source"] = VariableSource.FALLBACK
         return match
     except VariablesUnavailable:
         raise

tests/test_variables.py

@@ -6,6 +6,7 @@
 
 from jupyter_jcli.variables import (
     VariablesUnavailable,
+    VariableSource,
     _fallback_list_variables,
     list_variables,
     inspect_variable,
@@ -48,7 +49,7 @@ def test_returns_dict_shape(self, live_kernel):
 
         assert "variables" in result
         assert "source" in result
-        assert result["source"] in ("dap", "fallback")
+        assert result["source"] in (VariableSource.DAP, VariableSource.FALLBACK)
         assert isinstance(result["variables"], list)
 
     def test_user_variables_present(self, live_kernel):
@@ -83,14 +84,24 @@ def test_inspect_known_variable(self, live_kernel):
 
         assert result["name"] == "_ti_x"
         assert "42" in result["value"]
-        assert result["source"] in ("dap", "fallback")
+        assert result["source"] in (VariableSource.DAP, VariableSource.FALLBACK)
 
     def test_inspect_missing_variable_raises(self, live_kernel):
         live_kernel.execute("_warmup = 1", timeout=30)
         with pytest.raises(VariablesUnavailable):
             inspect_variable(live_kernel, "__no_such_var__", timeout=15.0)
 
 
+class TestVariableSourceEnum:
+    """Unit tests — VariableSource enum value stability."""
+
+    def test_dap_value_equals_string(self):
+        assert VariableSource.DAP == "dap"
+
+    def test_fallback_round_trips(self):
+        assert VariableSource("fallback") is VariableSource.FALLBACK
+
+
 class TestListVariableValueFields:
     """Integration regression — list_variables always returns string fields."""
 

tests/test_vars_cmd.py

@@ -8,6 +8,7 @@
 
 from jupyter_jcli.cli import main
 from jupyter_jcli.commands.vars_cmd import _emit_list
+from jupyter_jcli.variables import VariableSource
 
 
 def _create_session(runner, url, token):
@@ -36,7 +37,7 @@ def test_json_output_shape(self, live_session, mock_kernel_connection):
         data = json.loads(result.output)
         assert "variables" in data
         assert "source" in data
-        assert data["source"] in ("dap", "fallback")
+        assert data["source"] in (VariableSource.DAP.value, VariableSource.FALLBACK.value)
 
     def test_user_variables_in_output(self, live_session, mock_kernel_connection):
         runner = CliRunner()
@@ -79,7 +80,7 @@ def test_inspect_single_variable_json(self, live_session, mock_kernel_connection
         data = json.loads(result.output)
         assert data["name"] == "_vs_x"
         assert "42" in data["value"]
-        assert data["source"] in ("dap", "fallback")
+        assert data["source"] in (VariableSource.DAP.value, VariableSource.FALLBACK.value)
 
     def test_inspect_missing_variable_exits_1(self, live_session, mock_kernel_connection):
         runner = CliRunner()
@@ -119,7 +120,7 @@ def test_emit_list_does_not_crash_on_list_value(self):
         ctx = Context(server_url="http://localhost:8888", token=None, use_json=False)
         result = {
             "variables": [{"name": "lst", "type": "list", "value": [1, 2, 3]}],
-            "source": "fallback",
+            "source": VariableSource.FALLBACK,
         }
         _emit_list(ctx, result, "fake-session-id")
 
@@ -130,7 +131,7 @@ def test_emit_list_output_contains_variable_name(self):
         ctx = Context(server_url="http://localhost:8888", token=None, use_json=False)
         result = {
             "variables": [{"name": "my_list", "type": "list", "value": [1, 2, 3]}],
-            "source": "fallback",
+            "source": VariableSource.FALLBACK,
         }
         with CliRunner().isolated_filesystem():
             runner = CliRunner()
@@ -151,7 +152,7 @@ def test_emit_list_no_connection_failed_on_bad_value(self):
         ctx = Context(server_url="http://localhost:8888", token=None, use_json=False)
         result = {
             "variables": [{"name": "x", "type": "int", "value": 99}],
-            "source": "fallback",
+            "source": VariableSource.FALLBACK,
         }
         _emit_list(ctx, result, "fake-session-id")