Bug report

Bug description:

The docs for returncode state the following:

A negative value -N indicates that the child was terminated by signal N (POSIX only).

which does not technically require, but strongly suggest that processes terminated by signals will have a negative returncode corresponding to the signal. On some platforms (observed on Arch Linux and macOS, both using Python 3.13.7), this does indeed seem to be the case. On others it is not. The observed counterexample is Ubuntu using Python 3.12.3. There, returncode seems to be set to 128 + signal value. Technically, this does not violate the documented behavior, but it is very surprising. If that is intended behavior, the docs deserve a clear warning. My preference would be to mandate negative returncodes upon termination by signal in the docs and to adapt the code on non-conformant platforms accordingly.

Interestingly, asyncio.create_subprocess_exec has the expected behavior of consistently negative returncodes on the tested platforms, which increases my suspicion that there is indeed undesired behavior involved.

import asyncio async def repro(): proc = await asyncio.create_subprocess_shell("./sigint.sh") await proc.communicate() print(proc.returncode) assert proc.returncode == -2 asyncio.run(repro())

sigint.sh:

#!/bin/sh kill -2 $$

I created a repo to show the differences in GitHub's CI: https://github.com/danielrainer/python_signal_returncode_repro/actions/runs/17310888203

CPython versions tested on:

3.13, 3.12

Operating systems tested on:

Linux, macOS

Linked PRs

• gh-138234: clarify returncode behavior for subprocess_exec vs subprocess_shell #138536