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

CONTRIBUTING.md

@@ -91,7 +91,7 @@ The tests are run concurrently, and the default number of workers is 8. You can
 
 ### 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/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 a venv created by tox in the '.tox' folder can make it easier to get the pytest configuration correct. Debugpy needs to be installed into the venv for the tests to run, so using the tox generated .venv makes that easier.
 

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.
@@ -55,7 +56,7 @@ def main():
     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
@@ -203,9 +204,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")
@@ -216,15 +217,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
 
@@ -268,7 +270,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({})
@@ -336,6 +338,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]
@@ -392,7 +395,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":
@@ -487,6 +490,9 @@ def attach_request(self, request):
         else:
             if not servers.is_serving():
                 servers.serve(localhost)
+            # servers.serve() above guarantees a listener; fail fast if it's missing
+            # rather than handing the debuggee an empty ("", 0) address it can't use.
+            assert servers.listener is not None
             host, port = sockets.get_address(servers.listener)
 
         # There are four distinct possibilities here.
@@ -579,9 +585,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'
             )
@@ -626,7 +632,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
 
@@ -652,7 +659,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.
@@ -765,6 +772,10 @@ def notify_of_subprocess(self, conn):
             body["connect"]["host"] = host or localhost
         if "port" not in body["connect"]:
             if port is None:
+                # A subprocess is only reported once the client is connected, so the
+                # client listener must be serving; fail fast rather than sending the
+                # child a null port it can't connect to.
+                assert listener is not None
                 _, port = sockets.get_address(listener)
             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,18 +49,19 @@ 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
 
         # Do this last to avoid triggering useless notifications for assignments above.
-        self.observers += [lambda *_: self.session.notify_changed()]
+        self.observers = [*self.observers, lambda *_: self.session.notify_changed()]
 
     def __str__(self):
         return f"{type(self).__name__}[{self.session.id}]"
@@ -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)
@@ -89,11 +90,15 @@ def spawn_debuggee(
 
     arguments = dict(start_request.arguments)
     if not session.no_debug:
+        # For a debug launch the server listener must already be up; fail fast
+        # rather than silently spawning a debuggee that can't connect back.
+        assert servers.listener is not None
         _, arguments["port"] = sockets.get_address(servers.listener)
         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)