From ec9388b718ebfcec0971f3be5ed785e4c657120d Mon Sep 17 00:00:00 2001
From: Vyron Vasileiadis <hi@fedonman.com>
Date: Fri, 7 Aug 2026 15:19:07 +0300
Subject: [PATCH] gh-153970: Fix str() of CalledProcessError when returncode is
 not an integer (#153971)

CalledProcessError.__str__() fell through to a branch that formats the
return code with %d, which raises TypeError when returncode is None.

(cherry picked from commit 7c653e2540cbe4180efb3bd83b63865a1f675650)
---
 Doc/library/subprocess.rst                             |  4 ++--
 Lib/subprocess.py                                      |  6 +++---
 Lib/test/test_subprocess.py                            | 10 ++++++++++
 .../2026-07-22-12-00-00.gh-issue-153970.Kq7Wn3.rst     |  3 +++
 4 files changed, 18 insertions(+), 5 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2026-07-22-12-00-00.gh-issue-153970.Kq7Wn3.rst

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index fe64daa3291d670..2a31213560c92d3 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -236,8 +236,8 @@ underlying :class:`Popen` interface can be used directly.
 
     .. attribute:: returncode
 
-        Exit status of the child process.  If the process exited due to a
-        signal, this will be the negative signal number.
+        Exit status of the child process, an integer.  If the process
+        exited due to a signal, this will be the negative signal number.
 
     .. attribute:: cmd
 
diff --git a/Lib/subprocess.py b/Lib/subprocess.py
index 5948cd841bc371c..4a956cd6d6ec0c8 100644
--- a/Lib/subprocess.py
+++ b/Lib/subprocess.py
@@ -143,7 +143,7 @@ def __init__(self, returncode, cmd, output=None, stderr=None):
         self.stderr = stderr
 
     def __str__(self):
-        if self.returncode and self.returncode < 0:
+        if isinstance(self.returncode, int) and self.returncode < 0:
             try:
                 return "Command '%s' died with %r." % (
                         self.cmd, signal.Signals(-self.returncode))
@@ -151,8 +151,8 @@ def __str__(self):
                 return "Command '%s' died with unknown signal %d." % (
                         self.cmd, -self.returncode)
         else:
-            return "Command '%s' returned non-zero exit status %d." % (
-                    self.cmd, self.returncode)
+            return (f"Command {self.cmd!r} returned non-zero "
+                    f"exit status {self.returncode}.")
 
     @property
     def stdout(self):
diff --git a/Lib/test/test_subprocess.py b/Lib/test/test_subprocess.py
index 89e0422efb3697f..13b7c7fdc43ca28 100644
--- a/Lib/test/test_subprocess.py
+++ b/Lib/test/test_subprocess.py
@@ -2450,6 +2450,16 @@ def test_CalledProcessError_str_non_zero(self):
         error_string = str(err)
         self.assertIn("non-zero exit status 2.", error_string)
 
+        # returncode which is not an integer, which happens for example when
+        # Popen is mocked: str() must not fail
+        for returncode in (None, "2", 2.5, [2]):
+            with self.subTest(returncode=returncode):
+                err = subprocess.CalledProcessError(returncode, "fake cmd")
+                self.assertEqual(
+                    str(err),
+                    f"Command 'fake cmd' returned non-zero "
+                    f"exit status {returncode}.")
+
     def test_preexec(self):
         # DISCLAIMER: Setting environment variables is *not* a good use
         # of a preexec_fn.  This is merely a test.
diff --git a/Misc/NEWS.d/next/Library/2026-07-22-12-00-00.gh-issue-153970.Kq7Wn3.rst b/Misc/NEWS.d/next/Library/2026-07-22-12-00-00.gh-issue-153970.Kq7Wn3.rst
new file mode 100644
index 000000000000000..def943b46b59420
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2026-07-22-12-00-00.gh-issue-153970.Kq7Wn3.rst
@@ -0,0 +1,3 @@
+Calling :func:`str` on a :exc:`subprocess.CalledProcessError` no longer
+raises :exc:`TypeError` when its :attr:`!returncode` is not an integer, such
+as ``None``.