fix: issue a warning if the C tracer can't be imported

Author: nedbat

CHANGES.rst

@@ -30,8 +30,11 @@ Unreleased
 - Fixed incorrect rendering of f-strings with doubled braces, closing `issue
   1980`_.
 
-- The C extension module now conforms to `PEP 489`_, closing `issue 1977`_.
-  Thanks, `Adam Turner <pull 1978_>`_.
+- The C tracer core extension module now conforms to `PEP 489`_, closing `issue
+  1977`_.  Thanks, `Adam Turner <pull 1978_>`_.
+
+- If the C tracer core can't be imported, a warning ("no-ctracer") is issued
+  with the reason.
 
 - Fixed a "ValueError: min() arg is an empty sequence" error caused by strange
   empty modules, found by `oss-fuzz`_.

coverage/core.py

@@ -25,11 +25,13 @@
 
 os = isolate_module(os)
 
+IMPORT_ERROR: str = ""
+
 try:
     # Use the C extension code when we can, for speed.
     import coverage.tracer
     CTRACER_FILE: str | None = coverage.tracer.__file__
-except ImportError:
+except ImportError as imp_err:
     # Couldn't import the C extension, maybe it isn't built.
     # We still need to check the environment variable directly here,
     # as this code runs before configuration is loaded.
@@ -42,6 +44,7 @@
         # exception here causes all sorts of other noise in unittest.
         sys.stderr.write("*** COVERAGE_CORE is 'ctrace' but can't import CTracer!\n")
         sys.exit(1)
+    IMPORT_ERROR = str(imp_err)
     CTRACER_FILE = None
 
 
@@ -89,6 +92,8 @@ def __init__(
             if CTRACER_FILE:
                 core_name = "ctrace"
             else:
+                if env.CPYTHON and IMPORT_ERROR:
+                    warn(f"Couldn't import C tracer: {IMPORT_ERROR}", slug="no-ctracer", once=True)
                 core_name = "pytrace"
 
         self.tracer_kwargs = {}

doc/cmd.rst

@@ -274,6 +274,11 @@ Conflicting dynamic contexts (dynamic-conflict)
   :meth:`.Coverage.switch_context` function to change the context. Only one of
   these mechanisms should be in use at a time.
 
+Couldn't import C tracer (no-ctracer)
+  The core tracer implemented in C should have been used, but couldn't be
+  imported.  The reason is included in the warning message.  The Python tracer
+  will be used instead.
+
 sys.monitoring isn't available in this version, using default core (no-sysmon)
   You requested to use the sys.monitoring measurement core, but are running on
   Python 3.11 or lower where it isn't available.  A default core will be used

tests/test_process.py

@@ -1136,10 +1136,13 @@ def test_core_default(self) -> None:
         core = re_line(r" core:", out).strip()
         # if env.PYBEHAVIOR.pep669:
         #     assert core == "core: SysMonitor"
+        warns = re_lines(r"\(no-ctracer\)", out)
         if self.has_ctracer:
             assert core == "core: CTracer"
+            assert not warns
         else:
             assert core == "core: PyTracer"
+            assert bool(warns) == env.CPYTHON
 
     @pytest.mark.skipif(not has_ctracer, reason="No CTracer to request")
     def test_core_request_ctrace(self) -> None:
@@ -1164,12 +1167,12 @@ def test_core_request_sysmon(self) -> None:
         out = self.run_command("coverage run --debug=sys numbers.py")
         assert out.endswith("123 456\n")
         core = re_line(r" core:", out).strip()
-        warns = re_lines(r"CoverageWarning: sys.monitoring isn't available", out)
+        warns = re_lines(r"\(no-sysmon\)", out)
         if env.PYBEHAVIOR.pep669:
             assert core == "core: SysMonitor"
             assert not warns
         else:
-            assert core in ("core: CTracer", "core: PyTracer")
+            assert core in ["core: CTracer", "core: PyTracer"]
             assert warns
 
     def test_core_request_nosuchcore(self) -> None: