Deprecate Queue.join and Queue.task_done

trio/_deprecate.py

@@ -44,7 +44,9 @@ def _stringify(thing):
 def warn_deprecated(thing, version, *, issue, instead, stacklevel=2):
     stacklevel += 1
     msg = "{} is deprecated since Trio {}".format(_stringify(thing), version)
-    if instead is not None:
+    if instead is None:
+        msg += " with no replacement"
+    else:
         msg += "; use {} instead".format(_stringify(instead))
     if issue is not None:
         msg += " ({})".format(_url_for_issue(issue))

trio/_sync.py

@@ -5,6 +5,7 @@
 
 from . import _core
 from ._util import aiter_compat
+from ._deprecate import deprecated
 
 __all__ = [
     "Event",
@@ -810,8 +811,8 @@ class Queue:
     This class is generally modelled after :class:`queue.Queue`, but with the
     major difference that it is always bounded.
 
-    A :class:`Queue` object can be used as an asynchronous iterator, that
-    dequeues objects one at a time. I.e., these two loops are equivalent::
+    A :class:`Queue` object can be used as an asynchronous iterator that
+    dequeues objects one at a time. That is, these two loops are equivalent::
 
        async for obj in queue:
            ...
@@ -935,6 +936,7 @@ async def get(self):
         await self._get_semaphore.acquire()
         return self._get_protected()
 
+    @deprecated("0.2.0", issue=321, instead=None)
     @_core.enable_ki_protection
     def task_done(self):
         """Decrement the count of unfinished work.
@@ -949,6 +951,7 @@ def task_done(self):
         if self._unprocessed == 0:
             self._join_lot.unpark_all()
 
+    @deprecated("0.2.0", issue=321, instead=None)
     async def join(self):
         """Block until the count of unfinished work reaches zero.
 
@@ -978,8 +981,6 @@ def statistics(self):
           :meth:`put` method.
         * ``tasks_waiting_get``: The number of tasks blocked on this queue's
           :meth:`get` method.
-        * ``tasks_waiting_join``: The number of tasks blocked on this queue's
-          :meth:`join` method.
 
         """
         return _QueueStats(

trio/tests/test_deprecate.py

@@ -44,6 +44,7 @@ def test_warn_deprecated_no_instead_or_issue(recwarn_always):
     assert len(recwarn_always) == 1
     got = recwarn_always.pop(TrioDeprecationWarning)
     assert "water is deprecated" in got.message.args[0]
+    assert "no replacement" in got.message.args[0]
     assert "Trio 1.3" in got.message.args[0]
 
 

trio/tests/test_sync.py

@@ -403,7 +403,7 @@ async def test_Queue():
     assert q.empty()
 
 
-async def test_Queue_join():
+async def test_Queue_join(recwarn):
     q = Queue(2)
     with assert_checkpoints():
         await q.join()
@@ -452,7 +452,8 @@ async def consumer():
         nursery.start_soon(consumer)
 
 
-async def test_Queue_statistics():
+# XX remove the 'recwarn' fixture after join is removed
+async def test_Queue_statistics(recwarn):
     q = Queue(3)
     q.put_nowait(1)
     statistics = q.statistics()