From 9402ea63f7897ecda7036f667949ad17f4208e5b Mon Sep 17 00:00:00 2001
From: Laurie O <laurie_opperman@hotmail.com>
Date: Mon, 26 Feb 2024 02:53:21 +1000
Subject: [PATCH] gh-96471: Correct docs for queue shutdown (#115838)

---
 Doc/library/queue.rst |  7 +++----
 Lib/queue.py          | 12 +++++-------
 2 files changed, 8 insertions(+), 11 deletions(-)

diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index 1421fc2e552..f2a6dbf589f 100644
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -187,11 +187,12 @@ fully processed by daemon consumer threads.
    processed (meaning that a :meth:`task_done` call was received for every item
    that had been :meth:`put` into the queue).
 
+   ``shutdown(immediate=True)`` calls :meth:`task_done` for each remaining item
+   in the queue.
+
    Raises a :exc:`ValueError` if called more times than there were items placed in
    the queue.
 
-   Raises :exc:`ShutDown` if the queue has been shut down immediately.
-
 
 .. method:: Queue.join()
 
@@ -202,8 +203,6 @@ fully processed by daemon consumer threads.
    indicate that the item was retrieved and all work on it is complete.  When the
    count of unfinished tasks drops to zero, :meth:`join` unblocks.
 
-   Raises :exc:`ShutDown` if the queue has been shut down immediately.
-
 
 Example of how to wait for enqueued tasks to be completed::
 
diff --git a/Lib/queue.py b/Lib/queue.py
index 467ff4fcecb..18fad8df08e 100644
--- a/Lib/queue.py
+++ b/Lib/queue.py
@@ -72,10 +72,11 @@ class Queue:
         have been processed (meaning that a task_done() call was received
         for every item that had been put() into the queue).
 
+        shutdown(immediate=True) calls task_done() for each remaining item in
+        the queue.
+
         Raises a ValueError if called more times than there were items
         placed in the queue.
-
-        Raises ShutDown if the queue has been shut down immediately.
         '''
         with self.all_tasks_done:
             unfinished = self.unfinished_tasks - 1
@@ -93,8 +94,6 @@ class Queue:
         to indicate the item was retrieved and all work on it is complete.
 
         When the count of unfinished tasks drops to zero, join() unblocks.
-
-        Raises ShutDown if the queue has been shut down immediately.
         '''
         with self.all_tasks_done:
             while self.unfinished_tasks:
@@ -227,18 +226,17 @@ class Queue:
         return self.get(block=False)
 
     def shutdown(self, immediate=False):
-        '''Shut-down the queue, making queue gets and puts raise.
+        '''Shut-down the queue, making queue gets and puts raise ShutDown.
 
         By default, gets will only raise once the queue is empty. Set
         'immediate' to True to make gets raise immediately instead.
 
         All blocked callers of put() will be unblocked, and also get()
-        and join() if 'immediate'. The ShutDown exception is raised.
+        and join() if 'immediate'.
         '''
         with self.mutex:
             self.is_shutdown = True
             if immediate:
-                n_items = self._qsize()
                 while self._qsize():
                     self._get()
                     if self.unfinished_tasks > 0: