run: Support system signal as a coverage report dump trigger.

Signed-off-by: Arkady Gilinsky <9481855+ark-g@users.noreply.github.com>

Author: ark-g

coverage/cmdline.py

@@ -10,9 +10,11 @@
 import os
 import os.path
 import shlex
+import signal
 import sys
 import textwrap
 import traceback
+import types
 
 from typing import cast, Any, NoReturn
 
@@ -227,7 +229,15 @@ class Opts:
         "", "--version", action="store_true",
         help="Display version information and exit.",
     )
-
+    dump_signal = optparse.make_option(
+        '', '--dump_signal', action='store', metavar='DUMP_SIGNAL',
+        choices = ['USR1', 'USR2'],
+        help=(
+            "Define a system signal that will trigger coverage report dump. " +
+            "It is important that target script do not intercept this signal. " +
+            "Currently supported options are: USR1, USR2."
+        ),
+    )
 
 class CoverageOptionParser(optparse.OptionParser):
     """Base OptionParser for coverage.py.
@@ -251,6 +261,7 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
             data_file=None,
             debug=None,
             directory=None,
+            dump_signal=None,
             fail_under=None,
             format=None,
             help=None,
@@ -525,6 +536,7 @@ def get_prog_name(self) -> str:
             Opts.parallel_mode,
             Opts.source,
             Opts.timid,
+            Opts.dump_signal,
             ] + GLOBAL_ARGS,
         usage="[options] <pyfile> [program options]",
         description="Run a Python program, measuring code execution.",
@@ -807,6 +819,11 @@ def do_help(
 
         return False
 
+    def do_dump(self, _signum: int, _frame: types.FrameType | None) -> None:
+        """ Signal handler to dump coverage report """
+        print("Dumping coverage data ...")
+        self.coverage.save()
+
     def do_run(self, options: optparse.Values, args: list[str]) -> int:
         """Implementation of 'coverage run'."""
 
@@ -851,6 +868,15 @@ def do_run(self, options: optparse.Values, args: list[str]) -> int:
         if options.append:
             self.coverage.load()
 
+        if options.dump_signal:
+            if options.dump_signal.upper() == 'USR1':
+                signal.signal(signal.SIGUSR1, self.do_dump)
+            elif options.dump_signal.upper() == 'USR2':
+                signal.signal(signal.SIGUSR2, self.do_dump)
+            else:
+                show_help(f"Unsupported signal for dump coverage report: {options.dump_signal}")
+                return ERR
+
         # Run the script.
         self.coverage.start()
         code_ran = True

doc/cmd.rst

@@ -137,13 +137,18 @@ There are many options:
                             A list of directories or importable names of code to
                             measure.
       --timid               Use the slower Python trace function core.
+      --dump_signal=DUMP_SIGNAL
+                            Define a system signal that will trigger coverage
+                            report dump. It is important that target script do not
+                            intercept this signal. Currently supported options
+                            are: USR1, USR2.
       --debug=OPTS          Debug options, separated by commas. [env:
                             COVERAGE_DEBUG]
       -h, --help            Get help on this command.
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (sum: saD//ido/B)
+.. [[[end]]] (sum: kxkJi2xQZv)
 
 If you want :ref:`branch coverage <branch>` measurement, use the ``--branch``
 flag.  Otherwise only statement coverage is measured.
@@ -215,6 +220,9 @@ and may change in the future.
 These options can also be set in the :ref:`config_run` section of your
 .coveragerc file.
 
+In case if you are specifying ``--dump_signal``, please make sure that
+your target script doesn't intercept this signal. Otherwise the coverage
+reports will not be generated.
 
 .. _cmd_warnings: