docs: --save-signal #1998 Thanks, Arkady Gilinsky

Author: nedbat

CHANGES.rst

@@ -38,6 +38,11 @@ Unreleased
   abruptly end the process.  This closes long-standing `issue 310`_ as well as
   its duplicates: `issue 312`_, `issue 1845`_, and `issue 1941`_.
 
+- A new command-line option: ``--save-signal=USR1`` specifies a signal that
+  coverage.py will listen for.  When the signal is sent, the coverage data will
+  be saved.  This makes it possible to save data from within long-running
+  processes.  Thanks, `Arkady Gilinsky <pull 1998_>`_.
+
 - A new configuration option: ":ref:`config_report_partial_also`" is a list of
   regexes to add as pragmas for partial branches.  This parallels the
   ":ref:`config_report_exclude_also`" setting for adding line exclusion
@@ -56,6 +61,7 @@ Unreleased
 .. _issue 1308: https://github.com/nedbat/coveragepy/issues/1308
 .. _issue 1845: https://github.com/nedbat/coveragepy/issues/1845
 .. _issue 1941: https://github.com/nedbat/coveragepy/issues/1941
+.. _pull 1998: https://github.com/nedbat/coveragepy/pull/1998
 .. _issue 2001: https://github.com/nedbat/coveragepy/issues/2001
 
 

CONTRIBUTORS.txt

@@ -21,6 +21,7 @@ Anders Kaseorg
 Andrew Hoos
 Anthony Sottile
 Arcadiy Ivanov
+Arkady Gilinsky
 Aron Griffis
 Artem Dayneko
 Arthur Deygin

coverage/cmdline.py

@@ -191,13 +191,11 @@ class Opts:
         ),
     )
     save_signal = optparse.make_option(
-        '', '--save-signal', action='store', metavar='SAVE_SIGNAL',
+        '', '--save-signal', action='store', metavar='SIGNAL',
         choices = ['USR1', 'USR2'],
         help=(
-            "Define a system signal that will trigger coverage report save operation. " +
-            "It is important that target script do not intercept this signal. " +
-            "Currently supported options are: USR1, USR2. " +
-            "This feature does not work on Windows."
+            "Specify a signal that will trigger coverage to write its collected data. " +
+            "Supported values are: USR1, USR2. Not available on Windows."
         ),
     )
     show_contexts = optparse.make_option(

doc/cmd.rst

@@ -133,12 +133,9 @@ There are many options:
       -p, --parallel-mode   Append the machine name, process id and random number
                             to the data file name to simplify collecting data from
                             many processes.
-      --save-signal=SAVE_SIGNAL
-                            Define a system signal that will trigger coverage
-                            report save operation. It is important that target
-                            script do not intercept this signal. Currently
-                            supported options are: USR1, USR2. This feature does
-                            not work on Windows.
+      --save-signal=SIGNAL  Specify a signal that will trigger coverage to write
+                            its collected data. Supported values are: USR1, USR2.
+                            Not available on Windows.
       --source=SRC1,SRC2,...
                             A list of directories or importable names of code to
                             measure.
@@ -149,7 +146,7 @@ There are many options:
       --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
                             'setup.cfg', 'tox.ini', and 'pyproject.toml' are
                             tried. [env: COVERAGE_RCFILE]
-.. [[[end]]] (sum: X8Kbvdq2+f)
+.. [[[end]]] (sum: 1Ks5r6cadh)
 
 If you want :ref:`branch coverage <branch>` measurement, use the ``--branch``
 flag.  Otherwise only statement coverage is measured.
@@ -221,9 +218,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 ``--save-signal``, please make sure that
-your target script doesn't intercept this signal. Otherwise the coverage
-reports will not be generated.
+If you are specifying ``--save-signal``, please make sure that your program
+doesn't intercept this signal. If it does, coverage won't receive the signal
+and the data file will not be written.
 
 .. _cmd_warnings: