issue #3182: replace deprecated ptvsd debugger by debugpy

aries_cloudagent/__main__.py

@@ -20,16 +20,16 @@ def init_debug(args):
 
     # --debug to use microsoft's visual studio remote debugger
     if ENABLE_PTVSD or "--debug" in args:
+        DAP_HOST = os.getenv("PTVSD_HOST", None) or os.getenv("DAP_HOST", "localhost")
+        DAP_PORT = os.getenv("PTVSD_PORT", None) or os.getenv("DAP_PORT", 5678)
         try:
-            import ptvsd
+            import debugpy
 
-            ptvsd.enable_attach()
-            print("ptvsd is running")
-            print("=== Waiting for debugger to attach ===")
-            # To pause execution until the debugger is attached:
-            ptvsd.wait_for_attach()
+            debugpy.listen((DAP_HOST, DAP_PORT))
+            print(f"=== Waiting for debugger to attach to {DAP_HOST}:{DAP_PORT} ===")
+            debugpy.wait_for_client()
         except ImportError:
-            print("ptvsd library was not found")
+            print("debugpy library was not found")
 
     if ENABLE_PYDEVD_PYCHARM or "--debug-pycharm" in args:
         try:

aries_cloudagent/config/argparse.py

@@ -214,11 +214,11 @@ def get_settings(self, args: Namespace):
         return settings
 
 
-@group(CAT_START)
-class DebugGroup(ArgumentGroup):
-    """Debug settings."""
+@group(CAT_PROVISION, CAT_START, CAT_UPGRADE)
+class DebuggerGroup(ArgumentGroup):
+    """Debugger settings."""
 
-    GROUP_NAME = "Debug"
+    GROUP_NAME = "Debugger"
 
     def add_arguments(self, parser: ArgumentParser):
         """Add debug command line arguments to the parser."""
@@ -228,10 +228,28 @@ def add_arguments(self, parser: ArgumentParser):
             env_var="ACAPY_DEBUG",
             help=(
                 "Enables a remote debugging service that can be accessed "
-                "using ptvsd for Visual Studio Code. The framework will wait "
-                "for the debugger to connect at start-up. Default: false."
+                "using the Debug Adapter Protocol (supported by Visual Studio Code). "
+                "The framework will wait for the debugger to connect at start-up. "
+                "Default: false."
             ),
         )
+
+    def get_settings(self, args: Namespace) -> dict:
+        """Extract debug settings."""
+        settings = {}
+        if args.debug:
+            settings["debug.enabled"] = True
+        return settings
+
+
+@group(CAT_START)
+class DebugGroup(ArgumentGroup):
+    """Debug settings."""
+
+    GROUP_NAME = "Debug"
+
+    def add_arguments(self, parser: ArgumentParser):
+        """Add debug command line arguments to the parser."""
         parser.add_argument(
             "--debug-seed",
             dest="debug_seed",
@@ -415,8 +433,6 @@ def add_arguments(self, parser: ArgumentParser):
     def get_settings(self, args: Namespace) -> dict:
         """Extract debug settings."""
         settings = {}
-        if args.debug:
-            settings["debug.enabled"] = True
         if args.debug_connections:
             settings["debug.connections"] = True
         if args.debug_credentials:

aries_cloudagent/tests/test_main.py

@@ -34,9 +34,9 @@ def test_ptvsd(self):
             test_module.init_debug(["aca-py", "--debug"])
 
             mock_import.assert_called_once()
-            self.assertEqual(mock_import.call_args[0][0], "ptvsd")
-            mock_import.return_value.enable_attach.assert_called_once()
-            mock_import.return_value.wait_for_attach.assert_called_once()
+            self.assertEqual(mock_import.call_args[0][0], "debugpy")
+            mock_import.return_value.listen.assert_called_once()
+            mock_import.return_value.wait_for_client.assert_called_once()
 
     def test_ptvsd_import_x(self):
         with mock.patch("builtins.__import__") as mock_import:

conftest.py

@@ -146,19 +146,24 @@ def stub_ursa_bbs_signatures() -> Stub:
 
 def pytest_sessionstart(session):
     global STUBS, POSTGRES_URL, ENABLE_PTVSD
-    ENABLE_PTVSD = os.getenv("ENABLE_PTVSD", False)
-    # --debug-vs to use microsoft's visual studio remote debugger
-    if ENABLE_PTVSD or "--debug" in sys.argv:
+    args = sys.argv
+
+    # copied from __main__.py:init_debug
+    ENABLE_PTVSD = os.getenv("ENABLE_PTVSD", "").lower()
+    ENABLE_PTVSD = ENABLE_PTVSD and ENABLE_PTVSD not in ("false", "0")
+
+    # --debug to use microsoft's visual studio remote debugger
+    if ENABLE_PTVSD or "--debug" in args:
+        DAP_HOST = os.getenv("PTVSD_HOST", None) or os.getenv("DAP_HOST", "localhost")
+        DAP_PORT = os.getenv("PTVSD_PORT", None) or os.getenv("DAP_PORT", 5678)
         try:
-            import ptvsd
+            import debugpy
 
-            ptvsd.enable_attach(address=("0.0.0.0", 5678))
-            print("ptvsd is running")
-            print("=== Waiting for debugger to attach ===")
-            # To pause execution until the debugger is attached:
-            ptvsd.wait_for_attach()
+            debugpy.listen((DAP_HOST, DAP_PORT))
+            print(f"=== Waiting for debugger to attach to {DAP_HOST}:{DAP_PORT} ===")
+            debugpy.wait_for_client()
         except ImportError:
-            print("ptvsd library was not found")
+            print("debugpy library was not found")
 
     POSTGRES_URL = os.getenv("POSTGRES_URL")
 

docs/features/DevReadMe.md

@@ -182,7 +182,18 @@ For example:
 ./scripts/run_docker start --inbound-transport http 0.0.0.0 10000 --outbound-transport http --debug --log-level DEBUG
 ```
 
-To enable the [ptvsd](https://github.com/Microsoft/ptvsd) Python debugger for Visual Studio/VSCode use the `--debug` command line parameter.
+To enable the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) using the [debugpy implementation for Python 3](https://github.com/microsoft/debugpy/) Python debugger for Visual Studio/VSCode use the `--debug` command line parameter.
+
+When debugging an agent running within a docker container, you will need to set the DAP_HOST environment variable (defaults to ```localhost```)  to ```0.0.0.0``` to allow forwarding from within your docker container.
+
+Note that you may still find references to [PTVSD](https://github.com/microsoft/ptvsd), the deprecated implementation of DAP. PTVSD_HOST and PTVSD_PORT are interchangeable with DAP_HOST and DAP_PORT.
+
+Example:
+
+```bash
+ENV_VARS="DAP_HOST=0.0.0.0" scripts/run_docker provision --log-level debug  --wallet-type askar --wallet-name $(whoami) --wallet-key mysecretkey --endpoint http://localhost:8080 --no-ledger --debug
+```
+
 
 Any ports you will be using from the docker container should be published using the `PORTS` environment variable. For example: