From: andreuu-tsai <32549555+andreuu-tsai@users.noreply.github.com>
Date: Sat, 21 Mar 2026 12:32:28 +0000 (+0800)
Subject: gh-138234: clarify returncode behavior for subprocesses created with `shell=True... 
X-Git-Tag: v3.15.0a8~224
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8a531f89df8f8bf4c4fe395f9edcdc19852bdf1c;p=thirdparty%2FPython%2Fcpython.git

gh-138234: clarify returncode behavior for subprocesses created with `shell=True` (#138536)

Co-authored-by: Kumar Aditya <kumaraditya@python.org>
---

diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index 9416c758e51d..cb9ddc08a64d 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -311,8 +311,16 @@ their completion.
 
       A ``None`` value indicates that the process has not terminated yet.
 
-      A negative value ``-N`` indicates that the child was terminated
-      by signal ``N`` (POSIX only).
+      For processes created with :func:`~asyncio.create_subprocess_exec`, a negative
+      value ``-N`` indicates that the child was terminated by signal ``N``
+      (POSIX only).
+
+      For processes created with :func:`~asyncio.create_subprocess_shell`, the
+      return code reflects the exit status of the shell itself (e.g. ``/bin/sh``),
+      which may map signals to codes such as ``128+N``. See the
+      documentation of the shell (for example, the Bash manual's Exit Status)
+      for details.
+
 
 
 .. _asyncio-subprocess-threads:
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index def6d58eabbe..9e261a0ca039 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -964,6 +964,11 @@ Reassigning them to new values is unsupported:
    A negative value ``-N`` indicates that the child was terminated by signal
    ``N`` (POSIX only).
 
+   When ``shell=True``, the return code reflects the exit status of the shell
+   itself (e.g. ``/bin/sh``), which may map signals to codes such as
+   ``128+N``. See the documentation of the shell (for example, the Bash
+   manual's Exit Status) for details.
+
 
 Windows Popen Helpers
 ---------------------