From c5a3e080dd96ee44f71004bdaf4099d42458579a Mon Sep 17 00:00:00 2001
From: Nadeshiko Manju <me@manjusaka.me>
Date: Mon, 5 May 2025 09:15:31 +0800
Subject: [PATCH] gh-133089: Use original timeout value for `TimeoutExpired`
 when the func `subprocess.run` is called with a timeout (GH-133103) (cherry
 picked from commit 2bbcaedb75942389dacb51866948f40de5951c9c)

Co-authored-by: Nadeshiko Manju <me@manjusaka.me>
Signed-off-by: Manjusaka <me@manjusaka.me>
Co-authored-by: Gregory P. Smith <greg@krypto.org>
---
 Doc/library/subprocess.rst                     | 18 ++++++++++++++++++
 Lib/subprocess.py                              | 14 ++++++++++----
 Lib/test/test_subprocess.py                    | 14 ++++++++++++++
 ...5-04-29-02-23-04.gh-issue-133089.8Jy1ZS.rst |  4 ++++
 4 files changed, 46 insertions(+), 4 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Library/2025-04-29-02-23-04.gh-issue-133089.8Jy1ZS.rst

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index 59c98e867ff42d..4728b0df6eeebc 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -1591,6 +1591,24 @@ handling consistency are valid for these functions.
 Notes
 -----
 
+.. _subprocess-timeout-behavior:
+
+Timeout Behavior
+^^^^^^^^^^^^^^^^
+
+When using the ``timeout`` parameter in functions like :func:`run`,
+:meth:`Popen.wait`, or :meth:`Popen.communicate`,
+users should be aware of the following behaviors:
+
+1. **Process Creation Delay**: The initial process creation itself cannot be interrupted
+   on many platform APIs. This means that even when specifying a timeout, you are not
+   guaranteed to see a timeout exception until at least after however long process
+   creation takes.
+
+2. **Extremely Small Timeout Values**: Setting very small timeout values (such as a few
+   milliseconds) may result in almost immediate :exc:`TimeoutExpired` exceptions because
+   process creation and system scheduling inherently require time.
+
 .. _converting-argument-sequence:
 
 Converting an argument sequence to a string on Windows
diff --git a/Lib/subprocess.py b/Lib/subprocess.py
index 4a9a64e5577989..ffc3fdf6afb5c7 100644
--- a/Lib/subprocess.py
+++ b/Lib/subprocess.py
@@ -1237,8 +1237,11 @@ def communicate(self, input=None, timeout=None):
 
             finally:
                 self._communication_started = True
-
-            sts = self.wait(timeout=self._remaining_time(endtime))
+            try:
+                sts = self.wait(timeout=self._remaining_time(endtime))
+            except TimeoutExpired as exc:
+                exc.timeout = timeout
+                raise
 
         return (stdout, stderr)
 
@@ -2147,8 +2150,11 @@ def _communicate(self, input, endtime, orig_timeout):
                                 selector.unregister(key.fileobj)
                                 key.fileobj.close()
                             self._fileobj2output[key.fileobj].append(data)
-
-            self.wait(timeout=self._remaining_time(endtime))
+            try:
+                self.wait(timeout=self._remaining_time(endtime))
+            except TimeoutExpired as exc:
+                exc.timeout = orig_timeout
+                raise
 
             # All data exchanged.  Translate lists into strings.
             if stdout is not None:
diff --git a/Lib/test/test_subprocess.py b/Lib/test/test_subprocess.py
index 7d72737e9cb066..ba02b1a1c011a1 100644
--- a/Lib/test/test_subprocess.py
+++ b/Lib/test/test_subprocess.py
@@ -161,6 +161,20 @@ def test_call_timeout(self):
                           [sys.executable, "-c", "while True: pass"],
                           timeout=0.1)
 
+    def test_timeout_exception(self):
+        try:
+            subprocess.run(['echo', 'hi'], timeout = -1)
+        except subprocess.TimeoutExpired as e:
+            self.assertIn("-1 seconds", str(e))
+        else:
+            self.fail("Expected TimeoutExpired exception not raised")
+        try:
+            subprocess.run(['echo', 'hi'], timeout = 0)
+        except subprocess.TimeoutExpired as e:
+            self.assertIn("0 seconds", str(e))
+        else:
+            self.fail("Expected TimeoutExpired exception not raised")
+
     def test_check_call_zero(self):
         # check_call() function with zero return code
         rc = subprocess.check_call(ZERO_RETURN_CMD)
diff --git a/Misc/NEWS.d/next/Library/2025-04-29-02-23-04.gh-issue-133089.8Jy1ZS.rst b/Misc/NEWS.d/next/Library/2025-04-29-02-23-04.gh-issue-133089.8Jy1ZS.rst
new file mode 100644
index 00000000000000..8c4257a12a90e5
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2025-04-29-02-23-04.gh-issue-133089.8Jy1ZS.rst
@@ -0,0 +1,4 @@
+Use original timeout value for :exc:`subprocess.TimeoutExpired`
+when the func :meth:`subprocess.run` is called with a timeout
+instead of sometimes a confusing partial remaining time out value
+used internally on the final ``wait()``.