Add more typing to debugpy and switch to 'standard' type checking mode

CONTRIBUTING.md

@@ -65,7 +65,7 @@ On Linux or macOS:
 ```
 .../debugpy$ python3 -m tox
 ```
-This will perform a full run with the default settings. A full run will run tests on Python 2.7 and 3.5-3.8, and requires all of those to be installed. If some versions are missing, or it is desired to skip them for a particular run, tox can be directed to only run tests on specific versions with `-e`. In addition, the `--developer` option can be used to skip the packaging step, running tests directly against the source code in `src/debugpy`. This should only be used when iterating on the code, and a proper run should be performed before submitting a PR. On Windows:
+This will perform a full run with the default settings. A full run will run tests on Python 2.7 and 3.5-3.8, and requires all of those to be installed. If some versions are missing, or it is desired to skip them for a particular run, tox can be directed to only run tests on specific versions with `-e`. In addition, the `--develop` option can be used to skip the packaging step, running tests directly against the source code in `src/debugpy`. This should only be used when iterating on the code, and a proper run should be performed before submitting a PR. On Windows:
 ```
 ...\debugpy> py -m tox -e py27,py37 --develop
 ```
@@ -76,7 +76,7 @@ On Linux or macOS:
 
 ### Running tests without tox
 
-While tox is the recommended way to run the test suite, pytest can also be invoked directly from the root of the repository. This requires packages in tests/test_requirements.txt to be installed first.
+While tox is the recommended way to run the test suite, pytest can also be invoked directly from the root (src/debugpy) of the repository. This requires packages in tests/requirements.txt to be installed first.
 
 ## Using modified debugpy in Visual Studio Code
 To test integration between debugpy and Visual Studio Code, the latter can be directed to use a custom version of debugpy in lieu of the one bundled with the Python extension. This is done by specifying `"debugAdapterPath"` in `launch.json` - it must point at the root directory of the *package*, which is `src/debugpy` inside the repository:

pyproject.toml

@@ -21,6 +21,8 @@ ignore = ["src/debugpy/_vendored/pydevd", "src/debugpy/_version.py"]
 executionEnvironments = [
   { root = "src" }, { root = "." }
 ]
+typeCheckingMode = "standard"
+enableTypeIgnoreComments = false
 
 [tool.ruff]
 # Enable the pycodestyle (`E`) and Pyflakes (`F`) rules by default.

src/debugpy/adapter/__main__.py

@@ -8,6 +8,7 @@
 import locale
 import os
 import sys
+from typing import Any
 
 # WARNING: debugpy and submodules must not be imported on top level in this module,
 # and should be imported locally inside main() instead.
@@ -53,7 +54,7 @@ def main(args):
     if args.for_server is None:
         adapter.access_token = codecs.encode(os.urandom(32), "hex").decode("ascii")
 
-    endpoints = {}
+    endpoints: dict[str, Any] = {}
     try:
         client_host, client_port = clients.serve(args.host, args.port)
     except Exception as exc:

src/debugpy/adapter/clients.py

@@ -7,13 +7,13 @@
 import atexit
 import os
 import sys
+from typing import Any, Callable, Union, cast
 
 import debugpy
 from debugpy import adapter, common, launcher
 from debugpy.common import json, log, messaging, sockets
 from debugpy.adapter import clients, components, launchers, servers, sessions
 
-
 class Client(components.Component):
     """Handles the client side of a debug session."""
 
