feat: core can be specified in the config file. #1746

Author: nedbat

CHANGES.rst

@@ -27,6 +27,11 @@ Unreleased
   PYTHONWARNDEFAULTENCODING, fixing `issue 1966`_.  Thanks, `Henry Schreiner
   <pull 1967_>`_.
 
+- Added a ``[run] core`` configuration setting to specify the measurement core,
+  which was previously only available through the COVERAGE_CORE environment
+  variable. Finishes `issue 1746`_.
+
+.. _issue 1746: https://github.com/nedbat/coveragepy/issues/1746
 .. _issue 1966: https://github.com/nedbat/coveragepy/issues/1966
 .. _pull 1967: https://github.com/nedbat/coveragepy/pull/1967
 

coverage/config.py

@@ -197,6 +197,7 @@ def __init__(self) -> None:
         self.command_line: str | None = None
         self.concurrency: list[str] = []
         self.context: str | None = None
+        self.core: str | None = None
         self.cover_pylib = False
         self.data_file = ".coverage"
         self.debug: list[str] = []
@@ -379,6 +380,7 @@ def copy(self) -> CoverageConfig:
         ("command_line", "run:command_line"),
         ("concurrency", "run:concurrency", "list"),
         ("context", "run:context"),
+        ("core", "run:core"),
         ("cover_pylib", "run:cover_pylib", "boolean"),
         ("data_file", "run:data_file"),
         ("debug", "run:debug", "list"),
@@ -621,6 +623,10 @@ def read_coverage_config(
     debugs = os.getenv("COVERAGE_DEBUG")
     if debugs:
         config.debug.extend(d.strip() for d in debugs.split(","))
+    # Read the COVERAGE_CORE environment variable for backward compatibility.
+    env_core = os.getenv("COVERAGE_CORE")
+    if env_core:
+        config.core = env_core
 
     # 4) from constructor arguments:
     config.from_args(**kwargs)

coverage/core.py

@@ -31,6 +31,8 @@
     CTRACER_FILE: str | None = coverage.tracer.__file__
 except ImportError:
     # 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.
     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
@@ -74,7 +76,7 @@ def __init__(
             core_name = "pytrace"
 
         if core_name is None:
-            core_name = os.getenv("COVERAGE_CORE")
+            core_name = config.core
 
         if core_name == "sysmon" and reason_no_sysmon:
             warn(f"sys.monitoring {reason_no_sysmon}, using default core", slug="no-sysmon")

doc/cmd.rst

@@ -204,8 +204,9 @@ simpler but slower trace method, and might be needed in rare cases.
 
 In Python 3.12 and above, you can try an experimental core based on the new
 :mod:`sys.monitoring <python:sys.monitoring>` module by defining a
-``COVERAGE_CORE=sysmon`` environment variable.  This should be faster, though
-plugins and dynamic contexts are not yet supported with it.
+``COVERAGE_CORE=sysmon`` environment variable or by setting ``core = sysmon``
+in the configuration file.  This should be faster, though plugins and
+dynamic contexts are not yet supported with it.
 
 Coverage.py sets an environment variable, ``COVERAGE_RUN`` to indicate that
 your code is running under coverage measurement.  The value is not relevant,

doc/config.rst

@@ -330,6 +330,23 @@ Before version 4.2, this option only accepted a single string.
 
 .. _config_run_cover_pylib:
 
+.. _config_run_core:
+
+[run] core
+................
+
+(string) Specify which trace function implementation to use. Valid values are:
+"pytrace" for the pure Python implementation, "ctrace" for the C implementation
+(default), or "sysmon" for the :mod:`sys.monitoring <python:sys.monitoring>`
+implementation (Python 3.12+ only).
+
+This was previously only available as the COVERAGE_CORE environment variable.
+Note that the "sysmon" core is experimental and does not yet support plugins
+or dynamic contexts.
+
+.. versionadded:: 7.9
+
+
 [run] cover_pylib
 .................
 

tests/test_config.py

@@ -491,6 +491,30 @@ def test_exclude_also(self) -> None:
         expected = coverage.config.DEFAULT_EXCLUDE + ["foobar", "raise .*Error"]
         assert cov.config.exclude_list == expected
 
+    def test_core_option(self) -> None:
+        # Test that the core option can be set in the configuration file
+        self.make_file(".coveragerc", """\
+            [run]
+            core = pytrace
+            """)
+
+        # Skip calling Coverage() which would actually initialize the tracer
+        # and instead manually initialize the config
+        from coverage.config import CoverageConfig
+        config = CoverageConfig()
+        config.from_file(".coveragerc", lambda m: None, our_file=True)
+        assert config.core == "pytrace"
+
+        # Test with TOML config file
+        self.make_file("pyproject.toml", """\
+            [tool.coverage.run]
+            core = "ctrace"
+            """)
+
+        config = CoverageConfig()
+        config.from_file("pyproject.toml", lambda m: None, our_file=True)
+        assert config.core == "ctrace"
+
 
 class ConfigFileTest(UsingModulesMixin, CoverageTest):
     """Tests of the config file settings in particular."""