feat: patch=fork

Author: nedbat

CHANGES.rst

@@ -23,6 +23,9 @@ upgrading your version of coverage.py.
 Unreleased
 ----------
 
+- Added ``patch = fork`` for times when the built-in forking support is
+  insufficient.
+
 - Fix: ``patch = execv`` also inherits the entire coverage configuration now.
 
 

coverage/control.py

@@ -1410,7 +1410,7 @@ def plugin_info(plugins: list[Any]) -> list[str]:
     )(Coverage)
 
 
-def process_startup() -> Coverage | None:
+def process_startup(*, force: bool = False) -> Coverage | None:
     """Call this at Python start-up to perhaps measure coverage.
 
     If the environment variable COVERAGE_PROCESS_START is defined, coverage
@@ -1442,7 +1442,7 @@ def process_startup() -> Coverage | None:
     #
     # https://github.com/nedbat/coveragepy/issues/340 has more details.
 
-    if hasattr(process_startup, "coverage"):
+    if not force and hasattr(process_startup, "coverage"):
         # We've annotated this function before, so we must have already
         # auto-started coverage.py in this process.  Nothing to do.
         return None
@@ -1459,6 +1459,13 @@ def process_startup() -> Coverage | None:
     return cov
 
 
+def _after_fork_in_child() -> None:
+    """Used by patch=fork in the child process to restart coverage."""
+    if cov := Coverage.current():
+        cov.stop()
+    process_startup(force=True)
+
+
 def _prevent_sub_process_measurement() -> None:
     """Stop any subprocess auto-measurement from writing data."""
     auto_created_coverage = getattr(process_startup, "coverage", None)

coverage/patch.py

@@ -38,6 +38,9 @@ def apply_patches(
         elif patch == "execv":
             _patch_execv(cov, config, debug)
 
+        elif patch == "fork":
+            _patch_fork(debug)
+
         elif patch == "subprocess":
             _patch_subprocess(config, debug, make_pth_file)
 
@@ -101,6 +104,16 @@ def coverage_execv_patch(*args: Any, **kwargs: Any) -> Any:
     os.execve = make_execv_patch("execve", os.execve)
 
 
+def _patch_fork(debug: TDebugCtl) -> None:
+    """Ensure Coverage is properly reset after a fork."""
+    from coverage.control import _after_fork_in_child
+    if env.WINDOWS:
+        raise CoverageException("patch=fork isn't supported yet on Windows.")
+
+    debug.write("Patching fork")
+    os.register_at_fork(after_in_child=_after_fork_in_child)
+
+
 def _patch_subprocess(config: CoverageConfig, debug: TDebugCtl, make_pth_file: bool) -> None:
     """Write .pth files and set environment vars to measure subprocesses."""
     debug.write("Patching subprocess")

doc/config.rst

@@ -443,10 +443,19 @@ side-effects.
 
 Available patches:
 
+- ``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
+  executable. Not available on Windows.
+
 - ``_exit``: The :func:`os._exit() <python:os._exit>` function exits the
   process immediately without calling cleanup handlers.  This patch saves
   coverage data before exiting.
 
+- ``fork``: Forking a process normally continues measuring coverage properly.
+  This patch stops the previous coverage and starts a new one in the child
+  process for those times when the default handling isn't enough.
+
 - ``subprocess``: Python sub-processes normally won't get coverage measurement.
   This patch configures Python to start coverage automatically, and will apply
   to processes created with :mod:`subprocess`, :func:`os.system`, or one of the
@@ -459,11 +468,6 @@ Available patches:
   and will require combining data files before reporting.  See
   :ref:`cmd_combine` for more details.
 
-- ``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
-  executable. Not available on Windows.
-
 .. versionadded:: 7.10