From fbb841a6bf8fec5d49b00a8756278f77dcdcb210 Mon Sep 17 00:00:00 2001 From: "Nathaniel J. Smith" Date: Mon, 27 Nov 2017 21:36:56 -0800 Subject: [PATCH] Rename STATUS_IGNORED to TASK_STATUS_IGNORED The asymmetry in task_status=trio.STATUS_IGNORED is bugging me too much. I gotta change it. What to change it to? task_status=trio.TASK_STATUS_IGNORED is kind of long -- 36 characters -- and likely to make 80-character lines wrap. But the old one was 31 characters, which is already likely to make 80-character lines wrap, and I haven't had any better ideas. I don't want to make it status=STATUS_IGNORED, because then we're claiming the kwarg "status" in every Trio server function, which seems just a little too generic. task_status is more unique and I think better for attaching this special convention to. I thought about task_status=NO_TASK_STATUS, but that feels weird. It's not that the task has no status, it's that the caller is ignoring that status. I guess we could switch to something like status_reporter=trio.NO_STATUS_REPORTER but that's even *longer* (39 characters), and not really any clearer. --- docs/source/reference-core.rst | 8 +++--- trio/__init__.py | 7 +++++ trio/_core/_run.py | 9 ++++--- trio/_core/tests/test_run.py | 27 ++++++++++++-------- trio/_highlevel_open_tcp_listeners.py | 2 +- trio/_highlevel_serve_listeners.py | 2 +- trio/_highlevel_ssl_helpers.py | 2 +- trio/_toplevel_core_reexports.py | 2 +- trio/tests/test_highlevel_serve_listeners.py | 2 +- 9 files changed, 37 insertions(+), 24 deletions(-) diff --git a/docs/source/reference-core.rst b/docs/source/reference-core.rst index 86ea393ca3..25e583353f 100644 --- a/docs/source/reference-core.rst +++ b/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`. diff --git a/trio/__init__.py b/trio/__init__.py index 1028fb73bc..78de81400f 100644 --- a/trio/__init__.py +++ b/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__) diff --git a/trio/_core/_run.py b/trio/_core/_run.py index d1a139d83d..0e37b2a080 100644 --- a/trio/_core/_run.py +++ b/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(): diff --git a/trio/_core/tests/test_run.py b/trio/_core/tests/test_run.py index 1ee8b0f13e..c262a66906 100644 --- a/trio/_core/tests/test_run.py +++ b/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,7 +1780,7 @@ 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: @@ -1785,7 +1788,7 @@ async def raise_keyerror(task_status=_core.STATUS_IGNORED): 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,7 +1850,7 @@ 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() @@ -1853,7 +1858,7 @@ async def setup_nursery(task_status=_core.STATUS_IGNORED): # 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 diff --git a/trio/_highlevel_open_tcp_listeners.py b/trio/_highlevel_open_tcp_listeners.py index 4ac87686b4..6f3a483c26 100644 --- a/trio/_highlevel_open_tcp_listeners.py +++ b/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)``. diff --git a/trio/_highlevel_serve_listeners.py b/trio/_highlevel_serve_listeners.py index 0be6467199..d5efe87f0f 100644 --- a/trio/_highlevel_serve_listeners.py +++ b/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)``. diff --git a/trio/_highlevel_ssl_helpers.py b/trio/_highlevel_ssl_helpers.py index c2c5033701..1d7b80d708 100644 --- a/trio/_highlevel_ssl_helpers.py +++ b/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)``. diff --git a/trio/_toplevel_core_reexports.py b/trio/_toplevel_core_reexports.py index f4aabec321..c6fee116ec 100644 --- a/trio/_toplevel_core_reexports.py +++ b/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", diff --git a/trio/tests/test_highlevel_serve_listeners.py b/trio/tests/test_highlevel_serve_listeners.py index 13b87a1a57..c72f350618 100644 --- a/trio/tests/test_highlevel_serve_listeners.py +++ b/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()