@@ -67,7 +67,7 @@ def __init__(self, sock):
             fully handled.
             """
 
-            self.start_request = None
+            self.start_request: Union[messaging.Request, None] = None
             """The "launch" or "attach" request as received from the client.
             """
 
@@ -124,11 +124,12 @@ def propagate_after_start(self, event):
             self.client.channel.propagate(event)
 
     def _propagate_deferred_events(self):
-        log.debug("Propagating deferred events to {0}...", self.client)
-        for event in self._deferred_events:
-            log.debug("Propagating deferred {0}", event.describe())
-            self.client.channel.propagate(event)
-        log.info("All deferred events propagated to {0}.", self.client)
+        if self._deferred_events is not None:
+            log.debug("Propagating deferred events to {0}...", self.client)
+            for event in self._deferred_events:
+                log.debug("Propagating deferred {0}", event.describe())
+                self.client.channel.propagate(event)
+            log.info("All deferred events propagated to {0}.", self.client)
         self._deferred_events = None
 
     # Generic event handler. There are no specific handlers for client events, because
@@ -202,9 +203,9 @@ def initialize_request(self, request):
     #
     # See https://github.com/microsoft/vscode/issues/4902#issuecomment-368583522
     # for the sequence of request and events necessary to orchestrate the start.
-    def _start_message_handler(f):
+    def _start_message_handler(f: Callable[..., Any])-> Callable[..., object | None]:   # pyright: ignore[reportGeneralTypeIssues, reportSelfClsParameterName]
         @components.Component.message_handler
-        def handle(self, request):
+        def handle(self, request: messaging.Message):
             assert request.is_request("launch", "attach")
             if self._initialize_request is None:
                 raise request.isnt_valid("Session is not initialized yet")
@@ -215,15 +216,16 @@ def handle(self, request):
             if self.session.no_debug:
                 servers.dont_wait_for_first_connection()
 
+            request_options: list[Any] = cast("list[Any]", request("debugOptions", json.array(str)))
             self.session.debug_options = debug_options = set(
-                request("debugOptions", json.array(str))
+                request_options
             )
 
             f(self, request)
-            if request.response is not None:
+            if isinstance(request, messaging.Request) and request.response is not None:
                 return
 
-            if self.server:
+            if self.server and isinstance(request, messaging.Request):
                 self.server.initialize(self._initialize_request)
                 self._initialize_request = None
 
@@ -267,7 +269,7 @@ def handle(self, request):
                 except messaging.MessageHandlingError as exc:
                     exc.propagate(request)
 
-            if self.session.no_debug:
+            if self.session.no_debug and isinstance(request, messaging.Request):
                 self.start_request = request
                 self.has_started = True
                 request.respond({})
@@ -335,6 +337,7 @@ def property_or_debug_option(prop_name, flag_name):
             launcher_python = python[0]
 
         program = module = code = ()
+        args = []
         if "program" in request:
             program = request("program", str)
             args = [program]
@@ -391,7 +394,7 @@ def property_or_debug_option(prop_name, flag_name):
         if cwd == ():
             # If it's not specified, but we're launching a file rather than a module,
             # and the specified path has a directory in it, use that.
-            cwd = None if program == () else (os.path.dirname(program) or None)
+            cwd = None if program == () else (os.path.dirname(str(program)) or None)
 
         sudo = bool(property_or_debug_option("sudo", "Sudo"))
         if sudo and sys.platform == "win32":
@@ -484,7 +487,7 @@ def attach_request(self, request):
         else:
             if not servers.is_serving():
                 servers.serve()
-            host, port = servers.listener.getsockname()
+            host, port = servers.listener.getsockname() if servers.listener is not None else ("", 0)
 
         # There are four distinct possibilities here.
         #
@@ -576,9 +579,9 @@ def on_output(category, output):
             request.cant_handle("{0} is already being debugged.", conn)
 
     @message_handler
-    def configurationDone_request(self, request):
+    def configurationDone_request(self, request: messaging.Request):
         if self.start_request is None or self.has_started:
-            request.cant_handle(
+            raise request.cant_handle(
                 '"configurationDone" is only allowed during handling of a "launch" '
                 'or an "attach" request'
             )
@@ -623,7 +626,8 @@ def evaluate_request(self, request):
         def handle_response(response):
             request.respond(response.body)
 
-        propagated_request.on_response(handle_response)
+        if propagated_request is not None:
+            propagated_request.on_response(handle_response)
 
         return messaging.NO_RESPONSE
 
@@ -649,7 +653,7 @@ def debugpySystemInfo_request(self, request):
         result = {"debugpy": {"version": debugpy.__version__}}
         if self.server:
             try:
-                pydevd_info = self.server.channel.request("pydevdSystemInfo")
+                pydevd_info: messaging.MessageDict = self.server.channel.request("pydevdSystemInfo")
             except Exception:
                 # If the server has already disconnected, or couldn't handle it,
                 # report what we've got.
@@ -754,7 +758,7 @@ def notify_of_subprocess(self, conn):
         if "host" not in body["connect"]:
             body["connect"]["host"] = host if host is not None else "127.0.0.1"
         if "port" not in body["connect"]:
-            if port is None:
+            if port is None and listener is not None:
                 _, port = listener.getsockname()
             body["connect"]["port"] = port
 

src/debugpy/adapter/components.py

@@ -3,7 +3,12 @@
 # for license information.
 
 import functools
+from typing import TYPE_CHECKING, Type, TypeVar, Union, cast
 
+if TYPE_CHECKING:
+    # Dont import this during runtime. There's an order
+    # of imports issue that causes the debugger to hang.
+    from debugpy.adapter.sessions import Session
 from debugpy.common import json, log, messaging, util
 
 
@@ -31,7 +36,7 @@ class Component(util.Observable):
     to wait_for() a change caused by another component.
     """
 
