feat: core instead of tracer

The core of coverage.py is how it learns about execution. Now that we have
sys.monitoring, it might not be a trace function. So instead of specifying the
tracer to use, we specify the "core" to use.

Author: nedbat

Makefile

@@ -58,7 +58,7 @@ lint:					## Run linters and checkers.
 PYTEST_SMOKE_ARGS = -n auto -m "not expensive" --maxfail=3 $(ARGS)
 
 smoke: 					## Run tests quickly with the C tracer in the lowest supported Python versions.
-	COVERAGE_NO_PYTRACER=1 tox -q -e py38 -- $(PYTEST_SMOKE_ARGS)
+	COVERAGE_TEST_CORES=ctrace tox -q -e py38 -- $(PYTEST_SMOKE_ARGS)
 
 
 ##@ Metacov: coverage measurement of coverage.py itself
@@ -73,7 +73,7 @@ metahtml:				## Produce meta-coverage HTML reports.
 	python igor.py combine_html
 
 metasmoke:
-	COVERAGE_NO_PYTRACER=1 ARGS="-e py39" make metacov metahtml
+	COVERAGE_TEST_CORES=ctrace ARGS="-e py39" make metacov metahtml
 
 
 ##@ Requirements management

coverage/collector.py

@@ -37,14 +37,14 @@
     HAS_CTRACER = True
 except ImportError:
     # Couldn't import the C extension, maybe it isn't built.
-    if os.getenv('COVERAGE_TEST_TRACER') == 'c':        # pragma: part covered
-        # During testing, we use the COVERAGE_TEST_TRACER environment variable
+    if os.getenv("COVERAGE_CORE") == "ctrace":      # pragma: part covered
+        # During testing, we use the COVERAGE_CORE environment variable
         # to indicate that we've fiddled with the environment to test this
         # fallback code.  If we thought we had a C tracer, but couldn't import
         # it, then exit quickly and clearly instead of dribbling confusing
         # errors. I'm using sys.exit here instead of an exception because an
         # exception here causes all sorts of other noise in unittest.
-        sys.stderr.write("*** COVERAGE_TEST_TRACER is 'c' but can't import CTracer!\n")
+        sys.stderr.write("*** COVERAGE_CORE is 'ctrace' but can't import CTracer!\n")
         sys.exit(1)
     HAS_CTRACER = False
 
@@ -141,28 +141,37 @@ def __init__(
         self._trace_class: Type[TTracer]
         self.file_disposition_class: Type[TFileDisposition]
 
-        use_ctracer = False
-        if HAS_CTRACER and not timid:
-            use_ctracer = True
-
-        if env.PYBEHAVIOR.pep669 and self.should_start_context is None:
+        core: Optional[str]
+        if timid:
+            core = "pytrace"
+        else:
+            core = os.getenv("COVERAGE_CORE")
+            if not core:
+                if env.PYBEHAVIOR.pep669 and self.should_start_context is None:
+                    core = "sysmon"
+                elif HAS_CTRACER:
+                    core = "ctrace"
+
+        if core == "sysmon":
             self._trace_class = Pep669Tracer
             self.file_disposition_class = FileDisposition
             self.supports_plugins = False
             self.packed_arcs = False
             self.systrace = False
-        elif use_ctracer:
+        elif core == "ctrace":
             self._trace_class = CTracer
             self.file_disposition_class = CFileDisposition
             self.supports_plugins = True
             self.packed_arcs = True
             self.systrace = True
-        else:
+        elif core == "pytrace":
             self._trace_class = PyTracer
             self.file_disposition_class = FileDisposition
             self.supports_plugins = False
             self.packed_arcs = False
             self.systrace = True
+        else:
+            raise ConfigError(f"Unknown core value: {core!r}")
 
         # We can handle a few concurrency options here, but only one at a time.
         concurrencies = set(self.concurrency)

doc/contributing.rst

@@ -173,6 +173,8 @@ can combine tox and pytest options::
       py310: OK (17.99 seconds)
       congratulations :) (19.09 seconds)
 
