fix: subprocesses inherit the entire configuration. #2021

Author: nedbat

CHANGES.rst

@@ -37,13 +37,20 @@ Unreleased
     ``ModuleNotFound`` error trying to import coverage.  This is now fixed,
     closing `issue 2022`_.
 
+  - Originally only options set in the coverage configuration file would apply
+    to subprocesses.  Options set on the ``coverage run`` command line (such as
+    ``--branch``) wouldn't be communicated to the subprocesses.  This could
+    lead to combining failures, as described in `issue 2021`_. Now the entire
+    configuration is used in subprocesses, regardless of its origin.
+
   - Added ``debug=patch`` to help diagnose problems.
 
 - Fix: really close all SQLite databases, even in-memory ones. Closes `issue
   2017`_.
 
 .. _issue 2007: https://github.com/nedbat/coveragepy/issues/2007
 .. _issue 2017: https://github.com/nedbat/coveragepy/issues/2017
+.. _issue 2021: https://github.com/nedbat/coveragepy/issues/2021
 .. _issue 2022: https://github.com/nedbat/coveragepy/issues/2022
 .. _issue 2024: https://github.com/nedbat/coveragepy/issues/2024
 .. _issue 2025: https://github.com/nedbat/coveragepy/issues/2025

coverage/config.py

@@ -5,9 +5,11 @@
 
 from __future__ import annotations
 
+import base64
 import collections
 import configparser
 import copy
+import json
 import os
 import os.path
 import re
@@ -273,6 +275,10 @@ def __init__(self) -> None:
         "patch",
     }
 
+    SERIALIZE_ABSPATH = {
+        "data_file", "debug_file", "source_dirs",
+    }
+
     def from_args(self, **kwargs: TConfigValueIn) -> None:
         """Read config values from `kwargs`."""
         for k, v in kwargs.items():
@@ -554,6 +560,22 @@ def debug_info(self) -> list[tuple[str, Any]]:
             (k, v) for k, v in self.__dict__.items() if not k.startswith("_")
         )
 
+    def serialize(self) -> str:
+        """Convert to a string that can be ingested with `deserialize_config`.
+
+        File paths used by `coverage run` are made absolute to ensure the
+        deserialized config will refer to the same files.
+        """
+        data = {k:v for k, v in self.__dict__.items() if not k.startswith("_")}
+        for k in self.SERIALIZE_ABSPATH:
+            v = data[k]
+            if isinstance(v, list):
+                v = list(map(os.path.abspath, v))
+            elif isinstance(v, str):
+                v = os.path.abspath(v)
+            data[k] = v
+        return base64.b64encode(json.dumps(data).encode()).decode()
+
 
 def process_file_value(path: str) -> str:
     """Make adjustments to a file path to make it usable."""
