Reapply `.devx.debug` mod-name change to ipc-server lost during rebase..

" from tail of `BoxedMaybeException.pformat()`

examples/debugging/subactor_bp_in_ctx.py

@@ -33,11 +33,8 @@ async def just_bp(
 
 
 async def main():
-
     async with tractor.open_nursery(
         debug_mode=True,
-        enable_transports=['uds'],
-        loglevel='devx',
     ) as n:
         p = await n.start_actor(
             'bp_boi',

tests/devx/test_debugger.py

@@ -10,14 +10,10 @@ TODO:
     - wonder if any of it'll work on OS X?
 
 """
-from __future__ import annotations
 from functools import partial
 import itertools
 import platform
 import time
-from typing import (
-    TYPE_CHECKING,
-)
 
 import pytest
 from pexpect.exceptions import (
@@ -38,9 +34,6 @@ from .conftest import (
     assert_before,
 )
 
-if TYPE_CHECKING:
-    from ..conftest import PexpectSpawner
-
 # TODO: The next great debugger audit could be done by you!
 # - recurrent entry to breakpoint() from single actor *after* and an
 #   error in another task?
@@ -1070,88 +1063,6 @@ def test_shield_pause(
     child.expect(EOF)
 
 
-@pytest.mark.parametrize(
-    'quit_early', [False, True]
-)
-def test_ctxep_pauses_n_maybe_ipc_breaks(
-    spawn: PexpectSpawner,
-    quit_early: bool,
-):
-    '''
-    Audit generator embedded `.pause()`es from within a `@context`
-    endpoint with a chan close at the end, requiring that ctl-c is
-    mashed and zombie reaper kills sub with no hangs.
-
-    '''
-    child = spawn('subactor_bp_in_ctx')
-    child.expect(PROMPT)
-
-    # 3 iters for the `gen()` pause-points
-    for i in range(3):
-        assert_before(
-            child,
-            [
-                _pause_msg,
-                "('bp_boi'",  # actor name
-                "<Task 'just_bp'",  # task name
-            ]
-        )
-        if (
-            i == 1
-            and
-            quit_early
-        ):
-            child.sendline('q')
-            child.expect(PROMPT)
-            assert_before(
-                child,
-                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
-                 "bdb.BdbQuit",
-                 "('bp_boi'",
-                ]
-            )
-            child.sendline('c')
-            child.expect(EOF)
-            assert_before(
-                child,
-                ["tractor._exceptions.RemoteActorError: remote task raised a 'BdbQuit'",
-                 "bdb.BdbQuit",
-                 "('bp_boi'",
-                ]
-            )
-            break  # end-of-test
-
-        child.sendline('c')
-        try:
-            child.expect(PROMPT)
-        except TIMEOUT:
-            # no prompt since we hang due to IPC chan purposely
-            # closed so verify we see error reporting as well as
-            # a failed crash-REPL request msg and can CTL-c our way
-            # out.
-            assert_before(
-                child,
-                ['peer IPC channel closed abruptly?',
-                 'another task closed this fd',
-                 'Debug lock request was CANCELLED?',
-                 "TransportClosed: 'MsgpackUDSStream' was already closed locally ?",]
-
-                # XXX races on whether these show/hit?
-                 # 'Failed to REPl via `_pause()` You called `tractor.pause()` from an already cancelled scope!',
-                 # 'AssertionError',
-            )
-            # OSc(ancel) the hanging tree
-            do_ctlc(
-                child=child,
-                expect_prompt=False,
-            )
-            child.expect(EOF)
-            assert_before(
-                child,
-                ['KeyboardInterrupt'],
-            )
-
-
 # TODO: better error for "non-ideal" usage from the root actor.
 # -[ ] if called from an async scope emit a message that suggests
 #    using `await tractor.pause()` instead since it's less overhead

tests/devx/test_tooling.py

@@ -14,9 +14,6 @@ TODO:
 
 '''
 from __future__ import annotations
-from contextlib import (
-    contextmanager as cm,
-)
 import os
 import signal
 import time
@@ -31,8 +28,6 @@ from .conftest import (
     PROMPT,
     _pause_msg,
 )
-
-import pytest
 from pexpect.exceptions import (
     # TIMEOUT,
     EOF,
@@ -188,117 +183,3 @@ def test_breakpoint_hook_restored(
     )
     child.sendline('c')
     child.expect(EOF)
-
-
-
-_to_raise = Exception('Triggering a crash')
-
-
-@pytest.mark.parametrize(
-    'to_raise',
-    [
-        None,
-        _to_raise,
-        RuntimeError('Never crash handle this!'),
-    ],
-)
-@pytest.mark.parametrize(
-    'raise_on_exit',
-    [
-        True,
-        [type(_to_raise)],
-        False,
-    ]
-)
-def test_crash_handler_cms(
-    debug_mode: bool,
-    to_raise: Exception,
-    raise_on_exit: bool|list[Exception],
-):
-    '''
-    Verify the `.devx.open_crash_handler()` API(s) by also
-    (conveniently enough) tesing its `repl_fixture: ContextManager`
-    param support which for this suite allows use to avoid use of
-    a `pexpect`-style-test since we use the fixture to avoid actually
-    entering `PdbpREPL.iteract()` :smirk:
-
-    '''
-    import tractor
-    # import trio
-
-    # state flags
-    repl_acquired: bool = False
-    repl_released: bool = False
-
-    @cm
-    def block_repl_ux(
-        repl: tractor.devx.debug.PdbREPL,
-        maybe_bxerr: (
-            tractor.devx._debug.BoxedMaybeException
-            |None
-        ) = None,
-        enter_repl: bool = True,
-
-    ) -> bool:
-        '''
-        Set pre/post-REPL state vars and bypass actual conole
-        interaction.
-
-        '''
-        nonlocal repl_acquired, repl_released
-
-        # task: trio.Task = trio.lowlevel.current_task()
-        # print(f'pre-REPL active_task={task.name}')
-
-        print('pre-REPL')
-        repl_acquired = True
-        yield False  # never actually .interact()
-        print('post-REPL')
-        repl_released = True
-
-    try:
-        # TODO, with runtime's `debug_mode` setting
-        # -[ ] need to open runtime tho obvi..
-        #
-        # with tractor.devx.maybe_open_crash_handler(
-        #     pdb=True,
-
-        with tractor.devx.open_crash_handler(
-            raise_on_exit=raise_on_exit,
-            repl_fixture=block_repl_ux
-        ) as bxerr:
-            if to_raise is not None:
-                raise to_raise
-
-    except Exception as _exc:
-        exc = _exc
-        if (
-            raise_on_exit is True
-            or
-            type(to_raise) in raise_on_exit
-        ):
-            assert (
-                exc
-                is
-                to_raise
-                is
-                bxerr.value
-            )
-
-        else:
-            raise
-    else:
-        assert (
-            to_raise is None
-            or
-            not raise_on_exit
-            or
-            type(to_raise) not in raise_on_exit
-        )
-        assert bxerr.value is to_raise
-
-    assert bxerr.raise_on_exit == raise_on_exit
-
-    if to_raise is not None:
-        assert repl_acquired
-        assert repl_released

tests/test_context_stream_semantics.py

@@ -252,7 +252,7 @@ def test_simple_context(
             pass
         except BaseExceptionGroup as beg:
             # XXX: on windows it seems we may have to expect the group error
-            from tractor.trionics import is_multi_cancelled
+            from tractor._exceptions import is_multi_cancelled
             assert is_multi_cancelled(beg)
     else:
         trio.run(main)

tests/test_remote_exc_relay.py

@@ -1,237 +0,0 @@
-'''
-Special case testing for issues not (dis)covered in the primary
-`Context` related functional/scenario suites.
-
-**NOTE: this mod is a WIP** space for handling
-odd/rare/undiscovered/not-yet-revealed faults which either
-loudly (ideal case) breakl our supervision protocol
-or (worst case) result in distributed sys hangs.
-
-Suites here further try to clarify (if [partially] ill-defined) and
-verify our edge case semantics for inter-actor-relayed-exceptions
-including,
-
-- lowlevel: what remote obj-data is interchanged for IPC and what is
-  native-obj form is expected from unpacking in the the new
-  mem-domain.
-
-- which kinds of `RemoteActorError` (and its derivs) are expected by which
-  (types of) peers (parent, child, sibling, etc) with what
-  particular meta-data set such as,
-
-  - `.src_uid`: the original (maybe) peer who raised.
-  - `.relay_uid`: the next-hop-peer who sent it.
-  - `.relay_path`: the sequence of peer actor hops.
-  - `.is_inception`: a predicate that denotes multi-hop remote errors.
-
-- when should `ExceptionGroup`s be relayed from a particular
-  remote endpoint, they should never be caused by implicit `._rpc`
-  nursery machinery!
-
-- various special `trio` edge cases around its cancellation semantics
-  and how we (currently) leverage `trio.Cancelled` as a signal for
-  whether a `Context` task should raise `ContextCancelled` (ctx).
-
-'''
-import pytest
-import trio
-import tractor
-from tractor import (  # typing
-    ActorNursery,
-    Portal,
-    Context,
-    ContextCancelled,
-)
-
-
-@tractor.context
-async def sleep_n_chkpt_in_finally(
-    ctx: Context,
-    sleep_n_raise: bool,
-
-    chld_raise_delay: float,
-    chld_finally_delay: float,
-
-    rent_cancels: bool,
-    rent_ctxc_delay: float,
-
-    expect_exc: str|None = None,
-
-) -> None:
-    '''
-    Sync, open a tn, then wait for cancel, run a chkpt inside
-    the user's `finally:` teardown.
-
-    This covers a footgun case that `trio` core doesn't seem to care about
-    wherein an exc can be masked by a `trio.Cancelled` raised inside a tn emedded
-    `finally:`.
-
-    Also see `test_trioisms::test_acm_embedded_nursery_propagates_enter_err`
-    for the down and gritty details.
-
-    Since a `@context` endpoint fn can also contain code like this,
-    **and** bc we currently have no easy way other then
-    `trio.Cancelled` to signal cancellation on each side of an IPC `Context`,
-    the footgun issue can compound itself as demonstrated in this suite..
-
-    Here are some edge cases codified with our WIP "sclang" syntax
-    (note the parent(rent)/child(chld) naming here is just
-    pragmatism, generally these most of these cases can occurr
-    regardless of the distributed-task's supervision hiearchy),
-
-    - rent c)=> chld.raises-then-taskc-in-finally
-     |_ chld's body raises an `exc: BaseException`.
-      _ in its `finally:` block it runs a chkpoint
-        which raises a taskc (`trio.Cancelled`) which
-        masks `exc` instead raising taskc up to the first tn.
-      _ the embedded/chld tn captures the masking taskc and then
-        raises it up to the ._rpc-ep-tn instead of `exc`.
-      _ the rent thinks the child ctxc-ed instead of errored..
-
-    '''
-    await ctx.started()
-
-    if expect_exc:
-        expect_exc: BaseException = tractor._exceptions.get_err_type(
-            type_name=expect_exc,
-        )
-
-    berr: BaseException|None = None
-    try:
-        if not sleep_n_raise:
-            await trio.sleep_forever()
-        elif sleep_n_raise:
-
-            # XXX this sleep is less then the sleep the parent
-            # does before calling `ctx.cancel()`
-            await trio.sleep(chld_raise_delay)
-
-            # XXX this will be masked by a taskc raised in
-            # the `finally:` if this fn doesn't terminate
-            # before any ctxc-req arrives AND a checkpoint is hit
-            # in that `finally:`.
-            raise RuntimeError('my app krurshed..')
-
-    except BaseException as _berr:
-        berr = _berr
-
-        # TODO: it'd sure be nice to be able to inject our own
-        # `ContextCancelled` here instead of of `trio.Cancelled`
-        # so that our runtime can expect it and this "user code"
-        # would be able to tell the diff between a generic trio
-        # cancel and a tractor runtime-IPC cancel.
-        if expect_exc:
-            if not isinstance(
-                berr,
-                expect_exc,
-            ):
-                raise ValueError(
-                    f'Unexpected exc type ??\n'
-                    f'{berr!r}\n'
-                    f'\n'
-                    f'Expected a {expect_exc!r}\n'
-                )
-
-        raise berr
-
-    # simulate what user code might try even though
-    # it's a known boo-boo..
-    finally:
-        # maybe wait for rent ctxc to arrive
-        with trio.CancelScope(shield=True):
-            await trio.sleep(chld_finally_delay)
-
-        # !!XXX this will raise `trio.Cancelled` which
-        # will mask the RTE from above!!!
-        #
-        # YES, it's the same case as our extant
-        # `test_trioisms::test_acm_embedded_nursery_propagates_enter_err`
-        try:
-            await trio.lowlevel.checkpoint()
-        except trio.Cancelled as taskc:
-            if (scope_err := taskc.__context__):
-                print(
-                    f'XXX MASKED REMOTE ERROR XXX\n'
-                    f'ENDPOINT exception -> {scope_err!r}\n'
-                    f'will be masked by -> {taskc!r}\n'
-                )
-                # await tractor.pause(shield=True)
-
-            raise taskc
-
-
-@pytest.mark.parametrize(
-    'chld_callspec',
-    [
-        dict(
-            sleep_n_raise=None,
-            chld_raise_delay=0.1,
-            chld_finally_delay=0.1,
-            expect_exc='Cancelled',
-            rent_cancels=True,
-            rent_ctxc_delay=0.1,
-        ),
-        dict(
-            sleep_n_raise='RuntimeError',
-            chld_raise_delay=0.1,
-            chld_finally_delay=1,
-            expect_exc='RuntimeError',
-            rent_cancels=False,
-            rent_ctxc_delay=0.1,
-        ),
-    ],
-    ids=lambda item: f'chld_callspec={item!r}'
-)
-def test_unmasked_remote_exc(
-    debug_mode: bool,
-    chld_callspec: dict,
-    tpt_proto: str,
-):
-    expect_exc_str: str|None = chld_callspec['sleep_n_raise']
-    rent_ctxc_delay: float|None = chld_callspec['rent_ctxc_delay']
-    async def main():
-        an: ActorNursery
-        async with tractor.open_nursery(
-            debug_mode=debug_mode,
-            enable_transports=[tpt_proto],
-        ) as an:
-            ptl: Portal = await an.start_actor(
-                'cancellee',
-                enable_modules=[__name__],
-            )
-            ctx: Context
-            async with (
-                ptl.open_context(
-                    sleep_n_chkpt_in_finally,
-                    **chld_callspec,
-                ) as (ctx, sent),
-            ):
-                assert not sent
-                await trio.sleep(rent_ctxc_delay)
-                await ctx.cancel()
-
-                # recv error or result from chld
-                ctxc: ContextCancelled = await ctx.wait_for_result()
-                assert (
-                    ctxc is ctx.outcome
-                    and
-                    isinstance(ctxc, ContextCancelled)
-                )
-
-            # always graceful terminate the sub in non-error cases
-            await an.cancel()
-
-    if expect_exc_str:
-        expect_exc: BaseException = tractor._exceptions.get_err_type(
-            type_name=expect_exc_str,
-        )
-        with pytest.raises(
-            expected_exception=tractor.RemoteActorError,
-        ) as excinfo:
-            trio.run(main)
-
-        rae = excinfo.value
-        assert expect_exc == rae.boxed_type
-
-    else:
-        trio.run(main)

tests/test_trioisms.py

@@ -112,11 +112,55 @@ def test_acm_embedded_nursery_propagates_enter_err(
     '''
     import tractor
 
+    @acm
+    async def maybe_raise_from_masking_exc(
+        tn: trio.Nursery,
+        unmask_from: BaseException|None = trio.Cancelled
+
+        # TODO, maybe offer a collection?
+        # unmask_from: set[BaseException] = {
+        #     trio.Cancelled,
+        # },
+    ):
+        if not unmask_from:
+            yield
+            return
+
+        try:
+            yield
+        except* unmask_from as be_eg:
+
+            # TODO, if we offer `unmask_from: set`
+            # for masker_exc_type in unmask_from:
+
+            matches, rest = be_eg.split(unmask_from)
+            if not matches:
+                raise
+
+            for exc_match in be_eg.exceptions:
+                if (
+                    (exc_ctx := exc_match.__context__)
+                    and
+                    type(exc_ctx) not in {
+                        # trio.Cancelled,  # always by default?
+                        unmask_from,
+                    }
+                ):
+                    exc_ctx.add_note(
+                        f'\n'
+                        f'WARNING: the above error was masked by a {unmask_from!r} !?!\n'
+                        f'Are you always cancelling? Say from a `finally:` ?\n\n'
+
+                        f'{tn!r}'
+                    )
+                    raise exc_ctx from exc_match
+
+
     @acm
     async def wraps_tn_that_always_cancels():
         async with (
             trio.open_nursery() as tn,
-            tractor.trionics.maybe_raise_from_masking_exc(
+            maybe_raise_from_masking_exc(
                 tn=tn,
                 unmask_from=(
                     trio.Cancelled
@@ -158,60 +202,3 @@ def test_acm_embedded_nursery_propagates_enter_err(
     assert_eg, rest_eg = eg.split(AssertionError)
 
     assert len(assert_eg.exceptions) == 1
-
-
-
-def test_gatherctxs_with_memchan_breaks_multicancelled(
-    debug_mode: bool,
-):
-    '''
-    Demo how a using an `async with sndchan` inside a `.trionics.gather_contexts()` task
-    will break a strict-eg-tn's multi-cancelled absorption..
-
-    '''
-    from tractor import (
-        trionics,
-    )
-
-    @acm
-    async def open_memchan() -> trio.abc.ReceiveChannel:
-
-        task: trio.Task = trio.lowlevel.current_task()
-        print(
-            f'Opening {task!r}\n'
-        )
-
-        # 1 to force eager sending
-        send, recv = trio.open_memory_channel(16)
-
-        try:
-            async with send:
-                yield recv
-        finally:
-            print(
-                f'Closed {task!r}\n'
-            )
-
-
-    async def main():
-        async with (
-            # XXX should ensure ONLY the KBI
-            # is relayed upward
-            trionics.collapse_eg(),
-            trio.open_nursery(
-                # strict_exception_groups=False,
-            ), # as tn,
-
-            trionics.gather_contexts([
-                open_memchan(),
-                open_memchan(),
-            ]) as recv_chans,
-        ):
-            assert len(recv_chans) == 2
-
-            await trio.sleep(1)
-            raise KeyboardInterrupt
-            # tn.cancel_scope.cancel()
-
-    with pytest.raises(KeyboardInterrupt):
-        trio.run(main)

tractor/_entry.py

@@ -135,12 +135,12 @@ def _trio_main(
             f'  loglevel: {actor.loglevel}\n'
         )
         log.info(
-            'Starting new `trio` subactor\n'
+            'Starting new `trio` subactor:\n'
             +
             pformat.nest_from_op(
                 input_op='>(',  # see syntax ideas above
-                text=actor_info,
-                nest_indent=2,  # since "complete"
+                tree_str=actor_info,
+                back_from_op=2,  # since "complete"
             )
         )
     logmeth = log.info
@@ -149,8 +149,8 @@ def _trio_main(
         +
         pformat.nest_from_op(
             input_op=')>',  # like a "closed-to-play"-icon from super perspective
-            text=actor_info,
-            nest_indent=1,
+            tree_str=actor_info,
+            back_from_op=1,
         )
     )
     try:
@@ -167,7 +167,7 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='c)>',  # closed due to cancel (see above)
-                text=actor_info,
+                tree_str=actor_info,
             )
         )
     except BaseException as err:
@@ -177,7 +177,7 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='x)>',  # closed by error
-                text=actor_info,
+                tree_str=actor_info,
             )
         )
         # NOTE since we raise a tb will already be shown on the

tractor/_exceptions.py

@@ -1246,6 +1246,55 @@ def unpack_error(
     return exc
 
 
+def is_multi_cancelled(
+    exc: BaseException|BaseExceptionGroup,
+
+    ignore_nested: set[BaseException] = set(),
+
+) -> bool|BaseExceptionGroup:
+    '''
+    Predicate to determine if an `BaseExceptionGroup` only contains
+    some (maybe nested) set of sub-grouped exceptions (like only
+    `trio.Cancelled`s which get swallowed silently by default) and is
+    thus the result of "gracefully cancelling" a collection of
+    sub-tasks (or other conc primitives) and receiving a "cancelled
+    ACK" from each after termination.
+
+    Docs:
+    ----
+    - https://docs.python.org/3/library/exceptions.html#exception-groups
+    - https://docs.python.org/3/library/exceptions.html#BaseExceptionGroup.subgroup
+
+    '''
+
+    if (
+        not ignore_nested
+        or
+        trio.Cancelled in ignore_nested
+        # XXX always count-in `trio`'s native signal
+    ):
+        ignore_nested.update({trio.Cancelled})
+
+    if isinstance(exc, BaseExceptionGroup):
+        matched_exc: BaseExceptionGroup|None = exc.subgroup(
+            tuple(ignore_nested),
+
+            # TODO, complain about why not allowed XD
+            # condition=tuple(ignore_nested),
+        )
+        if matched_exc is not None:
+            return matched_exc
+
+    # NOTE, IFF no excs types match (throughout the error-tree)
+    # -> return `False`, OW return the matched sub-eg.
+    #
+    # IOW, for the inverse of ^ for the purpose of
+    # maybe-enter-REPL--logic: "only debug when the err-tree contains
+    # at least one exc-type NOT in `ignore_nested`" ; i.e. the case where
+    # we fallthrough and return `False` here.
+    return False
+
+
 def _raise_from_unexpected_msg(
     ctx: Context,
     msg: MsgType,

tractor/_root.py

@@ -61,11 +61,9 @@ from ._addr import (
     mk_uuid,
     wrap_address,
 )
-from .trionics import (
-    is_multi_cancelled,
-)
 from ._exceptions import (
     RuntimeFailure,
+    is_multi_cancelled,
 )
 
 

tractor/_rpc.py

@@ -37,7 +37,6 @@ import warnings
 
 import trio
 from trio import (
-    Cancelled,
     CancelScope,
     Nursery,
     TaskStatus,
@@ -53,14 +52,10 @@ from ._exceptions import (
     ModuleNotExposed,
     MsgTypeError,
     TransportClosed,
+    is_multi_cancelled,
     pack_error,
     unpack_error,
 )
-from .trionics import (
-    collapse_eg,
-    is_multi_cancelled,
-    maybe_raise_from_masking_exc,
-)
 from .devx import (
     debug,
     add_div,
@@ -255,7 +250,7 @@ async def _errors_relayed_via_ipc(
     ctx: Context,
     is_rpc: bool,
 
-    hide_tb: bool = True,
+    hide_tb: bool = False,
     debug_kbis: bool = False,
     task_status: TaskStatus[
         Context | BaseException
@@ -380,9 +375,9 @@ async def _errors_relayed_via_ipc(
     # they can be individually ccancelled.
     finally:
 
-        # if the error is not from user code and instead a failure of
-        # an internal-runtime-RPC or IPC-connection, we do (prolly) want
-        # to show this frame!
+        # if the error is not from user code and instead a failure
+        # of a runtime RPC or transport failure we do prolly want to
+        # show this frame
         if (
             rpc_err
             and (
@@ -621,40 +616,32 @@ async def _invoke(
         #  -> the below scope is never exposed to the
         #     `@context` marked RPC function.
         # - `._portal` is never set.
-        scope_err: BaseException|None = None
         try:
-            # TODO: better `trionics` primitive/tooling usage here!
-            # -[ ] should would be nice to have our `TaskMngr`
-            #   nursery here!
-            # -[ ] payload value checking like we do with
-            #   `.started()` such that the debbuger can engage
-            #   here in the child task instead of waiting for the
-            #   parent to crash with it's own MTE..
-            #
-            tn: Nursery
+            tn: trio.Nursery
             rpc_ctx_cs: CancelScope
             async with (
-                collapse_eg(),
-                trio.open_nursery() as tn,
+                trio.open_nursery(
+                    strict_exception_groups=False,
+                    # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
+
+                ) as tn,
                 msgops.maybe_limit_plds(
                     ctx=ctx,
                     spec=ctx_meta.get('pld_spec'),
                     dec_hook=ctx_meta.get('dec_hook'),
                 ),
-
-                # XXX NOTE, this being the "most embedded"
-                # scope ensures unasking of the `await coro` below
-                # *should* never be interfered with!!
-                maybe_raise_from_masking_exc(
-                    tn=tn,
-                    unmask_from=Cancelled,
-                ) as _mbme,  # maybe boxed masked exc
             ):
                 ctx._scope_nursery = tn
                 rpc_ctx_cs = ctx._scope = tn.cancel_scope
                 task_status.started(ctx)
 
-                # invoke user endpoint fn.
+                # TODO: better `trionics` tooling:
+                # -[ ] should would be nice to have our `TaskMngr`
+                #   nursery here!
+                # -[ ] payload value checking like we do with
+                #   `.started()` such that the debbuger can engage
+                #   here in the child task instead of waiting for the
+                #   parent to crash with it's own MTE..
                 res: Any|PayloadT = await coro
                 return_msg: Return|CancelAck = return_msg_type(
                     cid=cid,
@@ -757,48 +744,38 @@ async def _invoke(
             BaseException,
             trio.Cancelled,
 
-        ) as _scope_err:
-            scope_err = _scope_err
+        ) as scope_error:
             if (
-                isinstance(scope_err, RuntimeError)
-                and
-                scope_err.args
-                and
-                'Cancel scope stack corrupted' in scope_err.args[0]
+                isinstance(scope_error, RuntimeError)
+                and scope_error.args
+                and 'Cancel scope stack corrupted' in scope_error.args[0]
             ):
                 log.exception('Cancel scope stack corrupted!?\n')
                 # debug.mk_pdb().set_trace()
 
             # always set this (child) side's exception as the
             # local error on the context
-            ctx._local_error: BaseException = scope_err
+            ctx._local_error: BaseException = scope_error
             # ^-TODO-^ question,
             # does this matter other then for
             # consistentcy/testing?
             # |_ no user code should be in this scope at this point
             #    AND we already set this in the block below?
 
-            # XXX if a remote error was set then likely the
-            # exc group was raised due to that, so
+            # if a remote error was set then likely the
+            # exception group was raised due to that, so
             # and we instead raise that error immediately!
-            maybe_re: (
-                ContextCancelled|RemoteActorError
-            ) = ctx.maybe_raise()
-            if maybe_re:
-                log.cancel(
-                    f'Suppressing remote-exc from peer,\n'
-                    f'{maybe_re!r}\n'
-                )
+            ctx.maybe_raise()
 
             # maybe TODO: pack in come kinda
             # `trio.Cancelled.__traceback__` here so they can be
             # unwrapped and displayed on the caller side? no se..
-            raise scope_err
+            raise
 
         # `@context` entrypoint task bookeeping.
         # i.e. only pop the context tracking if used ;)
         finally:
-            assert chan.aid
+            assert chan.uid
 
             # don't pop the local context until we know the
             # associated child isn't in debug any more
@@ -825,9 +802,6 @@ async def _invoke(
                     descr_str += (
                         f'\n{merr!r}\n'  # needed?
                         f'{tb_str}\n'
-                        f'\n'
-                        f'scope_error:\n'
-                        f'{scope_err!r}\n'
                     )
                 else:
                     descr_str += f'\n{merr!r}\n'

tractor/_supervise.py

@@ -40,10 +40,8 @@ from ._state import current_actor, is_main_process
 from .log import get_logger, get_loglevel
 from ._runtime import Actor
 from ._portal import Portal
-from .trionics import (
-    is_multi_cancelled,
-)
 from ._exceptions import (
+    is_multi_cancelled,
     ContextCancelled,
 )
 from ._root import (

tractor/devx/_stackscope.py

@@ -238,8 +238,7 @@ def enable_stack_on_sig(
         import stackscope
     except ImportError:
         log.error(
-            '`stackscope` not installed for use in debug mode!\n'
-            '`Ignoring {enable_stack_on_sig!r} call!\n'
+            '`stackscope` not installed for use in debug mode!'
         )
         return None
 

tractor/devx/debug/_post_mortem.py

@@ -59,7 +59,7 @@ from tractor._state import (
     debug_mode,
 )
 from tractor.log import get_logger
-from tractor.trionics import (
+from tractor._exceptions import (
     is_multi_cancelled,
 )
 from ._trace import (
@@ -148,61 +148,59 @@ def _post_mortem(
         repl_fixture=repl_fixture,
         boxed_maybe_exc=boxed_maybe_exc,
     )
+    if not enter_repl:
+        return
     try:
-        if not enter_repl:
-            # XXX, trigger `.release()` below immediately!
-            return
-        try:
-            actor: Actor = current_actor()
-            actor_repr: str = str(actor.uid)
-            # ^TODO, instead a nice runtime-info + maddr + uid?
-            # -[ ] impl a `Actor.__repr()__`??
-            #  |_ <task>:<thread> @ <actor>
+        actor: Actor = current_actor()
+        actor_repr: str = str(actor.uid)
+        # ^TODO, instead a nice runtime-info + maddr + uid?
+        # -[ ] impl a `Actor.__repr()__`??
+        #  |_ <task>:<thread> @ <actor>
 
-        except NoRuntime:
-            actor_repr: str = '<no-actor-runtime?>'
+    except NoRuntime:
+        actor_repr: str = '<no-actor-runtime?>'
 
-        try:
-            task_repr: Task = trio.lowlevel.current_task()
-        except RuntimeError:
-            task_repr: str = '<unknown-Task>'
+    try:
+        task_repr: Task = trio.lowlevel.current_task()
+    except RuntimeError:
+        task_repr: str = '<unknown-Task>'
 
-        # TODO: print the actor supervion tree up to the root
-        # here! Bo
-        log.pdb(
-            f'{_crash_msg}\n'
-            f'x>(\n'
-            f' |_ {task_repr} @ {actor_repr}\n'
+    # TODO: print the actor supervion tree up to the root
+    # here! Bo
+    log.pdb(
+        f'{_crash_msg}\n'
+        f'x>(\n'
+        f' |_ {task_repr} @ {actor_repr}\n'
 
-        )
+    )
 
-        # XXX NOTE(s) on `pdbp.xpm()` version..
-        #
-        # - seems to lose the up-stack tb-info?
-        # - currently we're (only) replacing this from `pdbp.xpm()`
-        #   to add the `end=''` to the print XD
-        #
-        print(traceback.format_exc(), end='')
-        caller_frame: FrameType = api_frame.f_back
+    # XXX NOTE(s) on `pdbp.xpm()` version..
+    #
+    # - seems to lose the up-stack tb-info?
+    # - currently we're (only) replacing this from `pdbp.xpm()`
+    #   to add the `end=''` to the print XD
+    #
+    print(traceback.format_exc(), end='')
+    caller_frame: FrameType = api_frame.f_back
 
-        # NOTE, see the impl details of these in the lib to
-        # understand usage:
-        # - `pdbp.post_mortem()`
-        # - `pdbp.xps()`
-        # - `bdb.interaction()`
-        repl.reset()
-        repl.interaction(
-            frame=caller_frame,
-            # frame=None,
-            traceback=tb,
-        )
-    finally:
-        # XXX NOTE XXX: this is abs required to avoid hangs!
-        #
-        # Since we presume the post-mortem was enaged to
-        # a task-ending error, we MUST release the local REPL request
-        # so that not other local task nor the root remains blocked!
-        DebugStatus.release()
+    # NOTE, see the impl details of these in the lib to
+    # understand usage:
+    # - `pdbp.post_mortem()`
+    # - `pdbp.xps()`
+    # - `bdb.interaction()`
+    repl.reset()
+    repl.interaction(
+        frame=caller_frame,
+        # frame=None,
+        traceback=tb,
+    )
+
+    # XXX NOTE XXX: this is abs required to avoid hangs!
+    #
+    # Since we presume the post-mortem was enaged to
+    # a task-ending error, we MUST release the local REPL request
+    # so that not other local task nor the root remains blocked!
+    DebugStatus.release()
 
 
 async def post_mortem(

tractor/devx/debug/_tty_lock.py

@@ -846,9 +846,9 @@ class DebugStatus:
 
         '''
         if not (
-            (rt_repl_fixture := _state._runtime_vars.get('repl_fixture'))
-            or
             repl_fixture
+            or
+            (rt_repl_fixture := _state._runtime_vars.get('repl_fixture'))
         ):
             return True  # YES always enter
 

tractor/devx/pformat.py

@@ -15,10 +15,8 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 '''
-Pretty formatters for use throughout our internals.
-
-Handy for logging and exception message content but also for `repr()`
-in REPL(s).
+Pretty formatters for use throughout the code base.
+Mostly handy for logging and exception message content.
 
 '''
 import sys
@@ -226,8 +224,8 @@ def pformat_cs(
     field_prefix: str = ' |_',
 ) -> str:
     '''
-    Pretty format info about a `trio.CancelScope` including most of
-    its public state and `._cancel_status`.
+    Pretty format info about a `trio.CancelScope` including most
+    of its public state and `._cancel_status`.
 
     The output can be modified to show a "var name" for the
     instance as a field prefix, just a simple str before each
@@ -251,33 +249,14 @@ def pformat_cs(
     )
 
 
+# TODO: move this func to some kinda `.devx.pformat.py` eventually
+# as we work out our multi-domain state-flow-syntax!
 def nest_from_op(
-    input_op: str,  # TODO, Literal of all op-"symbols" from below?
-    text: str,
-    prefix_op: bool = True,  # unset is to suffix the first line
-    # optionally suffix `text`, by def on a newline
-    op_suffix='\n',
-
-    nest_prefix: str = '|_',
-    nest_indent: int|None = None,
-    # XXX indent `next_prefix` "to-the-right-of" `input_op`
-    # by this count of whitespaces (' ').
-    rm_from_first_ln: str|None = None,
-
-) -> str:
-    '''
-    Depth-increment the input (presumably hierarchy/supervision)
-    input "tree string" below the provided `input_op` execution
-    operator, so injecting a `"\n|_{input_op}\n"`and indenting the
-    `tree_str` to nest content aligned with the ops last char.
-
-    '''
-    # `sclang` "structurred-concurrency-language": an ascii-encoded
-    # symbolic alphabet to describe concurrent systems.
+    input_op: str,
     #
-    # ?TODO? aa more fomal idea for a syntax to the state of
-    # concurrent systems as a "3-domain" (execution, scope, storage)
-    # model and using a minimal ascii/utf-8 operator-set.
+    # ?TODO? an idea for a syntax to the state of concurrent systems
+    # as a "3-domain" (execution, scope, storage) model and using
+    # a minimal ascii/utf-8 operator-set.
     #
     # try not to take any of this seriously yet XD
     #
@@ -343,185 +322,29 @@ def nest_from_op(
     #
     # =>{  recv-req to open
     # <={  send-status that it closed
-    #
-    if (
-        nest_prefix
-        and
-        nest_indent != 0
-    ):
-        if nest_indent is not None:
-            nest_prefix: str = textwrap.indent(
-                nest_prefix,
-                prefix=nest_indent*' ',
-            )
-        nest_indent: int = len(nest_prefix)
 
-    # determine body-text indent either by,
-    # - using wtv explicit indent value is provided,
-    # OR
-    # - auto-calcing the indent to embed `text` under
-    #   the `nest_prefix` if provided, **IFF** `nest_indent=None`.
-    tree_str_indent: int = 0
-    if nest_indent not in {0, None}:
-        tree_str_indent = nest_indent
-    elif (
-        nest_prefix
-        and
-        nest_indent != 0
-    ):
-        tree_str_indent = len(nest_prefix)
+    tree_str: str,
 
-    indented_tree_str: str = text
-    if tree_str_indent:
-        indented_tree_str: str = textwrap.indent(
-            text,
-            prefix=' '*tree_str_indent,
-        )
-
-    # inject any provided nesting-prefix chars
-    # into the head of the first line.
-    if nest_prefix:
-        indented_tree_str: str = (
-            f'{nest_prefix}{indented_tree_str[tree_str_indent:]}'
-        )
-
-    if (
-        not prefix_op
-        or
-        rm_from_first_ln
-    ):
-        tree_lns: list[str] = indented_tree_str.splitlines()
-        first: str = tree_lns[0]
-        if rm_from_first_ln:
-            first = first.strip().replace(
-                rm_from_first_ln,
-                '',
-            )
-        indented_tree_str: str = '\n'.join(tree_lns[1:])
-
-        if prefix_op:
-            indented_tree_str = (
-                f'{first}\n'
-                f'{indented_tree_str}'
-            )
-
-    if prefix_op:
-        return (
-            f'{input_op}{op_suffix}'
-            f'{indented_tree_str}'
-        )
-    else:
-        return (
-            f'{first}{input_op}{op_suffix}'
-            f'{indented_tree_str}'
-        )
-
-
-# ------ modden.repr ------
-# XXX originally taken verbaatim from `modden.repr`
-'''
-More "multi-line" representation then the stdlib's `pprint` equivs.
-
-'''
-from inspect import (
-    FrameInfo,
-    stack,
-)
-import pprint
-import reprlib
-from typing import (
-    Callable,
-)
-
-
-def mk_repr(
-    **repr_kws,
-) -> Callable[[str], str]:
-    '''
-    Allocate and deliver a `repr.Repr` instance with provided input
-    settings using the std-lib's `reprlib` mod,
-     * https://docs.python.org/3/library/reprlib.html
-
-    ------ Ex. ------
-    An up to 6-layer-nested `dict` as multi-line:
-    - https://stackoverflow.com/a/79102479
-    - https://docs.python.org/3/library/reprlib.html#reprlib.Repr.maxlevel
-
-    '''
-    def_kws: dict[str, int] = dict(
-        indent=3,  # indent used for repr of recursive objects
-        maxlevel=616,  # recursion levels
-        maxdict=616,  # max items shown for `dict`
-        maxlist=616,  # max items shown for `dict`
-        maxstring=616,  # match editor line-len limit
-        maxtuple=616,  # match editor line-len limit
-        maxother=616,  # match editor line-len limit
-    )
-    def_kws |= repr_kws
-    reprr = reprlib.Repr(**def_kws)
-    return reprr.repr
-
-
-def ppfmt(
-    obj: object,
-    do_print: bool = False,
+    # NOTE: so move back-from-the-left of the `input_op` by
+    # this amount.
+    back_from_op: int = 0,
 ) -> str:
     '''
-    The `pprint.pformat()` version of `pprint.pp()`, namely
-    a default `sort_dicts=False`.. (which i think should be
-    the normal default in the stdlib).
-
-    '''
-    pprepr: Callable = mk_repr()
-    repr_str: str = pprepr(obj)
-
-    if do_print:
-        return pprint.pp(repr_str)
-
-    return repr_str
-
-
-pformat = ppfmt
-
-
-def pfmt_frame_info(fi: FrameInfo) -> str:
-    '''
-    Like a std `inspect.FrameInfo.__repr__()` but multi-line..
+    Depth-increment the input (presumably hierarchy/supervision)
+    input "tree string" below the provided `input_op` execution
+    operator, so injecting a `"\n|_{input_op}\n"`and indenting the
+    `tree_str` to nest content aligned with the ops last char.
 
     '''
     return (
-        'FrameInfo(\n'
-        '  frame={!r},\n'
-        '  filename={!r},\n'
-        '  lineno={!r},\n'
-        '  function={!r},\n'
-        '  code_context={!r},\n'
-        '  index={!r},\n'
-        '  positions={!r})'
-        ).format(
-            fi.frame,
-            fi.filename,
-            fi.lineno,
-            fi.function,
-            fi.code_context,
-            fi.index,
-            fi.positions
+        f'{input_op}\n'
+        +
+        textwrap.indent(
+            tree_str,
+            prefix=(
+                len(input_op)
+                -
+                (back_from_op + 1)
+            ) * ' ',
         )
-
-
-def pfmt_callstack(frames: int = 1) -> str:
-    '''
-    Generate a string of nested `inspect.FrameInfo` objects returned
-    from a `inspect.stack()` call such that only the `.frame` field
-    for each  layer is pprinted.
-
-    '''
-    caller_frames: list[FrameInfo] =  stack()[1:1+frames]
-    frames_str: str = ''
-    for i, frame_info in enumerate(caller_frames):
-        frames_str += textwrap.indent(
-            f'{frame_info.frame!r}\n',
-            prefix=' '*i,
-
-        )
-    return frames_str
+    )

tractor/msg/pretty_struct.py

@@ -20,7 +20,6 @@ Prettified version of `msgspec.Struct` for easier console grokin.
 '''
 from __future__ import annotations
 from collections import UserList
-import textwrap
 from typing import (
     Any,
     Iterator,
@@ -106,11 +105,27 @@ def iter_fields(struct: Struct) -> Iterator[
         )
 
 
-def iter_struct_ppfmt_lines(
+def pformat(
     struct: Struct,
-    field_indent: int = 0,
-) -> Iterator[tuple[str, str]]:
+    field_indent: int = 2,
+    indent: int = 0,
 
+) -> str:
+    '''
+    Recursion-safe `pprint.pformat()` style formatting of
+    a `msgspec.Struct` for sane reading by a human using a REPL.
+
+    '''
+    # global whitespace indent
+    ws: str = ' '*indent
+
+    # field whitespace indent
+    field_ws: str = ' '*(field_indent + indent)
+
+    # qtn: str = ws + struct.__class__.__qualname__
+    qtn: str = struct.__class__.__qualname__
+
+    obj_str: str = ''  # accumulator
     fi: structs.FieldInfo
     k: str
     v: Any
@@ -120,18 +135,15 @@ def iter_struct_ppfmt_lines(
         # ..]` over .__name__ == `Literal` but still get only the
         # latter for simple types like `str | int | None` etc..?
         ft: type = fi.type
-        typ_name: str = getattr(
-            ft,
-            '__name__',
-            str(ft)
-        ).replace(' ', '')
+        typ_name: str = getattr(ft, '__name__', str(ft))
 
         # recurse to get sub-struct's `.pformat()` output Bo
         if isinstance(v, Struct):
-            yield from iter_struct_ppfmt_lines(
-                struct=v,
-                field_indent=field_indent+field_indent,
+            val_str: str =  v.pformat(
+                indent=field_indent + indent,
+                field_indent=indent + field_indent,
             )
+
         else:
             val_str: str = repr(v)
 
@@ -149,39 +161,8 @@ def iter_struct_ppfmt_lines(
                 # raise
                 # return _Struct.__repr__(struct)
 
-        yield (
-            ' '*field_indent,  # indented ws prefix
-            f'{k}: {typ_name} = {val_str},',  # field's repr line content
-        )
-
-
-def pformat(
-    struct: Struct,
-    field_indent: int = 2,
-    indent: int = 0,
-) -> str:
-    '''
-    Recursion-safe `pprint.pformat()` style formatting of
-    a `msgspec.Struct` for sane reading by a human using a REPL.
-
-    '''
-    obj_str: str = ''  # accumulator
-    for prefix, field_repr, in iter_struct_ppfmt_lines(
-        struct,
-        field_indent=field_indent,
-    ):
-        obj_str += f'{prefix}{field_repr}\n'
-
-    # global whitespace indent
-    ws: str = ' '*indent
-    if indent:
-        obj_str: str = textwrap.indent(
-            text=obj_str,
-            prefix=ws,
-        )
-
-    # qtn: str = ws + struct.__class__.__qualname__
-    qtn: str = struct.__class__.__qualname__
+        # TODO: LOLOL use `textwrap.indent()` instead dawwwwwg!
+        obj_str += (field_ws + f'{k}: {typ_name} = {val_str},\n')
 
     return (
         f'{qtn}(\n'

tractor/to_asyncio.py

@@ -38,6 +38,7 @@ from typing import (
 import tractor
 from tractor._exceptions import (
     InternalError,
+    is_multi_cancelled,
     TrioTaskExited,
     TrioCancelled,
     AsyncioTaskExited,
@@ -58,9 +59,6 @@ from tractor.log import (
 # from tractor.msg import (
 #     pretty_struct,
 # )
-from tractor.trionics import (
-    is_multi_cancelled,
-)
 from tractor.trionics._broadcast import (
     broadcast_receiver,
     BroadcastReceiver,

tractor/trionics/__init__.py

@@ -32,8 +32,4 @@ from ._broadcast import (
 from ._beg import (
     collapse_eg as collapse_eg,
     maybe_collapse_eg as maybe_collapse_eg,
-    is_multi_cancelled as is_multi_cancelled,
-)
-from ._taskc import (
-    maybe_raise_from_masking_exc as maybe_raise_from_masking_exc,
 )

tractor/trionics/_beg.py

@@ -22,11 +22,6 @@ first-class-`trio` from a historical perspective B)
 from contextlib import (
     asynccontextmanager as acm,
 )
-from typing import (
-    Literal,
-)
-
-import trio
 
 
 def maybe_collapse_eg(
@@ -61,62 +56,3 @@ async def collapse_eg():
             raise exc
 
         raise beg
-
-
-def is_multi_cancelled(
-    beg: BaseException|BaseExceptionGroup,
-
-    ignore_nested: set[BaseException] = set(),
-
-) -> Literal[False]|BaseExceptionGroup:
-    '''
-    Predicate to determine if an `BaseExceptionGroup` only contains
-    some (maybe nested) set of sub-grouped exceptions (like only
-    `trio.Cancelled`s which get swallowed silently by default) and is
-    thus the result of "gracefully cancelling" a collection of
-    sub-tasks (or other conc primitives) and receiving a "cancelled
-    ACK" from each after termination.
-
-    Docs:
-    ----
-    - https://docs.python.org/3/library/exceptions.html#exception-groups
-    - https://docs.python.org/3/library/exceptions.html#BaseExceptionGroup.subgroup
-
-    '''
-
-    if (
-        not ignore_nested
-        or
-        trio.Cancelled not in ignore_nested
-        # XXX always count-in `trio`'s native signal
-    ):
-        ignore_nested.update({trio.Cancelled})
-
-    if isinstance(beg, BaseExceptionGroup):
-        # https://docs.python.org/3/library/exceptions.html#BaseExceptionGroup.subgroup
-        # |_ "The condition can be an exception type or tuple of
-        #   exception types, in which case each exception is checked
-        #   for a match using the same check that is used in an
-        #   except clause. The condition can also be a callable
-        #   (other than a type object) that accepts an exception as
-        #   its single argument and returns true for the exceptions
-        #   that should be in the subgroup."
-        matched_exc: BaseExceptionGroup|None = beg.subgroup(
-            tuple(ignore_nested),
-
-            # ??TODO, complain about why not allowed to use
-            # named arg style calling???
-            # XD .. wtf?
-            # condition=tuple(ignore_nested),
-        )
-        if matched_exc is not None:
-            return matched_exc
-
-    # NOTE, IFF no excs types match (throughout the error-tree)
-    # -> return `False`, OW return the matched sub-eg.
-    #
-    # IOW, for the inverse of ^ for the purpose of
-    # maybe-enter-REPL--logic: "only debug when the err-tree contains
-    # at least one exc-type NOT in `ignore_nested`" ; i.e. the case where
-    # we fallthrough and return `False` here.
-    return False

tractor/trionics/_mngrs.py

@@ -40,8 +40,6 @@ from typing import (
 import trio
 from tractor._state import current_actor
 from tractor.log import get_logger
-# from ._beg import collapse_eg
-
 
 if TYPE_CHECKING:
     from tractor import ActorNursery
@@ -114,19 +112,17 @@ async def gather_contexts(
     None,
 ]:
     '''
-    Concurrently enter a sequence of async context managers (`acm`s),
-    each scheduled in a separate `trio.Task` and deliver their
-    unwrapped `yield`-ed values in the same order once all `@acm`s
-    in every task have entered.
+    Concurrently enter a sequence of async context managers (acms),
+    each from a separate `trio` task and deliver the unwrapped
+    `yield`-ed values in the same order once all managers have entered.
 
-    On exit, all `acm`s are subsequently and concurrently exited with
-    **no order guarantees**.
+    On exit, all acms are subsequently and concurrently exited.
 
     This function is somewhat similar to a batch of non-blocking
     calls to `contextlib.AsyncExitStack.enter_async_context()`
     (inside a loop) *in combo with* a `asyncio.gather()` to get the
     `.__aenter__()`-ed values, except the managers are both
-    concurrently entered and exited and *cancellation-just-works™*.
+    concurrently entered and exited and *cancellation just works*(R).
 
     '''
     seed: int = id(mngrs)
@@ -146,20 +142,16 @@ async def gather_contexts(
     if not mngrs:
         raise ValueError(
             '`.trionics.gather_contexts()` input mngrs is empty?\n'
-            '\n'
             'Did try to use inline generator syntax?\n'
-            'Use a non-lazy iterator or sequence-type intead!\n'
+            'Use a non-lazy iterator or sequence type intead!'
         )
 
-    async with (
-        # collapse_eg(),
-        trio.open_nursery(
-            strict_exception_groups=False,
-            # ^XXX^ TODO? soo roll our own then ??
-            # -> since we kinda want the "if only one `.exception` then
-            # just raise that" interface?
-        ) as tn,
-    ):
+    async with trio.open_nursery(
+        strict_exception_groups=False,
+        # ^XXX^ TODO? soo roll our own then ??
+        # -> since we kinda want the "if only one `.exception` then
+        # just raise that" interface?
+    ) as tn:
         for mngr in mngrs:
             tn.start_soon(
                 _enter_and_wait,
@@ -176,7 +168,7 @@ async def gather_contexts(
         try:
             yield tuple(unwrapped.values())
         finally:
-            # XXX NOTE: this is ABSOLUTELY REQUIRED to avoid
+            # NOTE: this is ABSOLUTELY REQUIRED to avoid
             # the following wacky bug:
             # <tractorbugurlhere>
             parent_exit.set()

tractor/trionics/_taskc.py

@@ -1,184 +0,0 @@
-# tractor: structured concurrent "actors".
-# Copyright 2018-eternity Tyler Goodlet.
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU Affero General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU Affero General Public License for more details.
-
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <https://www.gnu.org/licenses/>.
-
-'''
-`trio.Task` cancellation helpers, extensions and "holsters".
-
-'''
-from __future__ import annotations
-from contextlib import (
-    asynccontextmanager as acm,
-)
-from typing import TYPE_CHECKING
-
-import trio
-from tractor.log import get_logger
-
-log = get_logger(__name__)
-
-
-if TYPE_CHECKING:
-    from tractor.devx.debug import BoxedMaybeException
-
-
-def find_masked_excs(
-    maybe_masker: BaseException,
-    unmask_from: set[BaseException],
-) -> BaseException|None:
-    ''''
-    Deliver any `maybe_masker.__context__` provided
-    it a declared masking exc-type entry in `unmask_from`.
-
-    '''
-    if (
-        type(maybe_masker) in unmask_from
-        and
-        (exc_ctx := maybe_masker.__context__)
-
-        # TODO? what about any cases where
-        # they could be the same type but not same instance?
-        # |_i.e. a cancel masking a cancel ??
-        # or (
-        #     exc_ctx is not maybe_masker
-        # )
-    ):
-        return exc_ctx
-
-    return None
-
-
-# XXX, relevant discussion @ `trio`-core,
-# https://github.com/python-trio/trio/issues/455
-#
-@acm
-async def maybe_raise_from_masking_exc(
-    tn: trio.Nursery|None = None,
-    unmask_from: (
-        BaseException|
-        tuple[BaseException]
-    ) = (trio.Cancelled,),
-
-    raise_unmasked: bool = True,
-    extra_note: str = (
-        'This can occurr when,\n'
-        ' - a `trio.Nursery` scope embeds a `finally:`-block '
-        'which executes a checkpoint!'
-        #
-        # ^TODO? other cases?
-    ),
-
-    always_warn_on: tuple[BaseException] = (
-        trio.Cancelled,
-    ),
-    # ^XXX, special case(s) where we warn-log bc likely
-    # there will be no operational diff since the exc
-    # is always expected to be consumed.
-) -> BoxedMaybeException:
-    '''
-    Maybe un-mask and re-raise exception(s) suppressed by a known
-    error-used-as-signal type (cough namely `trio.Cancelled`).
-
-    Though this unmasker targets cancelleds, it can be used more
-    generally to capture and unwrap masked excs detected as
-    `.__context__` values which were suppressed by any error type
-    passed in `unmask_from`.
-
-    -------------
-    STILL-TODO ??
-    -------------
-    -[ ] support for egs which have multiple masked entries in
-        `maybe_eg.exceptions`, in which case we should unmask the
-        individual sub-excs but maintain the eg-parent's form right?
-
-    '''
-    from tractor.devx.debug import (
-        BoxedMaybeException,
-        pause,
-    )
-    boxed_maybe_exc = BoxedMaybeException(
-        raise_on_exit=raise_unmasked,
-    )
-    matching: list[BaseException]|None = None
-    maybe_eg: ExceptionGroup|None
-
-    if tn:
-        try:  # handle egs
-            yield boxed_maybe_exc
-            return
-        except* unmask_from as _maybe_eg:
-            maybe_eg = _maybe_eg
-            matches: ExceptionGroup
-            matches, _ = maybe_eg.split(
-                unmask_from
-            )
-            if not matches:
-                raise
-
-            matching: list[BaseException] = matches.exceptions
-    else:
-        try:  # handle non-egs
-            yield boxed_maybe_exc
-            return
-        except unmask_from as _maybe_exc:
-            maybe_exc = _maybe_exc
-            matching: list[BaseException] = [
-                maybe_exc
-            ]
-
-        # XXX, only unmask-ed for debuggin!
-        # TODO, remove eventually..
-        except BaseException as _berr:
-            berr = _berr
-            await pause(shield=True)
-            raise berr
-
-    if matching is None:
-        raise
-
-    masked: list[tuple[BaseException, BaseException]] = []
-    for exc_match in matching:
-
-        if exc_ctx := find_masked_excs(
-            maybe_masker=exc_match,
-            unmask_from={unmask_from},
-        ):
-            masked.append((exc_ctx, exc_match))
-            boxed_maybe_exc.value = exc_match
-            note: str = (
-                f'\n'
-                f'^^WARNING^^ the above {exc_ctx!r} was masked by a {unmask_from!r}\n'
-            )
-            if extra_note:
-                note += (
-                    f'\n'
-                    f'{extra_note}\n'
-                )
-            exc_ctx.add_note(note)
-
-            if type(exc_match) in always_warn_on:
-                log.warning(note)
-
-            # await tractor.pause(shield=True)
-            if raise_unmasked:
-
-                if len(masked) < 2:
-                    raise exc_ctx from exc_match
-                else:
-                    # ?TODO, see above but, possibly unmasking sub-exc
-                    # entries if there are > 1
-                    await pause(shield=True)
-    else:
-        raise