+TODO: Update this for CORE instead of TRACER
+
 You can also affect the test runs with environment variables. Define any of
 these as 1 to use them:
 
@@ -191,7 +193,7 @@ these as 1 to use them:
 There are other environment variables that affect tests.  I use `set_env.py`_
 as a simple terminal interface to see and set them.
 
-Of course, run all the tests on every version of Python you have, before
+Of course, run all the tests on every version of Python you have before
 submitting a change.
 
 .. _pytest test selectors: https://doc.pytest.org/en/stable/usage.html#specifying-which-tests-to-run

igor.py

@@ -103,38 +103,48 @@ def do_remove_extension(*args):
                         print(f"Couldn't remove {filename}: {exc}")
 
 
-def label_for_tracer(tracer):
+def label_for_core(core):
     """Get the label for these tests."""
-    if tracer == "py":
-        label = "with Python tracer"
+    if core == "pytrace":
+        return "with Python tracer"
+    elif core == "ctrace":
+        return "with C tracer"
+    elif core == "sysmon":
+        return "with sys.monitoring"
     else:
-        label = "with C tracer"
+        raise ValueError(f"Bad core: {core!r}")
 
-    return label
 
+def should_skip(core):
+    """Is there a reason to skip these tests?
 
-def should_skip(tracer):
-    """Is there a reason to skip these tests?"""
+    Return empty string to run tests, or a message about why we are skipping
+    the tests.
+    """
     skipper = ""
 
-    # $set_env.py: COVERAGE_ONE_TRACER - Only run tests for one tracer.
-    only_one = os.getenv("COVERAGE_ONE_TRACER")
-    if only_one:
-        if CPYTHON:
-            if tracer == "py":
-                skipper = "Only one tracer: no Python tracer for CPython"
-        else:
-            if tracer == "c":
-                skipper = f"No C tracer for {platform.python_implementation()}"
-    elif tracer == "py":
-        # $set_env.py: COVERAGE_NO_PYTRACER - Don't run the tests under the Python tracer.
-        skipper = os.getenv("COVERAGE_NO_PYTRACER")
+    # $set_env.py: COVERAGE_TEST_CORES - List of cores to run
+    test_cores = os.getenv("COVERAGE_TEST_CORES")
+    if test_cores:
+        if core not in test_cores:
+            skipper = f"core {core} not in COVERAGE_TEST_CORES={test_cores}"
+
     else:
-        # $set_env.py: COVERAGE_NO_CTRACER - Don't run the tests under the C tracer.
-        skipper = os.getenv("COVERAGE_NO_CTRACER")
+        # $set_env.py: COVERAGE_ONE_CORE - Only run tests for one core.
+        only_one = os.getenv("COVERAGE_ONE_CORE")
+        if only_one:
+            if CPYTHON:
+                if sys.version_info >= (3, 12):
+                    if core != "sysmon":
+                        skipper = f"Only one core: not running {core}"
+                elif core != "ctrace":
+                    skipper = f"Only one core: not running {core}"
+            else:
+                if core != "pytrace":
+                    skipper = f"No C core for {platform.python_implementation()}"
 
     if skipper:
-        msg = "Skipping tests " + label_for_tracer(tracer)
+        msg = "Skipping tests " + label_for_core(core)
         if len(skipper) > 1:
             msg += ": " + skipper
     else:
@@ -143,26 +153,26 @@ def should_skip(tracer):
     return msg
 
 
-def make_env_id(tracer):
+def make_env_id(core):
     """An environment id that will keep all the test runs distinct."""
     impl = platform.python_implementation().lower()
     version = "%s%s" % sys.version_info[:2]
     if PYPY:
         version += "_%s%s" % sys.pypy_version_info[:2]
-    env_id = f"{impl}{version}_{tracer}"
+    env_id = f"{impl}{version}_{core}"
     return env_id
 
 
-def run_tests(tracer, *runner_args):
+def run_tests(core, *runner_args):
     """The actual running of tests."""
     if "COVERAGE_TESTING" not in os.environ:
         os.environ["COVERAGE_TESTING"] = "True"