@@ -669,3 +691,11 @@ def read_coverage_config(
     config.post_process()
 
     return config
+
+
+def deserialize_config(config_str: str) -> CoverageConfig:
+    """Take a string from CoverageConfig.serialize, and make a CoverageConfig."""
+    data = json.loads(base64.b64decode(config_str.encode()).decode())
+    config = CoverageConfig()
+    config.__dict__.update(data)
+    return config

coverage/control.py

@@ -24,7 +24,7 @@
 from coverage import env
 from coverage.annotate import AnnotateReporter
 from coverage.collector import Collector
-from coverage.config import CoverageConfig, read_coverage_config
+from coverage.config import CoverageConfig, deserialize_config, read_coverage_config
 from coverage.context import combine_context_switchers, should_start_context_test_function
 from coverage.core import CTRACER_FILE, Core
 from coverage.data import CoverageData, combine_parallel_data
@@ -89,6 +89,7 @@ def override_config(cov: Coverage, **kwargs: TConfigValueIn) -> Iterator[None]:
 
 DEFAULT_DATAFILE = DefaultValue("MISSING")
 _DEFAULT_DATAFILE = DEFAULT_DATAFILE  # Just in case, for backwards compatibility
+CONFIG_FROM_ENVIRONMENT = ":envvar:"
 
 class Coverage(TConfigurable):
     """Programmatic access to coverage.py.
@@ -316,27 +317,30 @@ def __init__(                       # pylint: disable=too-many-arguments
         self._should_write_debug = True
 
         # Build our configuration from a number of sources.
-        if not isinstance(config_file, bool):
-            config_file = os.fspath(config_file)
-        self.config = read_coverage_config(
-            config_file=config_file,
-            warn=self._warn,
-            data_file=data_file,
-            cover_pylib=cover_pylib,
-            timid=timid,
-            branch=branch,
-            parallel=bool_or_none(data_suffix),
-            source=source,
-            source_pkgs=source_pkgs,
-            source_dirs=source_dirs,
-            run_omit=omit,
-            run_include=include,
-            debug=debug,
-            report_omit=omit,
-            report_include=include,
-            concurrency=concurrency,
-            context=context,
-        )
+        if config_file == CONFIG_FROM_ENVIRONMENT:
+            self.config = deserialize_config(cast(str, os.getenv("COVERAGE_PROCESS_CONFIG")))
+        else:
+            if not isinstance(config_file, bool):
+                config_file = os.fspath(config_file)
+            self.config = read_coverage_config(
+                config_file=config_file,
+                warn=self._warn,
+                data_file=data_file,
+                cover_pylib=cover_pylib,
+                timid=timid,
+                branch=branch,
+                parallel=bool_or_none(data_suffix),
+                source=source,
+                source_pkgs=source_pkgs,
+                source_dirs=source_dirs,
+                run_omit=omit,
+                run_include=include,
+                debug=debug,
+                report_omit=omit,
+                report_include=include,
+                concurrency=concurrency,
+                context=context,
+            )
 
         # If we have subprocess measurement happening automatically, then we
         # want any explicit creation of a Coverage object to mean, this process
@@ -1413,24 +1417,19 @@ def process_startup() -> Coverage | None:
     measurement is started.  The value of the variable is the config file
     to use.
 
-    There are two ways to configure your Python installation to invoke this
-    function when Python starts:
-
-    #. Create or append to sitecustomize.py to add these lines::
-
-        import coverage
-        coverage.process_startup()
-
-    #. Create a .pth file in your Python installation containing::
-
-        import coverage; coverage.process_startup()
+    For details, see https://coverage.readthedocs.io/en/latest/subprocess.html.
 
     Returns the :class:`Coverage` instance that was started, or None if it was
     not started by this call.
 
     """
     cps = os.getenv("COVERAGE_PROCESS_START")
-    if not cps:
+    config_data = os.getenv("COVERAGE_PROCESS_CONFIG")
+    if cps is not None:
+        config_file = cps
+    elif config_data is not None:
+        config_file = CONFIG_FROM_ENVIRONMENT
+    else:
         # No request for coverage, nothing to do.
         return None
 
@@ -1445,13 +1444,10 @@ def process_startup() -> Coverage | None:
 
     if hasattr(process_startup, "coverage"):
         # We've annotated this function before, so we must have already
-        # started coverage.py in this process.  Nothing to do.
+        # auto-started coverage.py in this process.  Nothing to do.
         return None
 
-    cov = Coverage(
-        config_file=cps,
-        data_file=os.getenv("COVERAGE_PROCESS_DATAFILE") or DEFAULT_DATAFILE,
-    )
+    cov = Coverage(config_file=config_file)
     process_startup.coverage = cov      # type: ignore[attr-defined]
     cov._warn_no_data = False
     cov._warn_unimported_source = False

coverage/patch.py

@@ -113,8 +113,7 @@ def delete_pth_files() -> None:
                 p.unlink(missing_ok=True)
         atexit.register(delete_pth_files)
     assert config.config_file is not None
-    os.environ["COVERAGE_PROCESS_START"] = config.config_file
-    os.environ["COVERAGE_PROCESS_DATAFILE"] = os.path.abspath(config.data_file)
+    os.environ["COVERAGE_PROCESS_CONFIG"] = config.serialize()
 
 
 # Writing .pth files is not obvious. On Windows, getsitepackages() returns two

doc/config.rst

@@ -459,10 +459,6 @@ Available patches:
   and will require combining data files before reporting.  See
   :ref:`cmd_combine` for more details.
 
-  .. note:: When using ``patch = subprocess``, all configuration options must
-      be specified in a configuration file.  Options on the ``coverage``
-      command line will not be available to subprocesses.
-
 - ``execv``: The :func:`execv <python:os.execl>` family of functions end the
   current program without giving coverage a chance to write collected data.
   This patch adjusts those functions to save the data before starting the next

tests/test_process.py

@@ -1436,10 +1436,40 @@ def test_subprocess_in_directories(self) -> None:
         self.run_command("coverage combine")
         data = coverage.CoverageData(".covdata")
         data.read()
-        print(line_counts(data))
         assert line_counts(data)["main.py"] == 6
         assert line_counts(data)["subproc.py"] == 2
 
+    def test_subprocess_gets_nonfile_config(self) -> None:
+        # https://github.com/nedbat/coveragepy/issues/2021
+        self.make_file("subfunctions.py", """\
+            import subprocess, sys
+
+            def f1():
+                print("function 1")
+            def f2():
+                print("function 2")
+
+            functions = [f1, f2]
+
+            cases = sys.argv[1:]
+            if len(cases) > 1:
+                for c in cases:
+                    subprocess.call([sys.executable, __file__, c])
+            else:
+                functions[int(cases[0])]()
+            """)
+        self.make_file(".coveragerc", """\
+            [run]
+            disable_warnings = no-sysmon
+            patch = subprocess
+            """)
+        out = self.run_command("coverage run --branch subfunctions.py 0 1")
+        assert out.endswith("function 1\nfunction 2\n")
+        self.run_command("coverage combine")
+        data = coverage.CoverageData()
+        data.read()
+        assert line_counts(data)["subfunctions.py"] == 11
+
 
 @pytest.mark.skipif(env.WINDOWS, reason="patch=execv isn't supported on Windows")
 @pytest.mark.xdist_group(name="needs_pth")