wording

CHANGES.rst

@@ -16,7 +16,16 @@ Changes
 2.0.0 (2024-12-XX)
 ------------------
 
-- Implement .shutdown() for both sync and async APIs #720
+- Implement .shutdown(immediate=False) for both sync and async APIs #720
+
+  The change is not fully backward compatible:
+
+  1. If the queue is closed, ``janus.AsyncQueueShutDown`` and
+     ``janus.SyncQueueShutDown`` exceptions are raised instead of ``RuntimeError``.
+
+  2. Both sync and async ``.task_done()`` and ``.join()`` don't raise any exception
+     on queue shutdown/closing anymore; it is compatible with shutdown behavior
+     of stdlib sync and async queues.
 
 
 1.2.0 (2024-12-12)

janus/__init__.py

@@ -139,14 +139,17 @@ def _get_loop(self) -> asyncio.AbstractEventLoop:
         return loop
 
     def shutdown(self, immediate: bool = False) -> None:
-        """Shut-down the queue, making queue gets and puts raise ShutDown.
+        """Shut-down the queue, making queue gets and puts raise an exception.
 
         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() and get() will be unblocked. If
         'immediate', a task is marked as done for each item remaining in
         the queue, which may unblock callers of join().
+
+        The raise exception is SyncQueueShutDown for sync api and AsyncQueueShutDown
+        for async one.
         """
         with self._sync_mutex:
             self._is_shutdown = True
@@ -467,14 +470,17 @@ def get_nowait(self) -> T:
         return self.get(block=False)
 
     def shutdown(self, immediate: bool = False) -> None:
-        """Shut-down the queue, making queue gets and puts raise ShutDown.
+        """Shut-down the queue, making queue gets and puts raise an exception.
 
         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() and get() will be unblocked. If
         'immediate', a task is marked as done for each item remaining in
         the queue, which may unblock callers of join().
+
+        The raise exception is SyncQueueShutDown for sync api and AsyncQueueShutDown
+        for async one.
         """
         self._parent.shutdown(immediate)
 
@@ -675,14 +681,17 @@ async def join(self) -> None:
                         parent._async_tasks_done_waiting -= 1
 
     def shutdown(self, immediate: bool = False) -> None:
-        """Shut-down the queue, making queue gets and puts raise ShutDown.
+        """Shut-down the queue, making queue gets and puts raise an exception.
 
         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() and get() will be unblocked. If
         'immediate', a task is marked as done for each item remaining in
         the queue, which may unblock callers of join().
+
+        The raise exception is SyncQueueShutDown for sync api and AsyncQueueShutDown
+        for async one.
         """
         self._parent.shutdown(immediate)