-    print_banner(label_for_tracer(tracer))
+    print_banner(label_for_core(core))
 
     return pytest.main(list(runner_args))
 
 
-def run_tests_with_coverage(tracer, *runner_args):
+def run_tests_with_coverage(core, *runner_args):
     """Run tests, but with coverage."""
     # Need to define this early enough that the first import of env.py sees it.
     os.environ["COVERAGE_TESTING"] = "True"
@@ -172,7 +182,7 @@ def run_tests_with_coverage(tracer, *runner_args):
     if context:
         if context[0] == "$":
             context = os.environ[context[1:]]
-        os.environ["COVERAGE_CONTEXT"] = context + "." + tracer
+        os.environ["COVERAGE_CONTEXT"] = context + "." + core
 
     # Create the .pth file that will let us measure coverage in sub-processes.
     # The .pth file seems to have to be alphabetically after easy-install.pth
@@ -183,7 +193,7 @@ def run_tests_with_coverage(tracer, *runner_args):
     with open(pth_path, "w") as pth_file:
         pth_file.write("import coverage; coverage.process_startup()\n")
 
-    suffix = f"{make_env_id(tracer)}_{platform.platform()}"
+    suffix = f"{make_env_id(core)}_{platform.platform()}"
     os.environ["COVERAGE_METAFILE"] = os.path.abspath(".metacov." + suffix)
 
     import coverage
@@ -211,7 +221,7 @@ def run_tests_with_coverage(tracer, *runner_args):
         sys.modules.update(covmods)
 
         # Run tests, with the arguments from our command line.
-        status = run_tests(tracer, *runner_args)
+        status = run_tests(core, *runner_args)
 
     finally:
         cov.stop()
@@ -240,19 +250,19 @@ def do_combine_html():
     cov.html_report(show_contexts=show_contexts)
 
 
-def do_test_with_tracer(tracer, *runner_args):
-    """Run tests with a particular tracer."""
+def do_test_with_core(core, *runner_args):
+    """Run tests with a particular core."""
     # If we should skip these tests, skip them.
-    skip_msg = should_skip(tracer)
+    skip_msg = should_skip(core)
     if skip_msg:
         print(skip_msg)
         return None
 
-    os.environ["COVERAGE_TEST_TRACER"] = tracer
+    os.environ["COVERAGE_CORE"] = core
     if os.getenv("COVERAGE_COVERAGE", "no") == "yes":
-        return run_tests_with_coverage(tracer, *runner_args)
+        return run_tests_with_coverage(core, *runner_args)
     else:
-        return run_tests(tracer, *runner_args)
+        return run_tests(core, *runner_args)
 
 
 def do_zip_mods():

tox.ini

@@ -26,7 +26,7 @@ install_command = python -m pip install -U {opts} {packages}
 
 passenv = *
 setenv =
-    pypy3{,8,9,10}: COVERAGE_NO_CTRACER=no C extension under PyPy
+    pypy3{,8,9,10}: COVERAGE_TEST_CORES=pytrace
     # For some tests, we need .pyc files written in the current directory,
     # so override any local setting.
     PYTHONPYCACHEPREFIX=
@@ -41,13 +41,15 @@ commands =
     # Build the C extension and test with the CTracer
     python setup.py --quiet build_ext --inplace
     python -m pip install {env:COVERAGE_PIP_ARGS} -q -e .
-    python igor.py test_with_tracer c {posargs}
+    python igor.py test_with_core ctrace {posargs}
+
+    py3{12}: python igor.py test_with_core sysmon {posargs}
 
     # Remove the C extension so that we can test the PyTracer
     python igor.py remove_extension
 
     # Test with the PyTracer
-    python igor.py test_with_tracer py {posargs}
+    python igor.py test_with_core pytrace {posargs}
 
 [testenv:anypy]
 # $set_env.py: COVERAGE_ANYPY - The custom Python for "tox -e anypy"