gh-110722: Make -m test -T -j use sys.monitoring

Doc/library/trace.rst

@@ -188,18 +188,20 @@ Programmatic Interface
       Merge in data from another :class:`CoverageResults` object.
 
    .. method:: write_results(show_missing=True, summary=False, coverdir=None,\
-                             ignore_missing_files=False)
+                             *, ignore_missing_files=False)
 
       Write coverage results.  Set *show_missing* to show lines that had no
       hits.  Set *summary* to include in the output the coverage summary per
       module.  *coverdir* specifies the directory into which the coverage
       result files will be output.  If ``None``, the results for each source
       file are placed in its directory.
 
-      If *ignore_missing_files* is True, coverage counts for files that no
+      If *ignore_missing_files* is ``True``, coverage counts for files that no
       longer exist are silently ignored. Otherwise, a missing file will
       raise a :exc:`FileNotFoundError`.
 
+      .. versionchanged:: 3.13
+         Added *ignore_missing_files* parameter.
 
 A simple example demonstrating the use of the programmatic interface::
 

Lib/test/cov.py

@@ -1,22 +1,48 @@
-"""A minimal hook for gathering line coverage of the standard library."""
+"""A minimal hook for gathering line coverage of the standard library.
+
+Designed to be used with -Xpresite= which means:
+* it installs itself on import
+* it's not imported as `__main__` so can't use the ifmain idiom
+* it can't import anything besides `sys` to avoid tainting gathered coverage
+* filenames are not normalized
+
+To get gathered coverage back, look for 'test.cov' in `sys.modules`
+instead of importing directly. That way you can determine if the module
+was already in use.
+
+If you need to disable the hook, call the `disable()` function.
+"""
 
 import sys
 
 mon = sys.monitoring
-mon.use_tool_id(mon.COVERAGE_ID, "regrtest coverage")
 
 FileName = str
 LineNo = int
 Location = tuple[FileName, LineNo]
-COVERAGE: set[Location] = set()
 
-# `types` and `typing` not imported to avoid invalid coverage
+coverage: set[Location] = set()
+
+
+# `types` and `typing` aren't imported to avoid invalid coverage
 def add_line(
     code: "types.CodeType",
     lineno: int,
 ) -> "typing.Literal[sys.monitoring.DISABLE]":
-    COVERAGE.add((code.co_filename, lineno))
+    coverage.add((code.co_filename, lineno))
     return mon.DISABLE
 
-mon.register_callback(mon.COVERAGE_ID, mon.events.LINE, add_line)
-mon.set_events(mon.COVERAGE_ID, mon.events.LINE)
+
+def enable():
+    mon.use_tool_id(mon.COVERAGE_ID, "regrtest coverage")
+    mon.register_callback(mon.COVERAGE_ID, mon.events.LINE, add_line)
+    mon.set_events(mon.COVERAGE_ID, mon.events.LINE)
+
+
+def disable():
+    mon.set_events(mon.COVERAGE_ID, 0)
+    mon.register_callback(mon.COVERAGE_ID, mon.events.LINE, None)
+    mon.free_tool_id(mon.COVERAGE_ID)
+
+
+enable()

Lib/test/libregrtest/main.py

@@ -295,14 +295,15 @@ def run_test(
             namespace = dict(locals())
             tracer.runctx(cmd, globals=globals(), locals=namespace)
             result = namespace['result']
+            result.covered_lines = list(tracer.counts)
         else:
             result = run_single_test(test_name, runtests)
 
         self.results.accumulate_result(result, runtests)
 
         return result
 
-    def run_tests_sequentially(self, runtests) -> trace.CoverageResults | None:
+    def run_tests_sequentially(self, runtests) -> None:
         if self.coverage:
             tracer = trace.Trace(trace=False, count=True)
         else:
@@ -351,8 +352,6 @@ def run_tests_sequentially(self, runtests) -> trace.CoverageResults | None:
         if previous_test:
             print(previous_test)
 
-        return tracer.results() if tracer else None
-
     def get_state(self):
         state = self.results.get_state(self.fail_env_changed)
         if self.first_state:
@@ -461,10 +460,10 @@ def _run_tests(self, selected: TestTuple, tests: TestList | None) -> int:
         try:
             if self.num_workers:
                 self._run_tests_mp(runtests, self.num_workers)
-                coverage = self.results.get_coverage_results()
             else:
-                coverage = self.run_tests_sequentially(runtests)
+                self.run_tests_sequentially(runtests)
 
+            coverage = self.results.get_coverage_results()
             self.display_result(runtests)
 
             if self.want_rerun and self.results.need_rerun():

Lib/test/libregrtest/worker.py

@@ -91,7 +91,7 @@ def worker_process(worker_json: StrJSON) -> NoReturn:
     result = run_single_test(test_name, runtests)
     if runtests.coverage:
         if "test.cov" in sys.modules:  # imported by -Xpresite=
-            result.covered_lines = list(sys.modules["test.cov"].COVERAGE)
+            result.covered_lines = list(sys.modules["test.cov"].coverage)
         elif not Py_DEBUG:
             print(
                 "Gathering coverage in worker processes requires --with-pydebug",

Lib/trace.py

@@ -202,7 +202,7 @@ def update(self, other):
         for key in other_callers:
             callers[key] = 1
 
-    def write_results(self, show_missing=True, summary=False, coverdir=None,
+    def write_results(self, show_missing=True, summary=False, coverdir=None, *,
                       ignore_missing_files=False):
         """
         Write the coverage results.