-    def __init__(self, session, stream=None, channel=None):
+    def __init__(self, session: "Session", stream: "Union[messaging.JsonIOStream, None]"=None, channel: "Union[messaging.JsonMessageChannel, None]"=None):
         assert (stream is None) ^ (channel is None)
 
         try:
@@ -44,13 +49,14 @@ def __init__(self, session, stream=None, channel=None):
 
         self.session = session
 
-        if channel is None:
+        if channel is None and stream is not None:
             stream.name = str(self)
             channel = messaging.JsonMessageChannel(stream, self)
             channel.start()
-        else:
+        elif channel is not None:
             channel.name = channel.stream.name = str(self)
             channel.handlers = self
+        assert channel is not None
         self.channel = channel
         self.is_connected = True
 
@@ -108,8 +114,9 @@ def disconnect(self):
             self.is_connected = False
             self.session.finalize("{0} has disconnected".format(self))
 
+T = TypeVar('T')
 
-def missing(session, type):
+def missing(session, type: Type[T]) -> T:
     class Missing(object):
         """A dummy component that raises ComponentNotAvailable whenever some
         attribute is accessed on it.
@@ -124,7 +131,7 @@ def report():
         except Exception as exc:
             log.reraise_exception("{0} in {1}", exc, session)
 
-    return Missing()
+    return cast(type, Missing())
 
 
 class Capabilities(dict):

src/debugpy/adapter/launchers.py

@@ -3,6 +3,7 @@
 # for license information.
 
 import os
+import socket
 import subprocess
 import sys
 
@@ -18,7 +19,7 @@ class Launcher(components.Component):
 
     message_handler = components.Component.message_handler
 
-    def __init__(self, session, stream):
+    def __init__(self, session: sessions.Session, stream):
         with session:
             assert not session.launcher
             super().__init__(session, stream)
@@ -88,12 +89,13 @@ def spawn_debuggee(
     env = {}
 
     arguments = dict(start_request.arguments)
-    if not session.no_debug:
+    if not session.no_debug and servers.listener is not None:
         _, arguments["port"] = servers.listener.getsockname()
         arguments["adapterAccessToken"] = adapter.access_token
 
-    def on_launcher_connected(sock):
-        listener.close()
+    def on_launcher_connected(sock: socket.socket):
+        if listener is not None:
+            listener.close()
         stream = messaging.JsonIOStream.from_socket(sock)
         Launcher(session, stream)