Rename STATUS_IGNORED to TASK_STATUS_IGNORED

docs/source/reference-core.rst

@@ -924,13 +924,13 @@ Nursery objects provide the following interface:
 
       The conventional way to define ``async_fn`` is like::
 
-         async def async_fn(arg1, arg2, *, task_status=trio.STATUS_IGNORED):
+         async def async_fn(arg1, arg2, *, task_status=trio.TASK_STATUS_IGNORED):
              ...
              task_status.started()
              ...
 
-      :attr:`trio.STATUS_IGNORED` is a special global object with a
-      do-nothing ``started`` method. This way your function supports
+      :attr:`trio.TASK_STATUS_IGNORED` is a special global object with
+      a do-nothing ``started`` method. This way your function supports
       being called either like ``await nursery.start(async_fn, arg1,
       arg2)`` or directly like ``await async_fn(arg1, arg2)``, and
       either way it can call ``task_status.started()`` without
@@ -974,7 +974,7 @@ Nursery objects provide the following interface:
       :class:`~trio.hazmat.Task` objects which are still running.
 
 
-.. attribute:: STATUS_IGNORED
+.. attribute:: TASK_STATUS_IGNORED
 
    See :meth:`~The nursery interface.start`.
 

trio/__init__.py

@@ -95,6 +95,13 @@
         _deprecate.DeprecatedAttribute(
             hazmat.current_statistics, "0.2.0", issue=317
         ),
+    # STATUS_IGNORED never made it into a release, but I think people were
+    # using while it was in the dev version, so we might as well provide an
+    # alias for a little while.
+    "STATUS_IGNORED":
+        _deprecate.DeprecatedAttribute(
+            TASK_STATUS_IGNORED, "0.2.0", issue=353
+        ),
 }
 
 _deprecate.enable_attribute_deprecations(hazmat.__name__)

trio/_core/_run.py

@@ -46,7 +46,8 @@
 __all__ = [
     "Task", "run", "open_nursery", "open_cancel_scope", "checkpoint",
     "current_call_soon_thread_and_signal_safe", "current_task",
-    "current_effective_deadline", "checkpoint_if_cancelled", "STATUS_IGNORED"
+    "current_effective_deadline", "checkpoint_if_cancelled",
+    "TASK_STATUS_IGNORED"
 ]
 
 GLOBAL_RUN_CONTEXT = threading.local()
@@ -1540,15 +1541,15 @@ def run_impl(runner, async_fn, args):
 ################################################################
 
 
-class _StatusIgnored:
+class _TaskStatusIgnored:
     def __repr__(self):
-        return "STATUS_IGNORED"
+        return "TASK_STATUS_IGNORED"
 
     def started(self, value=None):
         pass
 
 
-STATUS_IGNORED = _StatusIgnored()
+TASK_STATUS_IGNORED = _TaskStatusIgnored()
 
 
 def current_task():

trio/_core/tests/test_run.py

@@ -1744,7 +1744,9 @@ async def no_args():  # pragma: no cover
         with pytest.raises(TypeError):
             await nursery.start(no_args)
 
-    async def sleep_then_start(seconds, *, task_status=_core.STATUS_IGNORED):
+    async def sleep_then_start(
+        seconds, *, task_status=_core.TASK_STATUS_IGNORED
+    ):
         repr(task_status)  # smoke test
         await sleep(seconds)
         task_status.started(seconds)
@@ -1762,13 +1764,14 @@ async def sleep_then_start(seconds, *, task_status=_core.STATUS_IGNORED):
             assert len(nursery.child_tasks) == 1
         assert _core.current_time() - t0 == 2 * seconds
 
-    # Make sure STATUS_IGNORED works so task function can be called directly
+    # Make sure TASK_STATUS_IGNORED works so task function can be called
+    # directly
     t0 = _core.current_time()
     await sleep_then_start(3)
     assert _core.current_time() - t0 == 2 * 3
 
     # calling started twice
-    async def double_started(task_status=_core.STATUS_IGNORED):
+    async def double_started(task_status=_core.TASK_STATUS_IGNORED):
         task_status.started()
         with pytest.raises(RuntimeError):
             task_status.started()
@@ -1777,15 +1780,15 @@ async def double_started(task_status=_core.STATUS_IGNORED):
         await nursery.start(double_started)
 
     # child crashes before calling started -> error comes out of .start()
-    async def raise_keyerror(task_status=_core.STATUS_IGNORED):
+    async def raise_keyerror(task_status=_core.TASK_STATUS_IGNORED):
         raise KeyError("oops")
 
     async with _core.open_nursery() as nursery:
         with pytest.raises(KeyError):
             await nursery.start(raise_keyerror)
 
     # child exiting cleanly before calling started -> triggers a RuntimeError
-    async def nothing(task_status=_core.STATUS_IGNORED):
+    async def nothing(task_status=_core.TASK_STATUS_IGNORED):
         return
 
     async with _core.open_nursery() as nursery:
@@ -1796,7 +1799,7 @@ async def nothing(task_status=_core.STATUS_IGNORED):
     # if the call to start() is cancelled, then the call to started() does
     # nothing -- the child keeps executing under start(). The value it passed
     # is ignored; start() raises Cancelled.
-    async def just_started(task_status=_core.STATUS_IGNORED):
+    async def just_started(task_status=_core.TASK_STATUS_IGNORED):
         task_status.started("hi")
 
     async with _core.open_nursery() as nursery:
@@ -1807,7 +1810,9 @@ async def just_started(task_status=_core.STATUS_IGNORED):
 
     # and if after the no-op started(), the child crashes, the error comes out
     # of start()
-    async def raise_keyerror_after_started(task_status=_core.STATUS_IGNORED):
+    async def raise_keyerror_after_started(
+        task_status=_core.TASK_STATUS_IGNORED
+    ):
         task_status.started()
         raise KeyError("whoopsiedaisy")
 
@@ -1845,15 +1850,15 @@ async def test_task_nursery_stack():
 async def test_nursery_start_with_cancelled_nursery():
     # This function isn't testing task_status, it's using task_status as a
     # convenient way to get a nursery that we can test spawning stuff into.
-    async def setup_nursery(task_status=_core.STATUS_IGNORED):
+    async def setup_nursery(task_status=_core.TASK_STATUS_IGNORED):
         async with _core.open_nursery() as nursery:
             task_status.started(nursery)
             await sleep_forever()
 
     # Calls started() while children are asleep, so we can make sure
     # that the cancellation machinery notices and aborts when a sleeping task
     # is moved into a cancelled scope.
-    async def sleeping_children(fn, *, task_status=_core.STATUS_IGNORED):
+    async def sleeping_children(fn, *, task_status=_core.TASK_STATUS_IGNORED):
         async with _core.open_nursery() as nursery:
             nursery.start_soon(sleep_forever)
             nursery.start_soon(sleep_forever)
@@ -1876,7 +1881,7 @@ async def sleeping_children(fn, *, task_status=_core.STATUS_IGNORED):
 
 
 async def test_nursery_start_keeps_nursery_open(autojump_clock):
-    async def sleep_a_bit(task_status=_core.STATUS_IGNORED):
+    async def sleep_a_bit(task_status=_core.TASK_STATUS_IGNORED):
         await sleep(2)
         task_status.started()
         await sleep(3)
@@ -1898,7 +1903,7 @@ async def sleep_a_bit(task_status=_core.STATUS_IGNORED):
 
     # Check that it still works even if the task that the nursery is waiting
     # for ends up crashing, and never actually enters the nursery.
-    async def sleep_then_crash(task_status=_core.STATUS_IGNORED):
+    async def sleep_then_crash(task_status=_core.TASK_STATUS_IGNORED):
         await sleep(7)
         raise KeyError
 

trio/_highlevel_open_tcp_listeners.py

@@ -141,7 +141,7 @@ async def serve_tcp(
     host=None,
     backlog=None,
     handler_nursery=None,
-    task_status=trio.STATUS_IGNORED
+    task_status=trio.TASK_STATUS_IGNORED
 ):
     """Listen for incoming TCP connections, and for each one start a task
     running ``handler(stream)``.

trio/_highlevel_serve_listeners.py

@@ -55,7 +55,7 @@ async def serve_listeners(
     listeners,
     *,
     handler_nursery=None,
-    task_status=trio.STATUS_IGNORED
+    task_status=trio.TASK_STATUS_IGNORED
 ):
     """Listen for incoming connections on ``listeners``, and for each one
     start a task running ``handler(stream)``.

trio/_highlevel_ssl_helpers.py

@@ -108,7 +108,7 @@ async def serve_ssl_over_tcp(
     https_compatible=False,
     backlog=None,
     handler_nursery=None,
-    task_status=trio.STATUS_IGNORED
+    task_status=trio.TASK_STATUS_IGNORED
 ):
     """Listen for incoming TCP connections, and for each one start a task
     running ``handler(stream)``.

trio/_toplevel_core_reexports.py

@@ -25,7 +25,7 @@
     "open_nursery",
     "open_cancel_scope",
     "current_effective_deadline",
-    "STATUS_IGNORED",
+    "TASK_STATUS_IGNORED",
     "current_time",
     "current_instruments",
     "TaskLocal",

trio/tests/test_highlevel_serve_listeners.py

@@ -124,7 +124,7 @@ async def handler(stream):
     class Done(Exception):
         pass
 
-    async def connection_watcher(*, task_status=trio.STATUS_IGNORED):
+    async def connection_watcher(*, task_status=trio.TASK_STATUS_IGNORED):
         async with trio.open_nursery() as nursery:
             task_status.started(nursery)
             await wait_all_tasks_blocked()