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

ark-g · 2025-07-12T04:59:52Z

Implement a feature that allows users to generate a coverage report by sending a signal. This is particularly useful for obtaining coverage reports from continuously running Python scripts, such as server implementations or monitoring utilities.
Currently supported only two signals SIGUSR1 and SIGUSR2.

Signed-off-by: Arkady Gilinsky <[email protected]>

nedbat

A few small changes. I'll adjust the English description once this merges.

nedbat · 2025-07-12T11:35:12Z

coverage/cmdline.py

@@ -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',


Suggested change

'', '--dump_signal', action='store', metavar='DUMP_SIGNAL',

'', '--dump-signal', action='store', metavar='DUMP_SIGNAL',

Options use hyphens, not underscores.

nedbat · 2025-07-12T11:35:56Z

coverage/cmdline.py

@@ -227,7 +229,15 @@ class Opts:
        "", "--version", action="store_true",
        help="Display version information and exit.",
    )
-
+    dump_signal = optparse.make_option(


Overall, I think this should be called "save signal" instead of "dump signal" throughout.

These make_option definitions are in rough alphabetical order, so this should be further up.

nedbat · 2025-07-12T11:38:02Z

coverage/cmdline.py

@@ -525,6 +536,7 @@ def get_prog_name(self) -> str:
            Opts.parallel_mode,
            Opts.source,
            Opts.timid,
+            Opts.dump_signal,


Keep these items alphabetized.

nedbat · 2025-07-12T11:39:40Z

Thanks for this! I want to have tests for this feature. test_process.py has some tests you could use as models, or I could give you some suggestions.

* Set options in alphabetical order * Rename "dump-signal" to "save-signal" Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g · 2025-07-12T16:36:39Z

Thanks for this! I want to have tests for this feature. test_process.py has some tests you could use as models, or I could give you some suggestions.

Hi,
First, I want to thank you for your great work and support for the Python coverage utility.
I don't see any option to create a test within the current environment. From what I understand, the test for the new feature should send a signal during the execution of the target script, but I haven't found this capability in the existing test examples or infrastructure. I would appreciate your suggestions on how to implement the test for the new feature.

Thanks.

nedbat · 2025-07-12T16:36:54Z

Thanks, what are your thoughts on a test? Let me know how far you want to take this, I can take it over when you want.

ark-g · 2025-07-12T16:45:26Z

I think that test should run some script with 2 stages.

    def test_save_signal(self) -> None:
        test_file = "dummy_hello.py"
        self.make_file(test_file, """\
            import time
            for i in range(10):
              time.sleep(1)
              if i < 5:
                print(f'{i:02d} Hello from the main script!')
              else:
                print(f'0x{i:02x} Hello X!')
            print('Done and goodbye')
            """)
        dummy_prc = self.run_command(f"coverage run --signal-save USR1 {test_file}")
        <Send signal first time>
        <Make sure that report reflects expected coverage>
        <sleep 5 secs>
       <Send signal second time>
       <Make sure that report reflects expected coverage>
       <Sleep 6 secs>
       <Make sure that report reflects 100% coverage>

But for the above I need to run script in background and to communicate with the running script dynamically (to monitor it's output).
Current infrastructure doesn't support such an ability, AFAIU.
Let me know, please, how do you see this test ?

nedbat · 2025-07-12T17:30:37Z

The test would have to be something like that, but I don't want it to take 10 seconds. I think it would be enough to have two cases in the test: in both, start an infinite loop process with coverage run --save-signal=USR1. In both cases, we use kill -s KILL to end the process. In one case, that's all we do, and we see no .coverage file is created. In the other case, we use kill -s USR1 before the KILL, and we see that a .coverage file is created.

nedbat · 2025-07-12T17:31:33Z

BTW, we also need to do the right thing on Windows. I think it's best to add "not on Windows" to the option help, and print an error if it's used on Windows. The test should check this also.

ark-g · 2025-07-12T18:58:48Z

The test would have to be something like that, but I don't want it to take 10 seconds. I think it would be enough to have two cases in the test: in both, start an infinite loop process with coverage run --save-signal=USR1. In both cases, we use kill -s KILL to end the process. In one case, that's all we do, and we see no .coverage file is created. In the other case, we use kill -s USR1 before the KILL, and we see that a .coverage file is created.

Do you have an example how to initiate infinite loop process in existing test infrastructure or I should use Subprocess module in the test ?

Signed-off-by: Arkady Gilinsky <[email protected]>

optparse catches the problem of an incorrect signal name, we don't need to.

ark-g · 2025-07-13T17:28:23Z

The test would have to be something like that, but I don't want it to take 10 seconds. I think it would be enough to have two cases in the test: in both, start an infinite loop process with coverage run --save-signal=USR1. In both cases, we use kill -s KILL to end the process. In one case, that's all we do, and we see no .coverage file is created. In the other case, we use kill -s USR1 before the KILL, and we see that a .coverage file is created.

Do you have an example how to initiate infinite loop process in existing test infrastructure or I should use Subprocess module in the test ?

I do not see much more purpose on the second test (with only KILL signal), but as you wish ... ;)

Signed-off-by: Arkady Gilinsky <[email protected]>

nedbat · 2025-07-13T23:22:15Z

Did you see this pull request? ark-g#1 It has some other changes for the code in cmdline.py. I wanted the test without the signal to show that the signal is needed to get the data file.

ark-g · 2025-07-14T03:38:50Z

Did you see this pull request? ark-g#1 It has some other changes for the code in cmdline.py. I wanted the test without the signal to show that the signal is needed to get the data file.

I think that the first test is also demonstrating this fact, since the final coverage report doesn't include the line that is sending KILL signal, but does include the line with USR1 signal.

Do you think that I can merge this PR ?

nedbat · 2025-07-15T12:18:05Z

I want you to take the changes I gave you in the pull request in your repo.

ark-g · 2025-07-17T12:45:12Z

I want you to take the changes I gave you in the pull request in your repo.

Now half of tests failed

nedbat · 2025-07-17T17:42:00Z

You need to merge the pull request in your repo. I can't do it, and there will be conflicts to resolve.

add tests

Signed-off-by: Arkady Gilinsky <[email protected]>

nedbat · 2025-07-19T11:00:42Z

tests/test_process.py

@@ -687,6 +716,51 @@ def test_module_name(self) -> None:
        out = self.run_command("python -m coverage")
        assert "Use 'coverage help' for help" in out

+    @pytest.mark.skipif(env.WINDOWS, reason="This test is not for Windows")
+    def test_save_signal_usr1(self) -> None:


I think maybe we don't need this test since test_save_signal covers it? Same for test_save_signal_kill, though maybe there's some subtlety I'm overlooking?

In general I agree, but the test_save_signal_usr1 is more precise and check conditions more tight, so I would leave it. Regarding test_save_signal_kill I will remove it since looks like we're both agree that it is redundant.

nedbat · 2025-07-19T11:01:12Z

Let me know when you are ready to merge.

Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g · 2025-07-19T12:24:24Z

Let me know when you are ready to merge.

Looks like all done and we are ready to merge

nedbat · 2025-07-19T22:28:25Z

Thanks for all the work! I rebased and combined commits, and landed them at commit 43bf46b.

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

35233a5

Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g force-pushed the master branch from bad12d2 to 35233a5 Compare July 12, 2025 06:22

nedbat requested changes Jul 12, 2025

View reviewed changes

misc: Changes per pull request

cd2a914

* Set options in alphabetical order * Rename "dump-signal" to "save-signal" Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g and others added 3 commits July 12, 2025 22:02

docs: Update - save signal doesn't work on Windows

b4f3467

Signed-off-by: Arkady Gilinsky <[email protected]>

simplify and test --save-signal handling

0858fb0

optparse catches the problem of an incorrect signal name, we don't need to.

Merge branch 'master' into nedbat/more-1998

b2b23c4

test: Add test cases for signal dump

5d0acca

Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g force-pushed the master branch from c18d5db to 5d0acca Compare July 13, 2025 17:34

test: a test for --save-signal

a89c789

ark-g force-pushed the master branch from 4c79987 to 5d0acca Compare July 19, 2025 08:39

ark-g added 3 commits July 19, 2025 11:39

Merge pull request #1 from nedbat/nedbat/more-1998

3f8ef2f

add tests

Merge branch 'master' into master

824e788

test: Rename send signal test functons

f3bcee1

Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g force-pushed the master branch 3 times, most recently from 556c4a1 to ff696ab Compare July 19, 2025 09:49

ark-g force-pushed the master branch 2 times, most recently from a454b9a to 7429db6 Compare July 19, 2025 10:02

Update signal test functions

ed22d06

Signed-off-by: Arkady Gilinsky <[email protected]>

ark-g force-pushed the master branch from 7429db6 to ed22d06 Compare July 19, 2025 10:06

nedbat reviewed Jul 19, 2025

View reviewed changes

ark-g added 2 commits July 19, 2025 14:40

test: Remove redundant test

31920ff

Signed-off-by: Arkady Gilinsky <[email protected]>

docs: Fix docs

ce9dfe9

Signed-off-by: Arkady Gilinsky <[email protected]>

nedbat added a commit that referenced this pull request Jul 19, 2025

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

43bf46b

nedbat closed this Jul 19, 2025

	'', '--dump_signal', action='store', metavar='DUMP_SIGNAL',
	'', '--dump-signal', action='store', metavar='DUMP_SIGNAL',

Uh oh!

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

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

Uh oh!

Conversation

ark-g commented Jul 12, 2025

Uh oh!

nedbat left a comment

Choose a reason for hiding this comment

Uh oh!

nedbat Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

nedbat Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

nedbat Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

nedbat Jul 12, 2025

Choose a reason for hiding this comment

Uh oh!

nedbat commented Jul 12, 2025

Uh oh!

ark-g commented Jul 12, 2025

Uh oh!

nedbat commented Jul 12, 2025

Uh oh!

ark-g commented Jul 12, 2025

Uh oh!

nedbat commented Jul 12, 2025

Uh oh!

nedbat commented Jul 12, 2025

Uh oh!

ark-g commented Jul 12, 2025

Uh oh!

ark-g commented Jul 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nedbat commented Jul 13, 2025

Uh oh!

ark-g commented Jul 14, 2025

Uh oh!

nedbat commented Jul 15, 2025

Uh oh!

ark-g commented Jul 17, 2025

Uh oh!

nedbat commented Jul 17, 2025

Uh oh!

nedbat Jul 19, 2025

Choose a reason for hiding this comment

Uh oh!

ark-g Jul 19, 2025

Choose a reason for hiding this comment

Uh oh!

nedbat commented Jul 19, 2025

Uh oh!

ark-g commented Jul 19, 2025

Uh oh!

nedbat commented Jul 19, 2025

Uh oh!

Uh oh!

ark-g commented Jul 13, 2025 •

edited

Loading