Deprecate Queue.join and Queue.task_done

See python-triogh-321.

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_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()