Merge pull request #380 from goodboy/multi_ipc_testing

Multi ipc testing

.github/workflows/ci.yml

@@ -8,46 +8,70 @@ on:
   workflow_dispatch:
 
 jobs:
-
-  mypy:
-    name: 'MyPy'
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-
-      - name: Setup python
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.11'
-
-      - name: Install dependencies
-        run: pip install -U . --upgrade-strategy eager -r requirements-test.txt
-
-      - name: Run MyPy check
-        run: mypy tractor/ --ignore-missing-imports --show-traceback
-
+  # ------ sdist ------
   # test that we can generate a software distribution and install it
   # thus avoid missing file issues after packaging.
+  #
+  # -[x] produce sdist with uv
+  # ------ - ------
   sdist-linux:
     name: 'sdist'
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
-      - name: Setup python
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.11'
+      - name: Install latest uv
+        uses: astral-sh/setup-uv@v6
 
-      - name: Build sdist
-        run: python setup.py sdist --formats=zip
+      - name: Build sdist as tar.gz
+        run: uv build --sdist --python=3.13
 
-      - name: Install sdist from .zips
-        run: python -m pip install dist/*.zip
+      - name: Install sdist from .tar.gz
+        run: python -m pip install dist/*.tar.gz
+
+  # ------ type-check ------
+  # mypy:
+  #   name: 'MyPy'
+  #   runs-on: ubuntu-latest
+
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@v4
+
+  #     - name: Install latest uv
+  #       uses: astral-sh/setup-uv@v6
+
+  #     # faster due to server caching?
+  #     # https://docs.astral.sh/uv/guides/integration/github/#setting-up-python
+  #     - name: "Set up Python"
+  #       uses: actions/setup-python@v6
+  #       with:
+  #         python-version-file: "pyproject.toml"
+
+  #     # w uv
+  #     # - name: Set up Python
+  #     #   run: uv python install
+
+  #     - name: Setup uv venv
+  #       run: uv venv .venv --python=3.13
+
+  #     - name: Install
+  #       run: uv sync --dev
+
+  #     # TODO, ty cmd over repo
+  #     # - name: type check with ty
+  #     #   run: ty ./tractor/
+
+  #     # - uses: actions/cache@v3
+  #     #     name: Cache uv virtenv as default .venv
+  #     #     with:
+  #     #       path: ./.venv
+  #     #       key: venv-${{ hashFiles('uv.lock') }}
+
+  #     - name: Run MyPy check
+  #       run: mypy tractor/ --ignore-missing-imports --show-traceback
 
 
   testing-linux:
@@ -59,32 +83,45 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python: ['3.11']
+        python-version: ['3.13']
         spawn_backend: [
           'trio',
-          'mp_spawn',
-          'mp_forkserver',
+          # 'mp_spawn',
+          # 'mp_forkserver',
         ]
 
     steps:
 
-      - name: Checkout
-        uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
-      - name: Setup python
-        uses: actions/setup-python@v2
+      - name: 'Install uv + py-${{ matrix.python-version }}'
+        uses: astral-sh/setup-uv@v6
         with:
-          python-version: '${{ matrix.python }}'
+          python-version: ${{ matrix.python-version }}
 
-      - name: Install dependencies
-        run: pip install -U . -r requirements-test.txt -r requirements-docs.txt --upgrade-strategy eager
+      # GH way.. faster?
+      # - name: setup-python@v6
+      #   uses: actions/setup-python@v6
+      #   with:
+      #     python-version: '${{ matrix.python-version }}'
 
-      - name: List dependencies
-        run: pip list
+      # consider caching for speedups?
+      # https://docs.astral.sh/uv/guides/integration/github/#caching
+
+      - name: Install the project w uv
+        run: uv sync --all-extras --dev
+
+      # - name: Install dependencies
+      #   run: pip install -U . -r requirements-test.txt -r requirements-docs.txt --upgrade-strategy eager
+
+      - name: List deps tree
+        run: uv tree
 
       - name: Run tests
-        run: pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
+        run: uv run pytest tests/ --spawn-backend=${{ matrix.spawn_backend }} -rsx
 
+  # XXX legacy NOTE XXX
+  #
   # We skip 3.10 on windows for now due to not having any collabs to
   # debug the CI failures. Anyone wanting to hack and solve them is very
   # welcome, but our primary user base is not using that OS.

docs/README.rst

@@ -1,8 +1,5 @@
 |logo| ``tractor``: distributed structurred concurrency
 
-|gh_actions|
-|docs|
-
 ``tractor`` is a `structured concurrency`_ (SC), multi-processing_ runtime built on trio_.
 
 Fundamentally, ``tractor`` provides parallelism via
@@ -66,6 +63,13 @@ Features
   - (WIP) a ``TaskMngr``: one-cancels-one style nursery supervisor.
 
 
+Status of `main` / infra
+------------------------
+
+- |gh_actions|
+- |docs|
+
+
 Install
 -------
 ``tractor`` is still in a *alpha-near-beta-stage* for many
@@ -689,9 +693,11 @@ channel`_!
 .. _msgspec: https://jcristharif.com/msgspec/
 .. _guest: https://trio.readthedocs.io/en/stable/reference-lowlevel.html?highlight=guest%20mode#using-guest-mode-to-run-trio-on-top-of-other-event-loops
 
-
-.. |gh_actions| image:: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fgoodboy%2Ftractor%2Fbadge&style=popout-square
-    :target: https://actions-badge.atrox.dev/goodboy/tractor/goto
+..
+   NOTE, on generating badge links from the UI
+   https://docs.github.com/en/actions/how-tos/monitoring-and-troubleshooting-workflows/monitoring-workflows/adding-a-workflow-status-badge?ref=gitguardian-blog-automated-secrets-detection#using-the-ui
+.. |gh_actions| image:: https://github.com/goodboy/tractor/actions/workflows/ci.yml/badge.svg?branch=main
+    :target: https://github.com/goodboy/tractor/actions/workflows/ci.yml
 
 .. |docs| image:: https://readthedocs.org/projects/tractor/badge/?version=latest
     :target: https://tractor.readthedocs.io/en/latest/?badge=latest

examples/debugging/asyncio_bp.py

@@ -29,7 +29,7 @@ async def bp_then_error(
     to_trio.send_nowait('start')
 
     # NOTE: what happens here inside the hook needs some refinement..
-    # => seems like it's still `.debug._set_trace()` but
+    # => seems like it's still `._debug._set_trace()` but
     #    we set `Lock.local_task_in_debug = 'sync'`, we probably want
     #    some further, at least, meta-data about the task/actor in debug
     #    in terms of making it clear it's `asyncio` mucking about.

examples/debugging/restore_builtin_breakpoint.py

@@ -5,7 +5,7 @@ import trio
 import tractor
 
 # ensure mod-path is correct!
-from tractor.devx.debug import (
+from tractor.devx._debug import (
     _sync_pause_from_builtin as _sync_pause_from_builtin,
 )
 
@@ -19,22 +19,19 @@ async def main() -> None:
     async with tractor.open_nursery(
         debug_mode=True,
         loglevel='devx',
-        maybe_enable_greenback=True,
-        # ^XXX REQUIRED to enable `breakpoint()` support (from sync
-        # fns) and thus required here to avoid an assertion err
-        # on the next line
-    ):
+    ) as an:
+        assert an
         assert (
             (pybp_var := os.environ['PYTHONBREAKPOINT'])
             ==
-            'tractor.devx.debug._sync_pause_from_builtin'
+            'tractor.devx._debug._sync_pause_from_builtin'
         )
 
         # TODO: an assert that verifies the hook has indeed been, hooked
         # XD
         assert (
             (pybp_hook := sys.breakpointhook)
-            is not tractor.devx.debug._set_trace
+            is not tractor.devx._debug._set_trace
         )
 
         print(

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',

examples/debugging/sync_bp.py

@@ -6,7 +6,7 @@ import tractor
 
 # TODO: only import these when not running from test harness?
 # can we detect `pexpect` usage maybe?
-# from tractor.devx.debug import (
+# from tractor.devx._debug import (
 #     get_lock,
 #     get_debug_req,
 # )

examples/threading/bg_thread_as_gen.py

@@ -1,360 +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/>.
-
-'''
-A shm-thread-as-generator-fn-ctx **prototype** in anticipation of
-free-threading (aka GIL-less threads) in py 3.13+
-
-Bo
-
-Main rationale,
-- binding a bg-thread to a "suspendable fn scope" means avoiding any
-  locking around shm-data-structures and, except for a single
-  `threading.Condition` (or better) for thread-context-switching,
-  enables a "pure-ish" style semantic for inter-thread
-  value-passing-IO between a "parent" and (bg) "child" shm-thread
-  where the only (allowed) data-flow would be via immutable values in
-  a "coroutine-style" using,
-
-  - parent-side:
-   |_ `callee_sent = gen.send(caller_sent)`
-
-  - child-side:
-   |_ `caller_sent = yield callee_sent`
-
-Related (official) reading,
-- https://docs.python.org/3/glossary.html#term-free-threading
-- https://peps.python.org/pep-0703/
- |_https://peps.python.org/pep-0703/#optimistic-avoiding-locking-in-dict-and-list-accesses
-
-
-'''
-from contextlib import (
-    contextmanager as cm,
-)
-import inspect
-# from functools import partial
-import time
-import threading
-from typing import (
-    Any,
-    Generator,
-)
-
-import tractor
-import trio
-
-
-log = tractor.log.get_console_log(
-    'info',
-    # ^ XXX causes latency with seed>=1e3
-    # 'warning',
-)
-_seed: int = int(1e3)
-
-
-def thread_gen(seed: int):
-    thr = threading.current_thread()
-    log.info(
-        f'thr: {thr.name} @ {thr.ident}\n'
-        f'    |_{thr!r}\n'
-        f'\n'
-        f'IN `thread_gen(seed={seed})`\n'
-        f'\n'
-        f'Starting range()-loop\n'
-    )
-    for i in range(seed):
-        log.info(
-            f'yielding i={i}\n'
-        )
-        from_main = yield i
-        log.info(
-            f'(from_main := {from_main}) = yield (i:={i})\n'
-        )
-        # time.sleep(0.0001)
-
-
-# TODO, how would we get the equiv from a pub trio-API?
-# -[ ] what about an inter-thread channel much like we have for
-# `to_asyncio` & guest mode??
-#
-# async def spawn_bg_thread_running_gen(fn):
-#     log.info('running trio.to_thread.run_sync()')
-#     await trio.to_thread.run_sync(
-#        partial(
-#          run_gen_in_thread,
-#          fn=fn,
-#          seed=_seed,
-#         )
-#     )
-
-
-# ?TODO? once correct, wrap this as a @deco-API?
-# -[ ] @generator_thread or similar?
-#
-def run_gen_in_thread(
-    cond: threading.Condition,
-    gen: Generator,
-    # ^NOTE, already closure-bound-in tgt generator-fn-instance which
-    # will be yielded to in the bg-thread!
-):
-    thr: threading.Thread = threading.current_thread()
-    log.info(
-        f'thr: {thr.name} @ {thr.ident}\n'
-        f'    |_{thr!r}\n'
-        f'\n'
-        f'IN `run_gen_in_thread(gen={gen})`\n'
-        f'\n'
-        f'entering gen blocking: {gen!r}\n'
-    )
-    try:
-        log.runtime('locking cond..')
-        with cond:
-            log.runtime('LOCKED cond..')
-            first_yielded = gen.send(None)
-            assert cond.to_yield is None
-            cond.to_yield = first_yielded
-            log.runtime('notifying cond..')
-            cond.notify()
-            log.runtime('waiting cond..')
-            cond.wait()
-
-            while (to_send := cond.to_send) is not None:
-                try:
-                    yielded = gen.send(to_send)
-                except StopIteration as siter:
-                    # TODO, check for return value?
-                    # if (ret := siter.value):
-                    #     cond.to_return = ret
-                    assert siter
-                    log.exception(f'{gen} exited')
-                    raise
-
-                cond.to_yield = yielded
-                log.runtime('LOOP notifying cond..')
-                cond.notify()
-                log.runtime('LOOP waiting cond..')
-                cond.wait()
-
-            # out = (yield from gen)
-            log.runtime('RELEASE-ing cond..')
-
-        # with cond block-end
-        log.runtime('RELEASE-ed cond..')
-
-    except BaseException:
-        log.exception(f'exited gen: {gen!r}\n')
-        raise
-
-    finally:
-        log.warning(
-            'Exiting bg thread!\n'
-        )
-        # TODO! better then this null setting naivety!
-        # -[ ] maybe an Unresolved or similar like for our `Context`?
-        #
-        # apply sentinel
-        cond.to_yield = None
-        with cond:
-            cond.notify_all()
-
-@cm
-def start_in_bg_thread(
-    gen: Generator,
-
-    # ?TODO?, is this useful to pass startup-ctx to the thread?
-    name: str|None = None,
-    **kwargs,
-
-) -> tuple[
-    threading.Thread,
-    Generator,
-    Any,
-]:
-    if not inspect.isgenerator(gen):
-        raise ValueError(
-            f'You must pass a `gen: Generator` instance\n'
-            f'gen={gen!r}\n'
-        )
-
-    # ?TODO? wrap this stuff into some kinda
-    # single-entry-inter-thread mem-chan?
-    #
-    cond = threading.Condition()
-    cond.to_send = None
-    cond.to_yield = None
-    cond.to_return = None
-
-    thr = threading.Thread(
-        target=run_gen_in_thread,
-        # args=(),  # ?TODO, useful?
-        kwargs={
-            'cond': cond,
-            'gen': gen,
-        } | kwargs,
-        name=name or gen.__name__,
-    )
-    log.info(
-        f'starting bg thread\n'
-        f'>(\n'
-        f'|_{thr!r}\n'
-    )
-    thr.start()
-
-    # TODO, Event or cond.wait() here to sync!?
-    time.sleep(0.01)
-
-    try:
-        log.info(f'locking cond {cond}..')
-        with cond:
-            log.runtime(f'LOCKED cond {cond}..')
-            first_yielded = cond.to_yield
-            log.runtime(f'cond.to_yield: {first_yielded}')
-
-            # delegator shim generator which proxies values from
-            # caller to callee-in-bg-thread
-            def wrapper():
-
-                # !?TODO, minimize # of yields during startup?
-                # -[ ] we can do i in <=1 manual yield pre while-loop no?
-                #
-                first_sent = yield first_yielded
-                cond.to_send = first_sent
-
-                # !TODO, exactly why we need a conditional-emit-sys!
-                log.runtime(
-                    f'cond.notify()\n'
-                    f'cond.to_send={cond.to_send!r}\n'
-                    f'cond.to_yield={cond.to_yield!r}\n'
-                )
-                cond.notify()
-                log.runtime(
-                    f'cond.wait()\n'
-                    f'cond.to_send={cond.to_send!r}\n'
-                    f'cond.to_yield={cond.to_yield!r}\n'
-                )
-                cond.wait()
-
-                to_yield = cond.to_yield
-                log.runtime(
-                    f'yielding to caller\n'
-                    f'cond.to_send={cond.to_send!r}\n'
-                    f'cond.to_yield={cond.to_yield!r}\n'
-                )
-                to_send = yield to_yield
-                log.runtime(
-                    f'post-yield to caller\n'
-                    f'to_send={to_send!r}\n'
-                    f'to_yield={to_yield!r}\n'
-                )
-
-                # !TODO, proper sentinel-to-break type-condition!
-                while to_send is not None:
-                    cond.to_send = to_send
-                    log.runtime(
-                        f'cond.nofity()\n'
-                        f'cond.to_send={cond.to_send!r}\n'
-                        f'cond.to_yield={cond.to_yield!r}\n'
-                    )
-                    cond.notify()
-                    if cond.to_yield is None:
-                        log.runtime(
-                            'BREAKING from wrapper-LOOP!\n'
-                        )
-                        break
-                        return
-
-                    log.runtime(
-                        f'cond.wait()\n'
-                        f'cond.to_send={cond.to_send!r}\n'
-                        f'cond.to_yield={cond.to_yield!r}\n'
-                    )
-                    cond.wait()
-
-                    log.runtime(
-                        f'yielding to caller\n'
-                        f'cond.to_send={cond.to_send!r}\n'
-                        f'cond.to_yield={cond.to_yield!r}\n'
-                    )
-                    to_yield = cond.to_yield
-                    to_send = yield to_yield
-                    log.runtime(
-                        f'post-yield to caller\n'
-                        f'to_send={to_send!r}\n'
-                        f'to_yield={to_yield!r}\n'
-                    )
-
-            log.info('creating wrapper..')
-            wrapper_gen = wrapper()
-            log.info(f'first .send(None): {wrapper_gen}\n')
-            first_yielded = wrapper_gen.send(None)
-            log.info(f'first yielded: {first_yielded}\n')
-
-            yield (
-                thr,
-                wrapper_gen,
-                first_yielded,
-            )
-    finally:
-        thr.join()
-        log.info(f'bg thread joined: {thr!r}')
-
-
-async def main():
-    async with trio.open_nursery() as tn:
-        assert tn
-
-        with (
-            start_in_bg_thread(
-                gen=(
-                    _gen:=thread_gen(
-                        seed=_seed,
-                    )
-                ),
-            ) as (
-                thr,
-                wrapped_gen,
-                first,
-            ),
-        ):
-            assert (
-                _gen is not wrapped_gen
-                and
-                wrapped_gen is not None
-            )
-            log.info(
-                'Entering wrapped_gen loop\n'
-            )
-
-            # NOTE, like our `Context.started` value
-            assert first == 0
-
-            # !TODO, proper sentinel-to-break type-condition!
-            yielded = first
-            while yielded is not None:
-
-                # XXX, compute callers new value to send to bg-thread
-                to_send = yielded * yielded
-
-                # send to bg-thread
-                yielded = wrapped_gen.send(to_send)
-                log.info(
-                    f'(yielded:={yielded!r}) = wrapped_gen.send((to_send:={to_send!r})'
-                )
-
-
-if __name__ == '__main__':
-    trio.run(main)

pyproject.toml

@@ -61,7 +61,8 @@ dev = [
   # `tractor.devx` tooling
   "greenback>=1.2.1,<2",
   "stackscope>=0.2.2,<0.3",
-  "typing-extensions>=4.13.2",  # needed for stackscope
+  # ^ requires this?
+  "typing-extensions>=4.14.1",
   "pyperclip>=1.9.0",
   "prompt-toolkit>=3.0.50",
   "xonsh>=0.19.2",

tests/conftest.py

@@ -103,7 +103,7 @@ def sig_prog(
 def daemon(
     debug_mode: bool,
     loglevel: str,
-    testdir: pytest.Pytester,
+    testdir,
     reg_addr: tuple[str, int],
     tpt_proto: str,
 

tests/devx/conftest.py

@@ -2,11 +2,9 @@
 `tractor.devx.*` tooling sub-pkg test space.
 
 '''
-from __future__ import annotations
 import time
 from typing import (
     Callable,
-    TYPE_CHECKING,
 )
 
 import pytest
@@ -18,7 +16,7 @@ from pexpect.spawnbase import SpawnBase
 from tractor._testing import (
     mk_cmd,
 )
-from tractor.devx.debug import (
+from tractor.devx._debug import (
     _pause_msg as _pause_msg,
     _crash_msg as _crash_msg,
     _repl_fail_msg as _repl_fail_msg,
@@ -28,22 +26,14 @@ from ..conftest import (
     _ci_env,
 )
 
-if TYPE_CHECKING:
-    from pexpect import pty_spawn
-
-
-# a fn that sub-instantiates a `pexpect.spawn()`
-# and returns it.
-type PexpectSpawner = Callable[[str], pty_spawn.spawn]
-
 
 @pytest.fixture
 def spawn(
-    start_method: str,
+    start_method,
     testdir: pytest.Pytester,
     reg_addr: tuple[str, int],
 
-) -> PexpectSpawner:
+) -> Callable[[str], None]:
     '''
     Use the `pexpect` module shipped via `testdir.spawn()` to
     run an `./examples/..` script by name.
@@ -69,7 +59,7 @@ def spawn(
     def _spawn(
         cmd: str,
         **mkcmd_kwargs,
-    ) -> pty_spawn.spawn:
+    ):
         unset_colors()
         return testdir.spawn(
             cmd=mk_cmd(
@@ -83,7 +73,7 @@ def spawn(
         )
 
     # such that test-dep can pass input script name.
-    return _spawn  # the `PexpectSpawner`, type alias.
+    return _spawn
 
 
 @pytest.fixture(
@@ -121,7 +111,7 @@ def ctlc(
         # XXX: disable pygments highlighting for auto-tests
         # since some envs (like actions CI) will struggle
         # the the added color-char encoding..
-        from tractor.devx.debug import TractorConfig
+        from tractor.devx._debug import TractorConfig
         TractorConfig.use_pygements = False
 
     yield use_ctlc

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?
@@ -317,6 +310,7 @@ def test_subactor_breakpoint(
 
     assert in_prompt_msg(
         child, [
+        'MessagingError:',
         'RemoteActorError:',
          "('breakpoint_forever'",
          'bdb.BdbQuit',
@@ -534,7 +528,7 @@ def test_multi_daemon_subactors(
     # now the root actor won't clobber the bp_forever child
     # during it's first access to the debug lock, but will instead
     # wait for the lock to release, by the edge triggered
-    # ``devx.debug.Lock.no_remote_has_tty`` event before sending cancel messages
+    # ``devx._debug.Lock.no_remote_has_tty`` event before sending cancel messages
     # (via portals) to its underlings B)
 
     # at some point here there should have been some warning msg from
@@ -1069,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

@@ -13,13 +13,9 @@ TODO:
   when debugging a problem inside the stack vs. in their app.
 
 '''
-from __future__ import annotations
 import os
 import signal
 import time
-from typing import (
-    TYPE_CHECKING,
-)
 
 from .conftest import (
     expect,
@@ -33,12 +29,9 @@ from pexpect.exceptions import (
     EOF,
 )
 
-if TYPE_CHECKING:
-    from ..conftest import PexpectSpawner
-
 
 def test_shield_pause(
-    spawn: PexpectSpawner,
+    spawn,
 ):
     '''
     Verify the `tractor.pause()/.post_mortem()` API works inside an
@@ -116,11 +109,9 @@ def test_shield_pause(
         child.pid,
         signal.SIGINT,
     )
-    from tractor._supervise import _shutdown_msg
     expect(
         child,
-        # 'Shutting down actor runtime',
-        _shutdown_msg,
+        'Shutting down actor runtime',
         timeout=6,
     )
     assert_before(
@@ -135,7 +126,7 @@ def test_shield_pause(
 
 
 def test_breakpoint_hook_restored(
-    spawn: PexpectSpawner,
+    spawn,
 ):
     '''
     Ensures our actor runtime sets a custom `breakpoint()` hook
@@ -149,7 +140,6 @@ def test_breakpoint_hook_restored(
     child = spawn('restore_builtin_breakpoint')
 
     child.expect(PROMPT)
-    try:
     assert_before(
         child,
         [
@@ -159,12 +149,7 @@ def test_breakpoint_hook_restored(
             "first bp, tractor hook set",
         ]
     )
-    # XXX if the above raises `AssertionError`, without sending
-    # the final 'continue' cmd to the REPL-active sub-process,
-    # we'll hang waiting for that pexpect instance to terminate..
-    finally:
     child.sendline('c')
-
     child.expect(PROMPT)
     assert_before(
         child,

tests/ipc/test_multi_tpt.py

@@ -0,0 +1,95 @@
+'''
+Verify the `enable_transports` param drives various
+per-root/sub-actor IPC endpoint/server settings.
+
+'''
+from __future__ import annotations
+
+import pytest
+import trio
+import tractor
+from tractor import (
+    Actor,
+    Portal,
+    ipc,
+    msg,
+    _state,
+    _addr,
+)
+
+@tractor.context
+async def chk_tpts(
+    ctx: tractor.Context,
+    tpt_proto_key: str,
+):
+    rtvars = _state._runtime_vars
+    assert (
+        tpt_proto_key
+        in
+        rtvars['_enable_tpts']
+    )
+    actor: Actor = tractor.current_actor()
+    spec: msg.types.SpawnSpec = actor._spawn_spec
+    assert spec._runtime_vars == rtvars
+
+    # ensure individual IPC ep-addr types
+    serv: ipc._server.Server = actor.ipc_server
+    addr: ipc._types.Address
+    for addr in serv.addrs:
+        assert addr.proto_key == tpt_proto_key
+
+    # Actor delegate-props enforcement
+    assert (
+        actor.accept_addrs
+        ==
+        serv.accept_addrs
+    )
+
+    await ctx.started(serv.accept_addrs)
+
+
+# TODO, parametrize over mis-matched-proto-typed `registry_addrs`
+# since i seems to work in `piker` but not exactly sure if both tcp
+# & uds are being deployed then?
+#
+@pytest.mark.parametrize(
+    'tpt_proto_key',
+    ['tcp', 'uds'],
+    ids=lambda item: f'ipc_tpt={item!r}'
+)
+def test_root_passes_tpt_to_sub(
+    tpt_proto_key: str,
+    reg_addr: tuple,
+    debug_mode: bool,
+):
+    async def main():
+        async with tractor.open_nursery(
+            enable_transports=[tpt_proto_key],
+            registry_addrs=[reg_addr],
+            debug_mode=debug_mode,
+        ) as an:
+
+            assert (
+                tpt_proto_key
+                in
+                _state._runtime_vars['_enable_tpts']
+            )
+
+            ptl: Portal = await an.start_actor(
+                name='sub',
+                enable_modules=[__name__],
+            )
+            async with ptl.open_context(
+                chk_tpts,
+                tpt_proto_key=tpt_proto_key,
+            ) as (ctx, accept_addrs):
+
+                uw_addr: tuple
+                for uw_addr in accept_addrs:
+                    addr = _addr.wrap_address(uw_addr)
+                    assert addr.is_valid
+
+            # shudown sub-actor(s)
+            await an.cancel()
+
+    trio.run(main)

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_infected_asyncio.py

@@ -889,7 +889,7 @@ async def manage_file(
 
         # NOTE: turns out you don't even need to sched an aio task
         # since the original issue, even though seemingly was due to
-        # the guest-run being abandoned + a `.debug.pause()` inside
+        # the guest-run being abandoned + a `._debug.pause()` inside
         # `._runtime._async_main()` (which was originally trying to
         # debug the `.lifetime_stack` not closing), IS NOT actually
         # the core issue?
@@ -1101,7 +1101,7 @@ def test_sigint_closes_lifetime_stack(
 #    => completed using `.bestow_portal(task)` inside
 #     `.to_asyncio._run_asyncio_task()` right?
 #   -[ ] translation func to get from `asyncio` task calling to 
-#     `.debug.wait_for_parent_stdin_hijack()` which does root
+#     `._debug.wait_for_parent_stdin_hijack()` which does root
 #     call to do TTY locking.
 #
 def test_sync_breakpoint():

tests/test_inter_peer_cancellation.py

@@ -410,6 +410,7 @@ def test_peer_canceller(
     '''
     async def main():
         async with tractor.open_nursery(
+            # NOTE: to halt the peer tasks on ctxc, uncomment this.
             debug_mode=debug_mode,
         ) as an:
             canceller: Portal = await an.start_actor(

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_root_runtime.py

@@ -83,26 +83,3 @@ def test_implicit_root_via_first_nursery(
             assert tractor.current_actor().aid.name == 'root'
 
     trio.run(main)
-
-
-def test_runtime_vars_unset(
-    reg_addr: tuple,
-    debug_mode: bool
-):
-    '''
-    Ensure any `._state._runtime_vars` are restored to default values
-    after the root actor-runtime exits!
-
-    '''
-    assert not tractor._state._runtime_vars['_debug_mode']
-    async def main():
-        assert not tractor._state._runtime_vars['_debug_mode']
-        async with tractor.open_nursery(
-            debug_mode=True,
-        ):
-            assert tractor._state._runtime_vars['_debug_mode']
-
-        # after runtime closure, should be reverted!
-        assert not tractor._state._runtime_vars['_debug_mode']
-
-    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/_context.py

@@ -101,9 +101,6 @@ from ._state import (
     debug_mode,
     _ctxvar_Context,
 )
-from .trionics import (
-    collapse_eg,
-)
 # ------ - ------
 if TYPE_CHECKING:
     from ._portal import Portal
@@ -295,7 +292,7 @@ class Context:
     # - `._runtime._invoke()` will check this flag before engaging
     #   the crash handler REPL in such cases where the "callee"
     #   raises the cancellation,
-    # - `.devx.debug.lock_stdio_for_peer()` will set it to `False` if
+    # - `.devx._debug.lock_stdio_for_peer()` will set it to `False` if
     #   the global tty-lock has been configured to filter out some
     #   actors from being able to acquire the debugger lock.
     _enter_debugger_on_cancel: bool = True
@@ -743,8 +740,6 @@ class Context:
             # cancelled, NOT their reported canceller. IOW in the
             # latter case we're cancelled by someone else getting
             # cancelled.
-            #
-            # !TODO, switching to `Actor.aid` here!
             if (canc := error.canceller) == self._actor.uid:
                 whom: str = 'us'
                 self._canceller = canc
@@ -945,7 +940,7 @@ class Context:
         self.cancel_called = True
 
         header: str = (
-            f'Cancelling ctx from {side!r}-side\n'
+            f'Cancelling ctx from {side.upper()}-side\n'
         )
         reminfo: str = (
             # ' =>\n'
@@ -1256,8 +1251,8 @@ class Context:
 
             # ?XXX, should already be set in `._deliver_msg()` right?
             if self._outcome_msg is not Unresolved:
-                # from .devx import debug
-                # await debug.pause()
+                # from .devx import _debug
+                # await _debug.pause()
                 assert self._outcome_msg is outcome_msg
             else:
                 self._outcome_msg = outcome_msg
@@ -2028,8 +2023,10 @@ async def open_context_from_portal(
     ctxc_from_callee: ContextCancelled|None = None
     try:
         async with (
-            collapse_eg(),
-            trio.open_nursery() as tn,
+            trio.open_nursery(
+                strict_exception_groups=False,
+            ) as tn,
+
             msgops.maybe_limit_plds(
                 ctx=ctx,
                 spec=ctx_meta.get('pld_spec'),
@@ -2190,7 +2187,7 @@ async def open_context_from_portal(
         #   debugging the tractor-runtime itself using it's
         #   own `.devx.` tooling!
         # 
-        # await debug.pause()
+        # await _debug.pause()
 
         # CASE 2: context was cancelled by local task calling
         # `.cancel()`, we don't raise and the exit block should
@@ -2257,7 +2254,7 @@ async def open_context_from_portal(
         # NOTE: `Context.cancel()` is conversely NEVER CALLED in
         # the `ContextCancelled` "self cancellation absorbed" case
         # handled in the block above ^^^ !!
-        # await debug.pause()
+        # await _debug.pause()
         # log.cancel(
         match scope_err:
             case trio.Cancelled:
@@ -2272,11 +2269,11 @@ async def open_context_from_portal(
         )
 
         if debug_mode():
-            # async with debug.acquire_debug_lock(portal.actor.uid):
+            # async with _debug.acquire_debug_lock(portal.actor.uid):
             #     pass
             # TODO: factor ^ into below for non-root cases?
             #
-            from .devx.debug import maybe_wait_for_debugger
+            from .devx._debug import maybe_wait_for_debugger
             was_acquired: bool = await maybe_wait_for_debugger(
                 # header_msg=(
                 #     'Delaying `ctx.cancel()` until debug lock '
@@ -2339,8 +2336,8 @@ async def open_context_from_portal(
                 raise
 
             # yes this worx!
-            # from .devx import debug
-            # await debug.pause()
+            # from .devx import _debug
+            # await _debug.pause()
 
             # an exception type boxed in a `RemoteActorError`
             # is returned (meaning it was obvi not raised)
@@ -2375,7 +2372,7 @@ async def open_context_from_portal(
         # where the root is waiting on the lock to clear but the
         # child has already cleared it and clobbered IPC.
         if debug_mode():
-            from .devx.debug import maybe_wait_for_debugger
+            from .devx._debug import maybe_wait_for_debugger
             await maybe_wait_for_debugger()
 
         # though it should be impossible for any tasks

tractor/_discovery.py

@@ -28,10 +28,7 @@ from typing import (
 from contextlib import asynccontextmanager as acm
 
 from tractor.log import get_logger
-from .trionics import (
-    gather_contexts,
-    collapse_eg,
-)
+from .trionics import gather_contexts
 from .ipc import _connect_chan, Channel
 from ._addr import (
     UnwrappedAddress,
@@ -51,7 +48,6 @@ from ._state import (
 
 if TYPE_CHECKING:
     from ._runtime import Actor
-    from .ipc._server import IPCServer
 
 
 log = get_logger(__name__)
@@ -83,7 +79,7 @@ async def get_registry(
         )
     else:
         # TODO: try to look pre-existing connection from
-        # `IPCServer._peers` and use it instead?
+        # `Server._peers` and use it instead?
         async with (
             _connect_chan(addr) as chan,
             open_portal(chan) as regstr_ptl,
@@ -91,6 +87,7 @@ async def get_registry(
             yield regstr_ptl
 
 
+
 @acm
 async def get_root(
     **kwargs,
@@ -114,18 +111,23 @@ def get_peer_by_name(
 ) -> list[Channel]|None:  # at least 1
     '''
     Scan for an existing connection (set) to a named actor
-    and return any channels from `IPCServer._peers: dict`.
+    and return any channels from `Server._peers: dict`.
 
     This is an optimization method over querying the registrar for
     the same info.
 
     '''
     actor: Actor = current_actor()
-    server: IPCServer = actor.ipc_server
-    to_scan: dict[tuple, list[Channel]] = server._peers.copy()
-    pchan: Channel|None = actor._parent_chan
-    if pchan:
-        to_scan[pchan.uid].append(pchan)
+    to_scan: dict[tuple, list[Channel]] = actor.ipc_server._peers.copy()
+
+    # TODO: is this ever needed? creates a duplicate channel on actor._peers
+    # when multiple find_actor calls are made to same actor from a single ctx
+    # which causes actor exit to hang waiting forever on
+    # `actor._no_more_peers.wait()` in `_runtime.async_main`
+
+    # pchan: Channel|None = actor._parent_chan
+    # if pchan and pchan.uid not in to_scan:
+    #     to_scan[pchan.uid].append(pchan)
 
     for aid, chans in to_scan.items():
         _, peer_name = aid
@@ -251,12 +253,9 @@ async def find_actor(
         for addr in registry_addrs
     )
     portals: list[Portal]
-    async with (
-        collapse_eg(),
-        gather_contexts(
+    async with gather_contexts(
         mngrs=maybe_portals,
-        ) as portals,
-    ):
+    ) as portals:
         # log.runtime(
         #     'Gathered portals:\n'
         #     f'{portals}'

tractor/_entry.py

@@ -21,7 +21,8 @@ Sub-process entry points.
 from __future__ import annotations
 from functools import partial
 import multiprocessing as mp
-# import os
+import os
+import textwrap
 from typing import (
     Any,
     TYPE_CHECKING,
@@ -34,11 +35,7 @@ from .log import (
     get_logger,
 )
 from . import _state
-from .devx import (
-    _frame_stack,
-    pformat,
-)
-# from .msg import pretty_struct
+from .devx import _debug
 from .to_asyncio import run_as_asyncio_guest
 from ._addr import UnwrappedAddress
 from ._runtime import (
@@ -106,6 +103,107 @@ def _mp_main(
         )
 
 
+# TODO: move this func to some kinda `.devx._conc_lang.py` eventually
+# as we work out our multi-domain state-flow-syntax!
+def nest_from_op(
+    input_op: str,
+    #
+    # ?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
+    #
+    # > is a "play operator" indicating (CPU bound)
+    #   exec/work/ops required at the "lowest level computing"
+    #
+    # execution primititves (tasks, threads, actors..) denote their
+    # lifetime with '(' and ')' since parentheses normally are used
+    # in many langs to denote function calls.
+    #
+    # starting = (
+    # >(  opening/starting; beginning of the thread-of-exec (toe?)
+    # (>  opened/started,  (finished spawning toe)
+    # |_<Task: blah blah..>  repr of toe, in py these look like <objs>
+    #
+    # >) closing/exiting/stopping,
+    # )> closed/exited/stopped,
+    # |_<Task: blah blah..>
+    #   [OR <), )< ?? ]
+    #
+    # ending = )
+    # >c) cancelling to close/exit
+    # c)> cancelled (caused close), OR?
+    #  |_<Actor: ..>
+    #   OR maybe "<c)" which better indicates the cancel being
+    #   "delivered/returned" / returned" to LHS?
+    #
+    # >x)  erroring to eventuall exit
+    # x)>  errored and terminated
+    #  |_<Actor: ...>
+    #
+    # scopes: supers/nurseries, IPC-ctxs, sessions, perms, etc.
+    # >{  opening
+    # {>  opened
+    # }>  closed
+    # >}  closing
+    #
+    # storage: like queues, shm-buffers, files, etc..
+    # >[  opening
+    # [>  opened
+    #  |_<FileObj: ..>
+    #
+    # >]  closing
+    # ]>  closed
+
+    # IPC ops: channels, transports, msging
+    # =>  req msg
+    # <=  resp msg
+    # <=> 2-way streaming (of msgs)
+    # <-  recv 1 msg
+    # ->  send 1 msg
+    #
+    # TODO: still not sure on R/L-HS approach..?
+    # =>(  send-req to exec start (task, actor, thread..)
+    # (<=  recv-req to ^
+    #
+    # (<=  recv-req ^
+    # <=(  recv-resp opened remote exec primitive
+    # <=)  recv-resp closed
+    #
+    # )<=c req to stop due to cancel
+    # c=>) req to stop due to cancel
+    #
+    # =>{  recv-req to open
+    # <={  send-status that it closed
+
+    tree_str: str,
+
+    # NOTE: so move back-from-the-left of the `input_op` by
+    # this amount.
+    back_from_op: int = 0,
+) -> 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.
+
+    '''
+    return (
+        f'{input_op}\n'
+        +
+        textwrap.indent(
+            tree_str,
+            prefix=(
+                len(input_op)
+                -
+                (back_from_op + 1)
+            ) * ' ',
+        )
+    )
+
+
 def _trio_main(
     actor: Actor,
     *,
@@ -117,7 +215,7 @@ def _trio_main(
     Entry point for a `trio_run_in_process` subactor.
 
     '''
-    _frame_stack.hide_runtime_frames()
+    _debug.hide_runtime_frames()
 
     _state._current_actor = actor
     trio_main = partial(
@@ -128,23 +226,30 @@ def _trio_main(
 
     if actor.loglevel is not None:
         get_console_log(actor.loglevel)
+        actor_info: str = (
+            f'|_{actor}\n'
+            f'  uid: {actor.uid}\n'
+            f'  pid: {os.getpid()}\n'
+            f'  parent_addr: {parent_addr}\n'
+            f'  loglevel: {actor.loglevel}\n'
+        )
         log.info(
-            f'Starting `trio` subactor from parent @ '
-            f'{parent_addr}\n'
+            'Starting new `trio` subactor:\n'
             +
-            pformat.nest_from_op(
+            nest_from_op(
                 input_op='>(',  # see syntax ideas above
-                text=f'{actor}',
+                tree_str=actor_info,
+                back_from_op=2,  # since "complete"
             )
         )
     logmeth = log.info
     exit_status: str = (
         'Subactor exited\n'
         +
-        pformat.nest_from_op(
+        nest_from_op(
             input_op=')>',  # like a "closed-to-play"-icon from super perspective
-            text=f'{actor}',
-            nest_indent=1,
+            tree_str=actor_info,
+            back_from_op=1,
         )
     )
     try:
@@ -159,9 +264,9 @@ def _trio_main(
         exit_status: str = (
             'Actor received KBI (aka an OS-cancel)\n'
             +
-            pformat.nest_from_op(
+            nest_from_op(
                 input_op='c)>',  # closed due to cancel (see above)
-                text=f'{actor}',
+                tree_str=actor_info,
             )
         )
     except BaseException as err:
@@ -169,9 +274,9 @@ def _trio_main(
         exit_status: str = (
             'Main actor task exited due to crash?\n'
             +
-            pformat.nest_from_op(
+            nest_from_op(
                 input_op='x)>',  # closed by error
-                text=f'{actor}',
+                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/_portal.py

@@ -39,10 +39,7 @@ import warnings
 
 import trio
 
-from .trionics import (
-    maybe_open_nursery,
-    collapse_eg,
-)
+from .trionics import maybe_open_nursery
 from ._state import (
     current_actor,
 )
@@ -118,10 +115,6 @@ class Portal:
 
     @property
     def chan(self) -> Channel:
-        '''
-        Ref to this ctx's underlying `tractor.ipc.Channel`.
-
-        '''
         return self._chan
 
     @property
@@ -181,17 +174,10 @@ class Portal:
 
         # not expecting a "main" result
         if self._expect_result_ctx is None:
-            peer_id: str = f'{self.channel.aid.reprol()!r}'
             log.warning(
-                f'Portal to peer {peer_id} will not deliver a final result?\n'
-                f'\n'
-                f'Context.result() can only be called by the parent of '
-                f'a sub-actor when it was spawned with '
-                f'`ActorNursery.run_in_actor()`'
-                f'\n'
-                f'Further this `ActorNursery`-method-API will deprecated in the'
-                f'near fututre!\n'
-            )
+                f"Portal for {self.channel.aid} not expecting a final"
+                " result?\nresult() should only be called if subactor"
+                " was spawned with `ActorNursery.run_in_actor()`")
             return NoResult
 
         # expecting a "main" result
@@ -224,7 +210,6 @@ class Portal:
         typname: str = type(self).__name__
         log.warning(
             f'`{typname}.result()` is DEPRECATED!\n'
-            f'\n'
             f'Use `{typname}.wait_for_result()` instead!\n'
         )
         return await self.wait_for_result(
@@ -236,10 +221,8 @@ class Portal:
         # terminate all locally running async generator
         # IPC calls
         if self._streams:
-            peer_id: str = f'{self.channel.aid.reprol()!r}'
-            report: str = (
-                f'Cancelling all msg-streams with {peer_id}\n'
-            )
+            log.cancel(
+                f"Cancelling all streams with {self.channel.aid}")
             for stream in self._streams.copy():
                 try:
                     await stream.aclose()
@@ -248,18 +231,10 @@ class Portal:
                     # (unless of course at some point down the road we
                     # won't expect this to always be the case or need to
                     # detect it for respawning purposes?)
-                    report += (
-                        f'->) {stream!r} already closed\n'
-                    )
-
-            log.cancel(report)
+                    log.debug(f"{stream} was already closed.")
 
     async def aclose(self):
-        log.debug(
-            f'Closing portal\n'
-            f'>}}\n'
-            f'|_{self}\n'
-        )
+        log.debug(f"Closing {self}")
         # TODO: once we move to implementing our own `ReceiveChannel`
         # (including remote task cancellation inside its `.aclose()`)
         # we'll need to .aclose all those channels here
@@ -285,18 +260,19 @@ class Portal:
         __runtimeframe__: int = 1  # noqa
 
         chan: Channel = self.channel
-        peer_id: str = f'{self.channel.aid.reprol()!r}'
         if not chan.connected():
             log.runtime(
-                'Peer {peer_id} is already disconnected\n'
-                '-> skipping cancel request..\n'
+                'This channel is already closed, skipping cancel request..'
             )
             return False
 
+        reminfo: str = (
+            f'c)=> {self.channel.aid}\n'
+            f'  |_{chan}\n'
+        )
         log.cancel(
-            f'Sending actor-runtime-cancel-req to peer\n'
-            f'\n'
-            f'c)=> {peer_id}\n'
+            f'Requesting actor-runtime cancel for peer\n\n'
+            f'{reminfo}'
         )
 
         # XXX the one spot we set it?
@@ -321,9 +297,8 @@ class Portal:
                 # may timeout and we never get an ack (obvi racy)
                 # but that doesn't mean it wasn't cancelled.
                 log.debug(
-                    f'May have failed to cancel peer?\n'
-                    f'\n'
-                    f'c)=?> {peer_id}\n'
+                    'May have failed to cancel peer?\n'
+                    f'{reminfo}'
                 )
 
             # if we get here some weird cancellation case happened
@@ -341,22 +316,22 @@ class Portal:
 
             TransportClosed,
         ) as tpt_err:
-            ipc_borked_report: str = (
-                f'IPC for actor already closed/broken?\n\n'
-                f'\n'
-                f'c)=x> {peer_id}\n'
+            report: str = (
+                f'IPC chan for actor already closed or broken?\n\n'
+                f'{self.channel.aid}\n'
+                f' |_{self.channel}\n'
             )
             match tpt_err:
                 case TransportClosed():
-                    log.debug(ipc_borked_report)
+                    log.debug(report)
                 case _:
-                    ipc_borked_report += (
+                    report += (
                         f'\n'
                         f'Unhandled low-level transport-closed/error during\n'
                         f'Portal.cancel_actor()` request?\n'
                         f'<{type(tpt_err).__name__}( {tpt_err} )>\n'
                     )
-                    log.warning(ipc_borked_report)
+                    log.warning(report)
 
             return False
 
@@ -513,13 +488,10 @@ class Portal:
                 with trio.CancelScope(shield=True):
                     await ctx.cancel()
 
-            except trio.ClosedResourceError as cre:
+            except trio.ClosedResourceError:
                 # if the far end terminates before we send a cancel the
                 # underlying transport-channel may already be closed.
-                log.cancel(
-                    f'Context.cancel() -> {cre!r}\n'
-                    f'cid: {ctx.cid!r} already closed?\n'
-                )
+                log.cancel(f'Context {ctx} was already closed?')
 
             # XXX: should this always be done?
             # await recv_chan.aclose()
@@ -586,13 +558,14 @@ async def open_portal(
     assert actor
     was_connected: bool = False
 
-    async with (
-        collapse_eg(),
-        maybe_open_nursery(
+    async with maybe_open_nursery(
         tn,
         shield=shield,
-        ) as tn,
-    ):
+        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:
 
         if not channel.connected():
             await channel.connect()

tractor/_root.py

@@ -37,12 +37,14 @@ import warnings
 
 import trio
 
-from . import _runtime
-from .devx import (
-    debug,
-    _frame_stack,
-    pformat as _pformat,
+from ._runtime import (
+    Actor,
+    Arbiter,
+    # TODO: rename and make a non-actor subtype?
+    # Arbiter as Registry,
+    async_main,
 )
+from .devx import _debug
 from . import _spawn
 from . import _state
 from . import log
@@ -56,19 +58,16 @@ from ._addr import (
     mk_uuid,
     wrap_address,
 )
-from .trionics import (
-    is_multi_cancelled,
-    collapse_eg,
-)
 from ._exceptions import (
     RuntimeFailure,
+    is_multi_cancelled,
 )
 
 
 logger = log.get_logger('tractor')
 
 
-# TODO: stick this in a `@acm` defined in `devx.debug`?
+# TODO: stick this in a `@acm` defined in `devx._debug`?
 # -[ ] also maybe consider making this a `wrapt`-deco to
 #     save an indent level?
 #
@@ -90,7 +89,7 @@ async def maybe_block_bp(
         debug_mode
         and maybe_enable_greenback
         and (
-            maybe_mod := await debug.maybe_init_greenback(
+            maybe_mod := await _debug.maybe_init_greenback(
                 raise_not_found=False,
             )
         )
@@ -100,7 +99,7 @@ async def maybe_block_bp(
             'Enabling `tractor.pause_from_sync()` support!\n'
         )
         os.environ['PYTHONBREAKPOINT'] = (
-            'tractor.devx.debug._sync_pause_from_builtin'
+            'tractor.devx._debug._sync_pause_from_builtin'
         )
         _state._runtime_vars['use_greenback'] = True
         bp_blocked = False
@@ -164,9 +163,7 @@ async def open_root_actor(
 
     # enables the multi-process debugger support
     debug_mode: bool = False,
-    maybe_enable_greenback: bool = False,  # `.pause_from_sync()/breakpoint()` support
-    # ^XXX NOTE^ the perf implications of use,
-    # https://greenback.readthedocs.io/en/latest/principle.html#performance
+    maybe_enable_greenback: bool = True,  # `.pause_from_sync()/breakpoint()` support
     enable_stack_on_sig: bool = False,
 
     # internal logging
@@ -181,7 +178,7 @@ async def open_root_actor(
 
     hide_tb: bool = True,
 
-    # XXX, proxied directly to `.devx.debug._maybe_enter_pm()`
+    # XXX, proxied directly to `.devx._debug._maybe_enter_pm()`
     # for REPL-entry logic.
     debug_filter: Callable[
         [BaseException|BaseExceptionGroup],
@@ -192,19 +189,13 @@ async def open_root_actor(
     # read-only state to sublayers?
     # extra_rt_vars: dict|None = None,
 
-) -> _runtime.Actor:
+) -> Actor:
     '''
-    Initialize the `tractor` runtime by starting a "root actor" in
-    a parent-most Python process.
-
-    All (disjoint) actor-process-trees-as-programs are created via
-    this entrypoint.
+    Runtime init entry point for ``tractor``.
 
     '''
     # XXX NEVER allow nested actor-trees!
-    if already_actor := _state.current_actor(
-        err_on_no_runtime=False,
-    ):
+    if already_actor := _state.current_actor(err_on_no_runtime=False):
         rtvs: dict[str, Any] = _state._runtime_vars
         root_mailbox: list[str, int] = rtvs['_root_mailbox']
         registry_addrs: list[list[str, int]] = rtvs['_registry_addrs']
@@ -237,12 +228,12 @@ async def open_root_actor(
                 f'enable_transports={enable_transports!r}\n'
             )
 
-        _frame_stack.hide_runtime_frames()
+        _debug.hide_runtime_frames()
         __tracebackhide__: bool = hide_tb
 
         # attempt to retreive ``trio``'s sigint handler and stash it
         # on our debugger lock state.
-        debug.DebugStatus._trio_handler = signal.getsignal(signal.SIGINT)
+        _debug.DebugStatus._trio_handler = signal.getsignal(signal.SIGINT)
 
         # mark top most level process as root actor
         _state._runtime_vars['_is_root'] = True
@@ -274,20 +265,14 @@ async def open_root_actor(
                 DeprecationWarning,
                 stacklevel=2,
             )
-            uw_reg_addrs = [arbiter_addr]
+            registry_addrs = [arbiter_addr]
 
-        uw_reg_addrs = registry_addrs
-        if not uw_reg_addrs:
-            uw_reg_addrs: list[UnwrappedAddress] = default_lo_addrs(
+        if not registry_addrs:
+            registry_addrs: list[UnwrappedAddress] = default_lo_addrs(
                 enable_transports
             )
 
-        # must exist by now since all below code is dependent
-        assert uw_reg_addrs
-        registry_addrs: list[Address] = [
-            wrap_address(uw_addr)
-            for uw_addr in uw_reg_addrs
-        ]
+        assert registry_addrs
 
         loglevel = (
             loglevel
@@ -296,14 +281,13 @@ async def open_root_actor(
 
         if (
             debug_mode
-            and
-            _spawn._spawn_method == 'trio'
+            and _spawn._spawn_method == 'trio'
         ):
             _state._runtime_vars['_debug_mode'] = True
 
             # expose internal debug module to every actor allowing for
             # use of ``await tractor.pause()``
-            enable_modules.append('tractor.devx.debug._tty_lock')
+            enable_modules.append('tractor.devx._debug')
 
             # if debug mode get's enabled *at least* use that level of
             # logging for some informative console prompts.
@@ -336,10 +320,10 @@ async def open_root_actor(
             enable_stack_on_sig()
 
         # closed into below ping task-func
-        ponged_addrs: list[Address] = []
+        ponged_addrs: list[UnwrappedAddress] = []
 
         async def ping_tpt_socket(
-            addr: Address,
+            addr: UnwrappedAddress,
             timeout: float = 1,
         ) -> None:
             '''
@@ -359,22 +343,17 @@ async def open_root_actor(
                 # be better to eventually have a "discovery" protocol
                 # with basic handshake instead?
                 with trio.move_on_after(timeout):
-                    async with _connect_chan(addr.unwrap()):
+                    async with _connect_chan(addr):
                         ponged_addrs.append(addr)
 
             except OSError:
-                # ?TODO, make this a "discovery" log level?
+                # TODO: make this a "discovery" log level?
                 logger.info(
-                    f'No root-actor registry found @ {addr!r}\n'
+                    f'No actor registry found @ {addr}\n'
                 )
 
-        # !TODO, this is basically just another (abstract)
-        # happy-eyeballs, so we should try for formalize it somewhere
-        # in a `.[_]discovery` ya?
-        #
         async with trio.open_nursery() as tn:
-            for uw_addr in uw_reg_addrs:
-                addr: Address = wrap_address(uw_addr)
+            for addr in registry_addrs:
                 tn.start_soon(
                     ping_tpt_socket,
                     addr,
@@ -396,35 +375,31 @@ async def open_root_actor(
                 f'Registry(s) seem(s) to exist @ {ponged_addrs}'
             )
 
-            actor = _runtime.Actor(
+            actor = Actor(
                 name=name or 'anonymous',
                 uuid=mk_uuid(),
                 registry_addrs=ponged_addrs,
                 loglevel=loglevel,
                 enable_modules=enable_modules,
             )
-            # **DO NOT** use the registry_addrs as the
-            # ipc-transport-server's bind-addrs as this is
-            # a new NON-registrar, ROOT-actor.
-            #
-            # XXX INSTEAD, bind random addrs using the same tpt
-            # proto.
+            # DO NOT use the registry_addrs as the transport server
+            # addrs for this new non-registar, root-actor.
             for addr in ponged_addrs:
+                waddr: Address = wrap_address(addr)
                 trans_bind_addrs.append(
-                    addr.get_random(
-                        bindspace=addr.bindspace,
-                    )
+                    waddr.get_random(bindspace=waddr.bindspace)
                 )
 
         # Start this local actor as the "registrar", aka a regular
         # actor who manages the local registry of "mailboxes" of
         # other process-tree-local sub-actors.
         else:
+
             # NOTE that if the current actor IS THE REGISTAR, the
             # following init steps are taken:
             # - the tranport layer server is bound to each addr
             #   pair defined in provided registry_addrs, or the default.
-            trans_bind_addrs = uw_reg_addrs
+            trans_bind_addrs = registry_addrs
 
             # - it is normally desirable for any registrar to stay up
             #   indefinitely until either all registered (child/sub)
@@ -435,8 +410,7 @@ async def open_root_actor(
             # https://github.com/goodboy/tractor/pull/348
             # https://github.com/goodboy/tractor/issues/296
 
-            # TODO: rename as `RootActor` or is that even necessary?
-            actor = _runtime.Arbiter(
+            actor = Arbiter(
                 name=name or 'registrar',
                 uuid=mk_uuid(),
                 registry_addrs=registry_addrs,
@@ -448,16 +422,6 @@ async def open_root_actor(
             # `.trio.run()`.
             actor._infected_aio = _state._runtime_vars['_is_infected_aio']
 
-        # NOTE, only set the loopback addr for the
-        # process-tree-global "root" mailbox since all sub-actors
-        # should be able to speak to their root actor over that
-        # channel.
-        raddrs: list[Address] = _state._runtime_vars['_root_addrs']
-        raddrs.extend(trans_bind_addrs)
-        # TODO, remove once we have also removed all usage;
-        # eventually all (root-)registry apis should expect > 1 addr.
-        _state._runtime_vars['_root_mailbox'] = raddrs[0]
-
         # Start up main task set via core actor-runtime nurseries.
         try:
             # assign process-local actor
@@ -465,27 +429,21 @@ async def open_root_actor(
 
             # start local channel-server and fake the portal API
             # NOTE: this won't block since we provide the nursery
-            report: str = f'Starting actor-runtime for {actor.aid.reprol()!r}\n'
-            if reg_addrs := actor.registry_addrs:
-                report += (
-                    '-> Opening new registry @ '
-                    +
-                    '\n'.join(
-                        f'@{addr}' for addr in reg_addrs
+            ml_addrs_str: str = '\n'.join(
+                f'@{addr}' for addr in trans_bind_addrs
             )
+            logger.info(
+                f'Starting local {actor.uid} on the following transport addrs:\n'
+                f'{ml_addrs_str}'
             )
-            logger.info(f'{report}\n')
 
-            # start runtime in a bg sub-task, yield to caller.
-            async with (
-                collapse_eg(),
-                trio.open_nursery() as root_tn,
+            # start the actor runtime in a new task
+            async with trio.open_nursery(
+                strict_exception_groups=False,
+                # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
+            ) as nursery:
 
-                # XXX, finally-footgun below?
-                # -> see note on why shielding.
-                # maybe_raise_from_masking_exc(),
-            ):
-                # `_runtime.async_main()` creates an internal nursery
+                # ``_runtime.async_main()`` creates an internal nursery
                 # and blocks here until any underlying actor(-process)
                 # tree has terminated thereby conducting so called
                 # "end-to-end" structured concurrency throughout an
@@ -493,9 +451,9 @@ async def open_root_actor(
                 # "actor runtime" primitives are SC-compat and thus all
                 # transitively spawned actors/processes must be as
                 # well.
-                await root_tn.start(
+                await nursery.start(
                     partial(
-                        _runtime.async_main,
+                        async_main,
                         actor,
                         accept_addrs=trans_bind_addrs,
                         parent_addr=None
@@ -511,7 +469,7 @@ async def open_root_actor(
                     # TODO, in beginning to handle the subsubactor with
                     # crashed grandparent cases..
                     #
-                    # was_locked: bool = await debug.maybe_wait_for_debugger(
+                    # was_locked: bool = await _debug.maybe_wait_for_debugger(
                     #     child_in_debug=True,
                     # )
                     # XXX NOTE XXX see equiv note inside
@@ -519,7 +477,7 @@ async def open_root_actor(
                     # non-root or root-that-opened-this-mahually case we
                     # wait for the local actor-nursery to exit before
                     # exiting the transport channel handler.
-                    entered: bool = await debug._maybe_enter_pm(
+                    entered: bool = await _debug._maybe_enter_pm(
                         err,
                         api_frame=inspect.currentframe(),
                         debug_filter=debug_filter,
@@ -552,43 +510,19 @@ async def open_root_actor(
                     #     for an in nurseries:
                     #         tempn.start_soon(an.exited.wait)
 
-                    op_nested_actor_repr: str = _pformat.nest_from_op(
-                        input_op='>) ',
-                        text=actor.pformat(),
-                        nest_prefix='|_',
-                    )
                     logger.info(
                         f'Closing down root actor\n'
-                        f'{op_nested_actor_repr}'
+                        f'>)\n'
+                        f'|_{actor}\n'
                     )
-                    # XXX, THIS IS A *finally-footgun*!
-                    # -> though already shields iternally it can
-                    # taskc here and mask underlying errors raised in
-                    # the try-block above?
-                    with trio.CancelScope(shield=True):
                     await actor.cancel(None)  # self cancel
         finally:
-            # revert all process-global runtime state
-            if (
-                debug_mode
-                and
-                _spawn._spawn_method == 'trio'
-            ):
-                _state._runtime_vars['_debug_mode'] = False
-
             _state._current_actor = None
             _state._last_actor_terminated = actor
-
-            sclang_repr: str = _pformat.nest_from_op(
-                input_op=')>',
-                text=actor.pformat(),
-                nest_prefix='|_',
-                nest_indent=1,
-            )
-
-            logger.info(
+            logger.runtime(
                 f'Root actor terminated\n'
-                f'{sclang_repr}'
+                f')>\n'
+                f' |_{actor}\n'
             )
 
 

tractor/_rpc.py

@@ -37,7 +37,6 @@ import warnings
 
 import trio
 from trio import (
-    Cancelled,
     CancelScope,
     Nursery,
     TaskStatus,
@@ -53,18 +52,13 @@ 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,
+    _debug,
     add_div,
-    pformat as _pformat,
 )
 from . import _state
 from .log import get_logger
@@ -73,7 +67,7 @@ from .msg import (
     MsgCodec,
     PayloadT,
     NamespacePath,
-    pretty_struct,
+    # pretty_struct,
     _ops as msgops,
 )
 from tractor.msg.types import (
@@ -221,18 +215,11 @@ async def _invoke_non_context(
             task_status.started(ctx)
             result = await coro
             fname: str = func.__name__
-
-            op_nested_task: str = _pformat.nest_from_op(
-                input_op=f')> cid: {ctx.cid!r}',
-                text=f'{ctx._task}',
-                nest_indent=1,  # under >
-            )
             log.runtime(
-                f'RPC task complete\n'
-                f'\n'
-                f'{op_nested_task}\n'
-                f'\n'
-                f')> {fname}() -> {pformat(result)}\n'
+                'RPC complete:\n'
+                f'task: {ctx._task}\n'
+                f'|_cid={ctx.cid}\n'
+                f'|_{fname}() -> {pformat(result)}\n'
             )
 
             # NOTE: only send result if we know IPC isn't down
@@ -263,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
@@ -279,7 +266,7 @@ async def _errors_relayed_via_ipc(
 
     # TODO: a debug nursery when in debug mode!
     # async with maybe_open_debugger_nursery() as debug_tn:
-    # => see matching comment in side `.debug._pause()`
+    # => see matching comment in side `._debug._pause()`
     rpc_err: BaseException|None = None
     try:
         yield  # run RPC invoke body
@@ -331,7 +318,7 @@ async def _errors_relayed_via_ipc(
                     'RPC task crashed, attempting to enter debugger\n'
                     f'|_{ctx}'
                 )
-                entered_debug = await debug._maybe_enter_pm(
+                entered_debug = await _debug._maybe_enter_pm(
                     err,
                     api_frame=inspect.currentframe(),
                 )
@@ -388,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 (
@@ -475,7 +462,7 @@ async def _invoke(
     ):
         # XXX for .pause_from_sync()` usage we need to make sure
         # `greenback` is boostrapped in the subactor!
-        await debug.maybe_init_greenback()
+        await _debug.maybe_init_greenback()
 
     # TODO: possibly a specially formatted traceback
     # (not sure what typing is for this..)?
@@ -629,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!
+            tn: trio.Nursery
+            rpc_ctx_cs: CancelScope
+            async with (
+                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'),
+                ),
+            ):
+                ctx._scope_nursery = tn
+                rpc_ctx_cs = ctx._scope = tn.cancel_scope
+                task_status.started(ctx)
+
+                # 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..
-            #
-            tn: Nursery
-            rpc_ctx_cs: CancelScope
-            async with (
-                collapse_eg(),
-                trio.open_nursery() 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.
                 res: Any|PayloadT = await coro
                 return_msg: Return|CancelAck = return_msg_type(
                     cid=cid,
@@ -672,8 +651,7 @@ async def _invoke(
                 ctx._result = res
                 log.runtime(
                     f'Sending result msg and exiting {ctx.side!r}\n'
-                    f'\n'
-                    f'{pretty_struct.pformat(return_msg)}\n'
+                    f'{return_msg}\n'
                 )
                 await chan.send(return_msg)
 
@@ -765,52 +743,43 @@ async def _invoke(
             BaseExceptionGroup,
             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()
+                # _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
-            await debug.maybe_wait_for_debugger()
+            await _debug.maybe_wait_for_debugger()
             ctx: Context = actor._contexts.pop((
                 chan.uid,
                 cid,
@@ -833,19 +802,16 @@ 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'
             else:
-                descr_str += f'\nwith final result {ctx.outcome!r}\n'
+                descr_str += f'\nand final result {ctx.outcome!r}\n'
 
             logmeth(
-                f'{message}\n'
-                f'\n'
-                f'{descr_str}\n'
+                message
+                +
+                descr_str
             )
 
 
@@ -1012,10 +978,12 @@ async def process_messages(
                         cid=cid,
                         kwargs=kwargs,
                     ):
+                        kwargs |= {'req_chan': chan}
+
                         # XXX NOTE XXX don't start entire actor
                         # runtime cancellation if this actor is
                         # currently in debug mode!
-                        pdb_complete: trio.Event|None = debug.DebugStatus.repl_release
+                        pdb_complete: trio.Event|None = _debug.DebugStatus.repl_release
                         if pdb_complete:
                             await pdb_complete.wait()
 
@@ -1030,14 +998,14 @@ async def process_messages(
                                 cid,
                                 chan,
                                 actor.cancel,
-                                kwargs | {'req_chan': chan},
+                                kwargs,
                                 is_rpc=False,
                                 return_msg_type=CancelAck,
                             )
 
                         log.runtime(
-                            'Cancelling RPC-msg-loop with peer\n'
-                            f'->c}} {chan.aid.reprol()}@[{chan.maddr}]\n'
+                            'Cancelling IPC transport msg-loop with peer:\n'
+                            f'|_{chan}\n'
                         )
                         loop_cs.cancel()
                         break
@@ -1050,7 +1018,7 @@ async def process_messages(
                     ):
                         target_cid: str = kwargs['cid']
                         kwargs |= {
-                            'requesting_aid': chan.aid,
+                            'requesting_uid': chan.uid,
                             'ipc_msg': msg,
 
                             # XXX NOTE! ONLY the rpc-task-owning
@@ -1086,34 +1054,21 @@ async def process_messages(
                         ns=ns,
                         func=funcname,
                         kwargs=kwargs,  # type-spec this? see `msg.types`
-                        uid=actor_uuid,
+                        uid=actorid,
                     ):
-                        if actor_uuid != chan.aid.uid:
-                            raise RuntimeError(
-                                f'IPC <Start> msg <-> chan.aid mismatch!?\n'
-                                f'Channel.aid = {chan.aid!r}\n'
-                                f'Start.uid = {actor_uuid!r}\n'
-                            )
-                        # await debug.pause()
-                        op_repr: str = 'Start <=) '
-                        req_repr: str = _pformat.nest_from_op(
-                            input_op=op_repr,
-                            op_suffix='',
-                            nest_prefix='',
-                            text=f'{chan}',
-
-                            nest_indent=len(op_repr)-1,
-                            rm_from_first_ln='<',
-                            # ^XXX, subtract -1 to account for
-                            # <Channel
-                            # ^_chevron to be stripped
-                        )
                         start_status: str = (
-                            'Handling RPC request\n'
-                            f'{req_repr}\n'
-                            f'\n'
-                            f'->{{ ipc-context-id: {cid!r}\n'
-                            f'->{{ nsp for fn: `{ns}.{funcname}({kwargs})`\n'
+                            'Handling RPC `Start` request\n'
+                            f'<= peer: {actorid}\n\n'
+                            f'  |_{chan}\n'
+                            f'  |_cid: {cid}\n\n'
+                            # f'  |_{ns}.{funcname}({kwargs})\n'
+                            f'>> {actor.uid}\n'
+                            f'  |_{actor}\n'
+                            f'   -> nsp: `{ns}.{funcname}({kwargs})`\n'
+
+                            # f'  |_{ns}.{funcname}({kwargs})\n\n'
+
+                            # f'{pretty_struct.pformat(msg)}\n'
                         )
 
                         # runtime-internal endpoint: `Actor.<funcname>`
@@ -1142,6 +1097,10 @@ async def process_messages(
                                 await chan.send(err_msg)
                                 continue
 
+                        start_status += (
+                            f'   -> func: {func}\n'
+                        )
+
                         # schedule a task for the requested RPC function
                         # in the actor's main "service nursery".
                         #
@@ -1149,7 +1108,7 @@ async def process_messages(
                         # supervision isolation? would avoid having to
                         # manage RPC tasks individually in `._rpc_tasks`
                         # table?
-                        start_status += '->( scheduling new task..\n'
+                        start_status += '   -> scheduling new task..\n'
                         log.runtime(start_status)
                         try:
                             ctx: Context = await actor._service_n.start(
@@ -1233,24 +1192,12 @@ async def process_messages(
             # END-OF `async for`:
             # IPC disconnected via `trio.EndOfChannel`, likely
             # due to a (graceful) `Channel.aclose()`.
-
-            chan_op_repr: str = '<=x] '
-            chan_repr: str = _pformat.nest_from_op(
-                input_op=chan_op_repr,
-                op_suffix='',
-                nest_prefix='',
-                text=chan.pformat(),
-                nest_indent=len(chan_op_repr)-1,
-                rm_from_first_ln='<',
-            )
             log.runtime(
-                f'IPC channel disconnected\n'
-                f'{chan_repr}\n'
-                f'\n'
-                f'->c) cancelling RPC tasks.\n'
+                f'channel for {chan.uid} disconnected, cancelling RPC tasks\n'
+                f'|_{chan}\n'
             )
             await actor.cancel_rpc_tasks(
-                req_aid=actor.aid,
+                req_uid=actor.uid,
                 # a "self cancel" in terms of the lifetime of the
                 # IPC connection which is presumed to be the
                 # source of any requests for spawned tasks.
@@ -1322,37 +1269,13 @@ async def process_messages(
     finally:
         # msg debugging for when he machinery is brokey
         if msg is None:
-            message: str = 'Exiting RPC-loop without receiving a msg?'
+            message: str = 'Exiting IPC msg loop without receiving a msg?'
         else:
-            task_op_repr: str = ')>'
-            task: trio.Task = trio.lowlevel.current_task()
-
-            # maybe add cancelled opt prefix
-            if task._cancel_status.effectively_cancelled:
-                task_op_repr = 'c' + task_op_repr
-
-            task_repr: str = _pformat.nest_from_op(
-                input_op=task_op_repr,
-                text=f'{task!r}',
-                nest_indent=1,
-            )
-            # chan_op_repr: str = '<=} '
-            # chan_repr: str = _pformat.nest_from_op(
-            #     input_op=chan_op_repr,
-            #     op_suffix='',
-            #     nest_prefix='',
-            #     text=chan.pformat(),
-            #     nest_indent=len(chan_op_repr)-1,
-            #     rm_from_first_ln='<',
-            # )
             message: str = (
-                f'Exiting RPC-loop with final msg\n'
-                f'\n'
-                # f'{chan_repr}\n'
-                f'{task_repr}\n'
-                f'\n'
-                f'{pretty_struct.pformat(msg)}'
-                f'\n'
+                'Exiting IPC msg loop with final msg\n\n'
+                f'<= peer: {chan.uid}\n'
+                f'  |_{chan}\n\n'
+                # f'{pretty_struct.pformat(msg)}'
             )
 
         log.runtime(message)

tractor/_runtime.py

@@ -55,7 +55,6 @@ from typing import (
     TYPE_CHECKING,
 )
 import uuid
-import textwrap
 from types import ModuleType
 import warnings
 
@@ -74,9 +73,6 @@ from tractor.msg import (
     pretty_struct,
     types as msgtypes,
 )
-from .trionics import (
-    collapse_eg,
-)
 from .ipc import (
     Channel,
     # IPCServer,  # causes cycles atm..
@@ -101,10 +97,7 @@ from ._exceptions import (
     MsgTypeError,
     unpack_error,
 )
-from .devx import (
-    debug,
-    pformat as _pformat
-)
+from .devx import _debug
 from ._discovery import get_registry
 from ._portal import Portal
 from . import _state
@@ -213,7 +206,7 @@ class Actor:
         *,
         enable_modules: list[str] = [],
         loglevel: str|None = None,
-        registry_addrs: list[Address]|None = None,
+        registry_addrs: list[UnwrappedAddress]|None = None,
         spawn_method: str|None = None,
 
         # TODO: remove!
@@ -234,7 +227,7 @@ class Actor:
 
         # state
         self._cancel_complete = trio.Event()
-        self._cancel_called_by: tuple[str, tuple]|None = None
+        self._cancel_called_by_remote: tuple[str, tuple]|None = None
         self._cancel_called: bool = False
 
         # retreive and store parent `__main__` data which
@@ -244,7 +237,7 @@ class Actor:
         # TODO? only add this when `is_debug_mode() == True` no?
         # always include debugging tools module
         if _state.is_root_process():
-            enable_modules.append('tractor.devx.debug._tty_lock')
+            enable_modules.append('tractor.devx._debug')
 
         self.enable_modules: dict[str, str] = get_mod_nsps2fps(
             mod_ns_paths=enable_modules,
@@ -256,12 +249,11 @@ class Actor:
         if arbiter_addr is not None:
             warnings.warn(
                 '`Actor(arbiter_addr=<blah>)` is now deprecated.\n'
-                'Use `registry_addrs: list[Address]` instead.',
+                'Use `registry_addrs: list[tuple]` instead.',
                 DeprecationWarning,
                 stacklevel=2,
             )
-
-            registry_addrs: list[Address] = [wrap_address(arbiter_addr)]
+            registry_addrs: list[UnwrappedAddress] = [arbiter_addr]
 
         # marked by the process spawning backend at startup
         # will be None for the parent most process started manually
@@ -300,10 +292,8 @@ class Actor:
         # input via the validator.
         self._reg_addrs: list[UnwrappedAddress] = []
         if registry_addrs:
-            _state._runtime_vars['_registry_addrs'] = self.reg_addrs = [
-                addr.unwrap()
-                for addr in registry_addrs
-            ]
+            self.reg_addrs: list[UnwrappedAddress] = registry_addrs
+            _state._runtime_vars['_registry_addrs'] = registry_addrs
 
     @property
     def aid(self) -> msgtypes.Aid:
@@ -349,125 +339,46 @@ class Actor:
     def pid(self) -> int:
         return self._aid.pid
 
-    @property
-    def repr_state(self) -> str:
-        if self.cancel_complete:
-            return 'cancelled'
-
-        elif canceller := self.cancel_caller:
-                return f' and cancel-called by {canceller}'
-
-        else:
-            return 'running'
-
-    def pformat(
-        self,
-        ds: str = ': ',
-        indent: int = 0,
-        privates: bool = False,
-    ) -> str:
-
-        fmtstr: str = f'|_id: {self.aid.reprol()!r}\n'
-        if privates:
-            aid_nest_prefix: str = '|_aid='
-            aid_field_repr: str = _pformat.nest_from_op(
-                input_op='',
-                text=pretty_struct.pformat(
-                    struct=self.aid,
-                    field_indent=2,
-                ),
-                op_suffix='',
-                nest_prefix=aid_nest_prefix,
-                nest_indent=0,
-            )
-            fmtstr: str = f'{aid_field_repr}'
-
+    def pformat(self) -> str:
+        ds: str = '='
+        parent_uid: tuple|None = None
         if rent_chan := self._parent_chan:
-            fmtstr += (
-                f"|_parent{ds}{rent_chan.aid.reprol()}\n"
-            )
+            parent_uid = rent_chan.uid
 
+        peers: list = []
         server: _server.IPCServer = self.ipc_server
         if server:
-            if privates:
-                server_repr: str = self._ipc_server.pformat(
-                    privates=privates,
-                )
-                # create field ln as a key-header indented under
-                # and up to the section's key prefix.
-                # ^XXX if we were to indent `repr(Server)` to
-                # '<key>: '
-                #  _here_^
-                server_repr: str = _pformat.nest_from_op(
-                    input_op='',  # nest as sub-obj
-                    op_suffix='',
-                    text=server_repr,
-                )
-                fmtstr += (
-                    f"{server_repr}"
-                )
-            else:
-                fmtstr += (
-                    f'|_ipc: {server.repr_state!r}\n'
-                )
+            peers: list[tuple] = list(server._peer_connected)
 
-        fmtstr += (
-            f'|_rpc: {len(self._rpc_tasks)} active tasks\n'
+        fmtstr: str = (
+            f' |_id: {self.aid!r}\n'
+            # f"   aid{ds}{self.aid!r}\n"
+            f"   parent{ds}{parent_uid}\n"
+            f'\n'
+            f' |_ipc: {len(peers)!r} connected peers\n'
+            f"   peers{ds}{peers!r}\n"
+            f"   ipc_server{ds}{self._ipc_server}\n"
+            f'\n'
+            f' |_rpc: {len(self._rpc_tasks)} tasks\n'
+            f"   ctxs{ds}{len(self._contexts)}\n"
+            f'\n'
+            f' |_runtime: ._task{ds}{self._task!r}\n'
+            f'   _spawn_method{ds}{self._spawn_method}\n'
+            f'   _actoruid2nursery{ds}{self._actoruid2nursery}\n'
+            f'   _forkserver_info{ds}{self._forkserver_info}\n'
+            f'\n'
+            f' |_state: "TODO: .repr_state()"\n'
+            f'   _cancel_complete{ds}{self._cancel_complete}\n'
+            f'   _cancel_called_by_remote{ds}{self._cancel_called_by_remote}\n'
+            f'   _cancel_called{ds}{self._cancel_called}\n'
         )
-
-        # TODO, actually fix the .repr_state impl/output?
-        # append ipc-ctx state summary
-        # ctxs: dict = self._contexts
-        # if ctxs:
-        #     ctx_states: dict[str, int] = {}
-        #     for ctx in self._contexts.values():
-        #         ctx_state: str = ctx.repr_state
-        #         cnt = ctx_states.setdefault(ctx_state, 0)
-        #         ctx_states[ctx_state] = cnt + 1
-
-        #     fmtstr += (
-        #         f"  ctxs{ds}{ctx_states}\n"
-        #     )
-
-        # runtime-state
-        task_name: str = '<dne>'
-        if task := self._task:
-            task_name: str = task.name
-        fmtstr += (
-            # TODO, this just like ctx?
-            f'|_state: {self.repr_state!r}\n'
-            f'  task: {task_name}\n'
-            f'  loglevel: {self.loglevel!r}\n'
-            f'  subactors_spawned: {len(self._actoruid2nursery)}\n'
+        return (
+            '<Actor(\n'
+            +
+            fmtstr
+            +
+            ')>\n'
         )
-        if not _state.is_root_process():
-            fmtstr += f'  spawn_method: {self._spawn_method!r}\n'
-
-        if privates:
-            fmtstr += (
-                # f'  actoruid2nursery{ds}{self._actoruid2nursery}\n'
-                f'  cancel_complete{ds}{self._cancel_complete}\n'
-                f'  cancel_called_by_remote{ds}{self._cancel_called_by}\n'
-                f'  cancel_called{ds}{self._cancel_called}\n'
-            )
-
-        if fmtstr:
-            fmtstr: str = textwrap.indent(
-                text=fmtstr,
-                prefix=' '*(1 + indent),
-            )
-
-        _repr: str = (
-            f'<{type(self).__name__}(\n'
-            f'{fmtstr}'
-            f')>\n'
-        )
-        if indent:
-            _repr: str = textwrap.indent(
-                text=_repr,
-                prefix=' '*indent,
-            )
-        return _repr
 
     __repr__ = pformat
 
@@ -475,11 +386,7 @@ class Actor:
     def reg_addrs(self) -> list[UnwrappedAddress]:
         '''
         List of (socket) addresses for all known (and contactable)
-        registry-service actors in "unwrapped" (i.e. IPC interchange
-        wire-compat) form.
-
-        If you are looking for the "wrapped" address form, use
-        `.registry_addrs` instead.
+        registry actors.
 
         '''
         return self._reg_addrs
@@ -498,14 +405,8 @@ class Actor:
 
         self._reg_addrs = addrs
 
-    @property
-    def registry_addrs(self) -> list[Address]:
-        return [wrap_address(uw_addr)
-                for uw_addr in self.reg_addrs]
-
     def load_modules(
         self,
-
     ) -> None:
         '''
         Load explicitly enabled python modules from local fs after
@@ -595,11 +496,11 @@ class Actor:
         queue.
 
         '''
-        aid: msgtypes.Aid = chan.aid
-        assert aid, f"`chan.aid` can't be {aid}"
+        uid: tuple[str, str] = chan.uid
+        assert uid, f"`chan.uid` can't be {uid}"
         try:
             ctx: Context = self._contexts[(
-                aid.uid,
+                uid,
                 cid,
 
                 # TODO: how to determine this tho?
@@ -610,7 +511,7 @@ class Actor:
                 'Ignoring invalid IPC msg!?\n'
                 f'Ctx seems to not/no-longer exist??\n'
                 f'\n'
-                f'<=? {aid.reprol()!r}\n'
+                f'<=? {uid}\n'
                 f'  |_{pretty_struct.pformat(msg)}\n'
             )
             match msg:
@@ -659,7 +560,6 @@ class Actor:
           msging session's lifetime.
 
         '''
-        # ?TODO, use Aid here as well?
         actor_uid = chan.uid
         assert actor_uid
         try:
@@ -1008,22 +908,6 @@ class Actor:
             None,  # self cancel all rpc tasks
         )
 
-    @property
-    def cancel_complete(self) -> bool:
-        return self._cancel_complete.is_set()
-
-    @property
-    def cancel_called(self) -> bool:
-        '''
-        Was this actor requested to cancel by a remote peer actor.
-
-        '''
-        return self._cancel_called_by is not None
-
-    @property
-    def cancel_caller(self) -> msgtypes.Aid|None:
-        return self._cancel_called_by
-
     async def cancel(
         self,
 
@@ -1048,18 +932,20 @@ class Actor:
 
         '''
         (
-            requesting_aid,  # Aid
-            requester_type,  # str
+            requesting_uid,
+            requester_type,
             req_chan,
             log_meth,
         ) = (
-            req_chan.aid,
+            req_chan.uid,
             'peer',
             req_chan,
             log.cancel,
+
         ) if req_chan else (
+
             # a self cancel of ALL rpc tasks
-            self.aid,
+            self.uid,
             'self',
             self,
             log.runtime,
@@ -1067,14 +953,14 @@ class Actor:
         # TODO: just use the new `Context.repr_rpc: str` (and
         # other) repr fields instead of doing this all manual..
         msg: str = (
-            f'Actor-runtime cancel request from {requester_type!r}\n'
+            f'Actor-runtime cancel request from {requester_type}\n\n'
+            f'<=c) {requesting_uid}\n'
+            f'  |_{self}\n'
             f'\n'
-            f'<=c)\n'
-            f'{self}'
         )
 
         # TODO: what happens here when we self-cancel tho?
-        self._cancel_called_by: tuple = requesting_aid
+        self._cancel_called_by_remote: tuple = requesting_uid
         self._cancel_called = True
 
         # cancel all ongoing rpc tasks
@@ -1082,7 +968,7 @@ class Actor:
 
             # kill any debugger request task to avoid deadlock
             # with the root actor in this tree
-            debug_req = debug.DebugStatus
+            debug_req = _debug.DebugStatus
             lock_req_ctx: Context = debug_req.req_ctx
             if (
                 lock_req_ctx
@@ -1092,7 +978,7 @@ class Actor:
                 msg += (
                     f'\n'
                     f'-> Cancelling active debugger request..\n'
-                    f'|_{debug.Lock.repr()}\n\n'
+                    f'|_{_debug.Lock.repr()}\n\n'
                     f'|_{lock_req_ctx}\n\n'
                 )
                 # lock_req_ctx._scope.cancel()
@@ -1102,7 +988,7 @@ class Actor:
 
             # self-cancel **all** ongoing RPC tasks
             await self.cancel_rpc_tasks(
-                req_aid=requesting_aid,
+                req_uid=requesting_uid,
                 parent_chan=None,
             )
 
@@ -1131,7 +1017,7 @@ class Actor:
         self,
         cid: str,
         parent_chan: Channel,
-        requesting_aid: msgtypes.Aid|None,
+        requesting_uid: tuple[str, str]|None,
 
         ipc_msg: dict|None|bool = False,
 
@@ -1169,7 +1055,7 @@ class Actor:
             log.runtime(
                 'Cancel request for invalid RPC task.\n'
                 'The task likely already completed or was never started!\n\n'
-                f'<= canceller: {requesting_aid}\n'
+                f'<= canceller: {requesting_uid}\n'
                 f'=> {cid}@{parent_chan.uid}\n'
                 f'  |_{parent_chan}\n'
             )
@@ -1177,12 +1063,9 @@ class Actor:
 
         log.cancel(
             'Rxed cancel request for RPC task\n'
-            f'{ctx._task!r} <=c) {requesting_aid}\n'
-            f'|_>> {ctx.repr_rpc}\n'
-
-            # f'|_{ctx._task}\n'
-            # f'   >> {ctx.repr_rpc}\n'
-
+            f'<=c) {requesting_uid}\n'
+            f' |_{ctx._task}\n'
+            f'    >> {ctx.repr_rpc}\n'
             # f'=> {ctx._task}\n'
             # f'  >> Actor._cancel_task() => {ctx._task}\n'
             # f'  |_ {ctx._task}\n\n'
@@ -1203,9 +1086,9 @@ class Actor:
         )
         if (
             ctx._canceller is None
-            and requesting_aid
+            and requesting_uid
         ):
-            ctx._canceller: tuple = requesting_aid.uid
+            ctx._canceller: tuple = requesting_uid
 
         # TODO: pack the RPC `{'cmd': <blah>}` msg into a ctxc and
         # then raise and pack it here?
@@ -1231,7 +1114,7 @@ class Actor:
 
         # wait for _invoke to mark the task complete
         flow_info: str = (
-            f'<= canceller: {requesting_aid}\n'
+            f'<= canceller: {requesting_uid}\n'
             f'=> ipc-parent: {parent_chan}\n'
             f'|_{ctx}\n'
         )
@@ -1248,7 +1131,7 @@ class Actor:
 
     async def cancel_rpc_tasks(
         self,
-        req_aid: msgtypes.Aid,
+        req_uid: tuple[str, str],
 
         # NOTE: when None is passed we cancel **all** rpc
         # tasks running in this actor!
@@ -1265,7 +1148,7 @@ class Actor:
         if not tasks:
             log.runtime(
                 'Actor has no cancellable RPC tasks?\n'
-                f'<= canceller: {req_aid.reprol()}\n'
+                f'<= canceller: {req_uid}\n'
             )
             return
 
@@ -1305,7 +1188,7 @@ class Actor:
         )
         log.cancel(
             f'Cancelling {descr} RPC tasks\n\n'
-            f'<=c) {req_aid} [canceller]\n'
+            f'<=c) {req_uid} [canceller]\n'
             f'{rent_chan_repr}'
             f'c)=> {self.uid} [cancellee]\n'
             f'  |_{self} [with {len(tasks)} tasks]\n'
@@ -1333,7 +1216,7 @@ class Actor:
             await self._cancel_task(
                 cid,
                 task_caller_chan,
-                requesting_aid=req_aid,
+                requesting_uid=req_uid,
             )
 
         if tasks:
@@ -1378,7 +1261,7 @@ class Actor:
         Return all IPC channels to the actor with provided `uid`.
 
         '''
-        return self._ipc_server._peers[uid]
+        return self._peers[uid]
 
     def is_infected_aio(self) -> bool:
         '''
@@ -1425,7 +1308,7 @@ async def async_main(
 
     # attempt to retreive ``trio``'s sigint handler and stash it
     # on our debugger state.
-    debug.DebugStatus._trio_handler = signal.getsignal(signal.SIGINT)
+    _debug.DebugStatus._trio_handler = signal.getsignal(signal.SIGINT)
 
     is_registered: bool = False
     try:
@@ -1433,8 +1316,6 @@ async def async_main(
         # establish primary connection with immediate parent
         actor._parent_chan: Channel|None = None
 
-        # is this a sub-actor?
-        # get runtime info from parent.
         if parent_addr is not None:
             (
                 actor._parent_chan,
@@ -1469,18 +1350,18 @@ async def async_main(
         # parent is kept alive as a resilient service until
         # cancellation steps have (mostly) occurred in
         # a deterministic way.
-        root_tn: trio.Nursery
-        async with (
-            collapse_eg(),
-            trio.open_nursery() as root_tn,
-        ):
-            actor._root_n = root_tn
+        async with trio.open_nursery(
+            strict_exception_groups=False,
+        ) as root_nursery:
+            actor._root_n = root_nursery
             assert actor._root_n
 
             ipc_server: _server.IPCServer
             async with (
-                collapse_eg(),
-                trio.open_nursery() as service_nursery,
+                trio.open_nursery(
+                    strict_exception_groups=False,
+                ) as service_nursery,
+
                 _server.open_ipc_server(
                     parent_tn=service_nursery,
                     stream_handler_tn=service_nursery,
@@ -1520,7 +1401,7 @@ async def async_main(
                 # try:
                 #     actor.load_modules()
                 # except ModuleNotFoundError as err:
-                #     debug.pause_from_sync()
+                #     _debug.pause_from_sync()
                 #     import pdbp; pdbp.set_trace()
                 #     raise
 
@@ -1531,6 +1412,9 @@ async def async_main(
 
                 # TODO: why is this not with the root nursery?
                 try:
+                    log.runtime(
+                        'Booting IPC server'
+                    )
                     eps: list = await ipc_server.listen_on(
                         accept_addrs=accept_addrs,
                         stream_handler_nursery=service_nursery,
@@ -1549,7 +1433,7 @@ async def async_main(
                     # tranport address bind errors - normally it's
                     # something silly like the wrong socket-address
                     # passed via a config or CLI Bo
-                    entered_debug: bool = await debug._maybe_enter_pm(
+                    entered_debug: bool = await _debug._maybe_enter_pm(
                         oserr,
                     )
                     if not entered_debug:
@@ -1562,6 +1446,18 @@ async def async_main(
                 # TODO, just read direct from ipc_server?
                 accept_addrs: list[UnwrappedAddress] = actor.accept_addrs
 
+                # NOTE: only set the loopback addr for the 
+                # process-tree-global "root" mailbox since
+                # all sub-actors should be able to speak to
+                # their root actor over that channel.
+                if _state._runtime_vars['_is_root']:
+                    raddrs: list[Address] = _state._runtime_vars['_root_addrs']
+                    for addr in accept_addrs:
+                        waddr: Address = wrap_address(addr)
+                        raddrs.append(addr)
+                    else:
+                        _state._runtime_vars['_root_mailbox'] = raddrs[0]
+
                 # Register with the arbiter if we're told its addr
                 log.runtime(
                     f'Registering `{actor.name}` => {pformat(accept_addrs)}\n'
@@ -1577,9 +1473,8 @@ async def async_main(
                         waddr = wrap_address(addr)
                         assert waddr.is_valid
                     except AssertionError:
-                        await debug.pause()
+                        await _debug.pause()
 
-                    # !TODO, get rid of the local-portal crap XD
                     async with get_registry(addr) as reg_portal:
                         for accept_addr in accept_addrs:
                             accept_addr = wrap_address(accept_addr)
@@ -1604,7 +1499,7 @@ async def async_main(
                 # start processing parent requests until our channel
                 # server is 100% up and running.
                 if actor._parent_chan:
-                    await root_tn.start(
+                    await root_nursery.start(
                         partial(
                             _rpc.process_messages,
                             chan=actor._parent_chan,
@@ -1616,9 +1511,8 @@ async def async_main(
                     # 'Blocking on service nursery to exit..\n'
                 )
             log.runtime(
-                'Service nursery complete\n'
-                '\n'
-                '->} waiting on root nursery to complete..\n'
+                "Service nursery complete\n"
+                "Waiting on root nursery to complete"
             )
 
         # Blocks here as expected until the root nursery is
@@ -1673,7 +1567,6 @@ async def async_main(
     finally:
         teardown_report: str = (
             'Main actor-runtime task completed\n'
-            '\n'
         )
 
         # ?TODO? should this be in `._entry`/`._root` mods instead?
@@ -1697,7 +1590,7 @@ async def async_main(
             # prevents any `infected_aio` actor from continuing
             # and any callbacks in the `ls` here WILL NOT be
             # called!!
-            # await debug.pause(shield=True)
+            # await _debug.pause(shield=True)
 
         ls.close()
 
@@ -1710,13 +1603,12 @@ async def async_main(
         #
         # if actor.name == 'brokerd.ib':
         #     with CancelScope(shield=True):
-        #         await debug.breakpoint()
+        #         await _debug.breakpoint()
 
         # Unregister actor from the registry-sys / registrar.
         if (
             is_registered
-            and
-            not actor.is_registrar
+            and not actor.is_registrar
         ):
             failed: bool = False
             for addr in actor.reg_addrs:
@@ -1751,8 +1643,7 @@ async def async_main(
             ipc_server.has_peers(check_chans=True)
         ):
             teardown_report += (
-                f'-> Waiting for remaining peers to clear..\n'
-                f'   {pformat(ipc_server._peers)}'
+                f'-> Waiting for remaining peers {ipc_server._peers} to clear..\n'
             )
             log.runtime(teardown_report)
             await ipc_server.wait_for_no_more_peers(
@@ -1760,23 +1651,15 @@ async def async_main(
             )
 
         teardown_report += (
-            '-]> all peer channels are complete.\n'
+            '-> All peer channels are complete\n'
         )
 
-    # op_nested_actor_repr: str = _pformat.nest_from_op(
-    #     input_op=')>',
-    #     text=actor.pformat(),
-    #     nest_prefix='|_',
-    #     nest_indent=1,  # under >
-    # )
     teardown_report += (
-        '-)> actor runtime main task exit.\n'
-        # f'{op_nested_actor_repr}'
+        'Actor runtime exiting\n'
+        f'>)\n'
+        f'|_{actor}\n'
     )
-    # if _state._runtime_vars['_is_root']:
-    #     log.info(teardown_report)
-    # else:
-    log.runtime(teardown_report)
+    log.info(teardown_report)
 
 
 # TODO: rename to `Registry` and move to `.discovery._registry`!
@@ -1909,7 +1792,7 @@ class Arbiter(Actor):
         waddr: Address = wrap_address(addr)
         if not waddr.is_valid:
             # should never be 0-dynamic-os-alloc
-            await debug.pause()
+            await _debug.pause()
 
         self._registry[uid] = addr
 

tractor/_spawn.py

@@ -34,9 +34,9 @@ from typing import (
 import trio
 from trio import TaskStatus
 
-from .devx import (
-    debug,
-    pformat as _pformat
+from .devx._debug import (
+    maybe_wait_for_debugger,
+    acquire_debug_lock,
 )
 from tractor._state import (
     current_actor,
@@ -51,17 +51,14 @@ from tractor._portal import Portal
 from tractor._runtime import Actor
 from tractor._entry import _mp_main
 from tractor._exceptions import ActorFailure
-from tractor.msg import (
-    types as msgtypes,
-    pretty_struct,
+from tractor.msg.types import (
+    Aid,
+    SpawnSpec,
 )
 
 
 if TYPE_CHECKING:
-    from ipc import (
-        _server,
-        Channel,
-    )
+    from ipc import IPCServer
     from ._supervise import ActorNursery
     ProcessType = TypeVar('ProcessType', mp.Process, trio.Process)
 
@@ -331,13 +328,12 @@ async def soft_kill(
     see `.hard_kill()`).
 
     '''
-    chan: Channel = portal.channel
-    peer_aid: msgtypes.Aid = chan.aid
+    peer_aid: Aid = portal.channel.aid
     try:
         log.cancel(
             f'Soft killing sub-actor via portal request\n'
             f'\n'
-            f'c)=> {peer_aid.reprol()}@[{chan.maddr}]\n'
+            f'(c=> {peer_aid}\n'
             f'  |_{proc}\n'
         )
         # wait on sub-proc to signal termination
@@ -345,7 +341,7 @@ async def soft_kill(
 
     except trio.Cancelled:
         with trio.CancelScope(shield=True):
-            await debug.maybe_wait_for_debugger(
+            await maybe_wait_for_debugger(
                 child_in_debug=_runtime_vars.get(
                     '_debug_mode', False
                 ),
@@ -469,7 +465,7 @@ async def trio_proc(
         "--uid",
         # TODO, how to pass this over "wire" encodings like
         # cmdline args?
-        # -[ ] maybe we can add an `msgtypes.Aid.min_tuple()` ?
+        # -[ ] maybe we can add an `Aid.min_tuple()` ?
         str(subactor.uid),
         # Address the child must connect to on startup
         "--parent_addr",
@@ -487,13 +483,12 @@ async def trio_proc(
 
     cancelled_during_spawn: bool = False
     proc: trio.Process|None = None
-    ipc_server: _server.Server = actor_nursery._actor.ipc_server
+    ipc_server: IPCServer = actor_nursery._actor.ipc_server
     try:
         try:
             proc: trio.Process = await trio.lowlevel.open_process(spawn_cmd, **proc_kwargs)
             log.runtime(
-                f'Started new child subproc\n'
-                f'(>\n'
+                'Started new child\n'
                 f'|_{proc}\n'
             )
 
@@ -512,10 +507,10 @@ async def trio_proc(
                 with trio.CancelScope(shield=True):
                     # don't clobber an ongoing pdb
                     if is_root_process():
-                        await debug.maybe_wait_for_debugger()
+                        await maybe_wait_for_debugger()
 
                     elif proc is not None:
-                        async with debug.acquire_debug_lock(subactor.uid):
+                        async with acquire_debug_lock(subactor.uid):
                             # soft wait on the proc to terminate
                             with trio.move_on_after(0.5):
                                 await proc.wait()
@@ -533,19 +528,14 @@ async def trio_proc(
 
         # send a "spawning specification" which configures the
         # initial runtime state of the child.
-        sspec = msgtypes.SpawnSpec(
+        sspec = SpawnSpec(
             _parent_main_data=subactor._parent_main_data,
             enable_modules=subactor.enable_modules,
             reg_addrs=subactor.reg_addrs,
             bind_addrs=bind_addrs,
             _runtime_vars=_runtime_vars,
         )
-        log.runtime(
-            f'Sending spawn spec to child\n'
-            f'{{}}=> {chan.aid.reprol()!r}\n'
-            f'\n'
-            f'{pretty_struct.pformat(sspec)}\n'
-        )
+        log.runtime(f'Sending spawn spec: {str(sspec)}')
         await chan.send(sspec)
 
         # track subactor in current nursery
@@ -573,7 +563,7 @@ async def trio_proc(
             # condition.
             await soft_kill(
                 proc,
-                trio.Process.wait,  # XXX, uses `pidfd_open()` below.
+                trio.Process.wait,
                 portal
             )
 
@@ -581,7 +571,8 @@ async def trio_proc(
             # tandem if not done already
             log.cancel(
                 'Cancelling portal result reaper task\n'
-                f'c)> {subactor.aid.reprol()!r}\n'
+                f'>c)\n'
+                f' |_{subactor.uid}\n'
             )
             nursery.cancel_scope.cancel()
 
@@ -590,24 +581,21 @@ async def trio_proc(
         # allowed! Do this **after** cancellation/teardown to avoid
         # killing the process too early.
         if proc:
-            reap_repr: str = _pformat.nest_from_op(
-                input_op='>x)',
-                text=subactor.pformat(),
-            )
             log.cancel(
                 f'Hard reap sequence starting for subactor\n'
-                f'{reap_repr}'
+                f'>x)\n'
+                f' |_{subactor}@{subactor.uid}\n'
             )
 
             with trio.CancelScope(shield=True):
                 # don't clobber an ongoing pdb
                 if cancelled_during_spawn:
                     # Try again to avoid TTY clobbering.
-                    async with debug.acquire_debug_lock(subactor.uid):
+                    async with acquire_debug_lock(subactor.uid):
                         with trio.move_on_after(0.5):
                             await proc.wait()
 
-                await debug.maybe_wait_for_debugger(
+                await maybe_wait_for_debugger(
                     child_in_debug=_runtime_vars.get(
                         '_debug_mode', False
                     ),
@@ -636,7 +624,7 @@ async def trio_proc(
                 #     acquire the lock and get notified of who has it,
                 #     check that uid against our known children?
                 # this_uid: tuple[str, str] = current_actor().uid
-                # await debug.acquire_debug_lock(this_uid)
+                # await acquire_debug_lock(this_uid)
 
                 if proc.poll() is None:
                     log.cancel(f"Attempting to hard kill {proc}")
@@ -739,7 +727,7 @@ async def mp_proc(
 
     log.runtime(f"Started {proc}")
 
-    ipc_server: _server.Server = actor_nursery._actor.ipc_server
+    ipc_server: IPCServer = actor_nursery._actor.ipc_server
     try:
         # wait for actor to spawn and connect back to us
         # channel should have handshake completed by the

tractor/_state.py

@@ -48,9 +48,8 @@ _current_actor: Actor|None = None  # type: ignore # noqa
 _last_actor_terminated: Actor|None = None
 
 # TODO: mk this a `msgspec.Struct`!
-# -[ ] type out all fields obvi!
-# -[ ] (eventually) mk wire-ready for monitoring?
 _runtime_vars: dict[str, Any] = {
+    '_debug_mode': False,
     # root of actor-process tree info
     '_is_root': False,  # bool
     '_root_mailbox': (None, None),  # tuple[str|None, str|None]
@@ -62,14 +61,10 @@ _runtime_vars: dict[str, Any] = {
     # registrar info
     '_registry_addrs': [],
 
-    # `debug_mode: bool` settings
-    '_debug_mode': False,  # bool
-    'repl_fixture': False,  # |AbstractContextManager[bool]
+    '_is_infected_aio': False,
+
     # for `tractor.pause_from_sync()` & `breakpoint()` support
     'use_greenback': False,
-
-    # infected-`asyncio`-mode: `trio` running as guest.
-    '_is_infected_aio': False,
 }
 
 

tractor/_streaming.py

@@ -426,8 +426,8 @@ class MsgStream(trio.abc.Channel):
             self._closed = re
 
         # if caught_eoc:
-        #     # from .devx import debug
-        #     # await debug.pause()
+        #     # from .devx import _debug
+        #     # await _debug.pause()
         #     with trio.CancelScope(shield=True):
         #         await rx_chan.aclose()
 

tractor/_supervise.py

@@ -21,6 +21,7 @@
 from contextlib import asynccontextmanager as acm
 from functools import partial
 import inspect
+from pprint import pformat
 from typing import (
     TYPE_CHECKING,
 )
@@ -30,10 +31,7 @@ import warnings
 import trio
 
 
-from .devx import (
-    debug,
-    pformat as _pformat,
-)
+from .devx._debug import maybe_wait_for_debugger
 from ._addr import (
     UnwrappedAddress,
     mk_uuid,
@@ -42,11 +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,
-    collapse_eg,
-)
 from ._exceptions import (
+    is_multi_cancelled,
     ContextCancelled,
 )
 from ._root import (
@@ -202,7 +197,7 @@ class ActorNursery:
             loglevel=loglevel,
 
             # verbatim relay this actor's registrar addresses
-            registry_addrs=current_actor().registry_addrs,
+            registry_addrs=current_actor().reg_addrs,
         )
         parent_addr: UnwrappedAddress = self._actor.accept_addr
         assert parent_addr
@@ -327,10 +322,9 @@ class ActorNursery:
         server: IPCServer = self._actor.ipc_server
 
         with trio.move_on_after(3) as cs:
-            async with (
-                collapse_eg(),
-                trio.open_nursery() as tn,
-            ):
+            async with trio.open_nursery(
+                strict_exception_groups=False,
+            ) as tn:
 
                 subactor: Actor
                 proc: trio.Process
@@ -423,10 +417,10 @@ async def _open_and_supervise_one_cancels_all_nursery(
     # `ActorNursery.start_actor()`).
 
     # errors from this daemon actor nursery bubble up to caller
-    async with (
-        collapse_eg(),
-        trio.open_nursery() as da_nursery,
-    ):
+    async with trio.open_nursery(
+        strict_exception_groups=False,
+        # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
+    ) as da_nursery:
         try:
             # This is the inner level "run in actor" nursery. It is
             # awaited first since actors spawned in this way (using
@@ -436,10 +430,11 @@ async def _open_and_supervise_one_cancels_all_nursery(
             # immediately raised for handling by a supervisor strategy.
             # As such if the strategy propagates any error(s) upwards
             # the above "daemon actor" nursery will be notified.
-            async with (
-                collapse_eg(),
-                trio.open_nursery() as ria_nursery,
-            ):
+            async with trio.open_nursery(
+                strict_exception_groups=False,
+                # ^XXX^ TODO? instead unpack any RAE as per "loose" style?
+            ) as ria_nursery:
+
                 an = ActorNursery(
                     actor,
                     ria_nursery,
@@ -456,7 +451,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
                     # the "hard join phase".
                     log.runtime(
                         'Waiting on subactors to complete:\n'
-                        f'>}} {len(an._children)}\n'
+                        f'{pformat(an._children)}\n'
                     )
                     an._join_procs.set()
 
@@ -470,7 +465,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
                     # will make the pdb repl unusable.
                     # Instead try to wait for pdb to be released before
                     # tearing down.
-                    await debug.maybe_wait_for_debugger(
+                    await maybe_wait_for_debugger(
                         child_in_debug=an._at_least_one_child_in_debug
                     )
 
@@ -546,7 +541,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
 
             # XXX: yet another guard before allowing the cancel
             # sequence in case a (single) child is in debug.
-            await debug.maybe_wait_for_debugger(
+            await maybe_wait_for_debugger(
                 child_in_debug=an._at_least_one_child_in_debug
             )
 
@@ -595,14 +590,9 @@ async def _open_and_supervise_one_cancels_all_nursery(
     # final exit
 
 
-_shutdown_msg: str = (
-    'Actor-runtime-shutdown'
-)
-
-# @api_frame
 @acm
+# @api_frame
 async def open_nursery(
-    *,  # named params only!
     hide_tb: bool = True,
     **kwargs,
     # ^TODO, paramspec for `open_root_actor()`
@@ -687,26 +677,17 @@ async def open_nursery(
         ):
             __tracebackhide__: bool = False
 
-
-        op_nested_an_repr: str = _pformat.nest_from_op(
-            input_op=')>',
-            text=f'{an}',
-            # nest_prefix='|_',
-            nest_indent=1,  # under >
+        msg: str = (
+            'Actor-nursery exited\n'
+            f'|_{an}\n'
         )
-        an_msg: str = (
-            f'Actor-nursery exited\n'
-            f'{op_nested_an_repr}\n'
-        )
-        # keep noise low during std operation.
-        log.runtime(an_msg)
 
         if implicit_runtime:
             # shutdown runtime if it was started and report noisly
             # that we're did so.
-            msg: str = (
-                '\n'
-                '\n'
-                f'{_shutdown_msg} )>\n'
-            )
+            msg += '=> Shutting down actor runtime <=\n'
             log.info(msg)
+
+        else:
+            # keep noise low during std operation.
+            log.runtime(msg)

tractor/_testing/__init__.py

@@ -26,7 +26,7 @@ import os
 import pathlib
 
 import tractor
-from tractor.devx.debug import (
+from tractor.devx._debug import (
     BoxedMaybeException,
 )
 from .pytest import (
@@ -37,9 +37,6 @@ from .fault_simulation import (
 )
 
 
-# TODO, use dulwhich for this instead?
-# -> we're going to likely need it (or something similar)
-#   for supporting hot-coad reload feats eventually anyway!
 def repodir() -> pathlib.Path:
     '''
     Return the abspath to the repo directory.

tractor/devx/__init__.py

@@ -20,7 +20,7 @@ Runtime "developer experience" utils and addons to aid our
 and working with/on the actor runtime.
 
 """
-from .debug import (
+from ._debug import (
     maybe_wait_for_debugger as maybe_wait_for_debugger,
     acquire_debug_lock as acquire_debug_lock,
     breakpoint as breakpoint,

tractor/devx/_frame_stack.py

@@ -20,18 +20,13 @@ as it pertains to improving the grok-ability of our runtime!
 
 '''
 from __future__ import annotations
-from contextlib import (
-    _GeneratorContextManager,
-    _AsyncGeneratorContextManager,
-)
 from functools import partial
 import inspect
-import textwrap
 from types import (
     FrameType,
     FunctionType,
     MethodType,
-    CodeType,
+    # CodeType,
 )
 from typing import (
     Any,
@@ -39,9 +34,6 @@ from typing import (
     Type,
 )
 
-import pdbp
-from tractor.log import get_logger
-import trio
 from tractor.msg import (
     pretty_struct,
     NamespacePath,
@@ -49,8 +41,6 @@ from tractor.msg import (
 import wrapt
 
 
-log = get_logger(__name__)
-
 # TODO: yeah, i don't love this and we should prolly just
 # write a decorator that actually keeps a stupid ref to the func
 # obj..
@@ -311,70 +301,3 @@ def api_frame(
 #     error_set: set[BaseException],
 # ) -> TracebackType:
 #     ...
-
-
-def hide_runtime_frames() -> dict[FunctionType, CodeType]:
-    '''
-    Hide call-stack frames for various std-lib and `trio`-API primitives
-    such that the tracebacks presented from our runtime are as minimized
-    as possible, particularly from inside a `PdbREPL`.
-
-    '''
-    # XXX HACKZONE XXX
-    #  hide exit stack frames on nurseries and cancel-scopes!
-    # |_ so avoid seeing it when the `pdbp` REPL is first engaged from
-    #    inside a `trio.open_nursery()` scope (with no line after it
-    #    in before the block end??).
-    #
-    # TODO: FINALLY got this workin originally with
-    #  `@pdbp.hideframe` around the `wrapper()` def embedded inside
-    #  `_ki_protection_decoratior()`.. which is in the module:
-    #  /home/goodboy/.virtualenvs/tractor311/lib/python3.11/site-packages/trio/_core/_ki.py
-    #
-    # -[ ] make an issue and patch for `trio` core? maybe linked
-    #    to the long outstanding `pdb` one below?
-    #   |_ it's funny that there's frame hiding throughout `._run.py`
-    #      but not where it matters on the below exit funcs..
-    #
-    # -[ ] provide a patchset for the lonstanding
-    #   |_ https://github.com/python-trio/trio/issues/1155
-    #
-    # -[ ] make a linked issue to ^ and propose allowing all the
-    #     `._core._run` code to have their `__tracebackhide__` value
-    #     configurable by a `RunVar` to allow getting scheduler frames
-    #     if desired through configuration?
-    #
-    # -[ ] maybe dig into the core `pdb` issue why the extra frame is shown
-    #      at all?
-    #
-    funcs: list[FunctionType] = [
-        trio._core._run.NurseryManager.__aexit__,
-        trio._core._run.CancelScope.__exit__,
-         _GeneratorContextManager.__exit__,
-         _AsyncGeneratorContextManager.__aexit__,
-         _AsyncGeneratorContextManager.__aenter__,
-         trio.Event.wait,
-    ]
-    func_list_str: str = textwrap.indent(
-        "\n".join(f.__qualname__ for f in funcs),
-        prefix=' |_ ',
-    )
-    log.devx(
-        'Hiding the following runtime frames by default:\n'
-        f'{func_list_str}\n'
-    )
-
-    codes: dict[FunctionType, CodeType] = {}
-    for ref in funcs:
-        # stash a pre-modified version of each ref's code-obj
-        # so it can be reverted later if needed.
-        codes[ref] = ref.__code__
-        pdbp.hideframe(ref)
-    #
-    # pdbp.hideframe(trio._core._run.NurseryManager.__aexit__)
-    # pdbp.hideframe(trio._core._run.CancelScope.__exit__)
-    # pdbp.hideframe(_GeneratorContextManager.__exit__)
-    # pdbp.hideframe(_AsyncGeneratorContextManager.__aexit__)
-    # pdbp.hideframe(_AsyncGeneratorContextManager.__aenter__)
-    # pdbp.hideframe(trio.Event.wait)
-    return codes

tractor/devx/_stackscope.py

@@ -49,7 +49,7 @@ from tractor import (
     _state,
     log as logmod,
 )
-from tractor.devx import debug
+from tractor.devx import _debug
 
 log = logmod.get_logger(__name__)
 
@@ -82,7 +82,7 @@ def dump_task_tree() -> None:
     if (
         current_sigint_handler
         is not
-        debug.DebugStatus._trio_handler
+        _debug.DebugStatus._trio_handler
     ):
         sigint_handler_report: str = (
             'The default `trio` SIGINT handler was replaced?!'
@@ -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/__init__.py

@@ -1,100 +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/>.
-
-'''
-Multi-actor debugging for da peeps!
-
-'''
-from __future__ import annotations
-from tractor.log import get_logger
-from ._repl import (
-    PdbREPL as PdbREPL,
-    mk_pdb as mk_pdb,
-    TractorConfig as TractorConfig,
-)
-from ._tty_lock import (
-    DebugStatus as DebugStatus,
-    DebugStateError as DebugStateError,
-)
-from ._trace import (
-    Lock as Lock,
-    _pause_msg as _pause_msg,
-    _repl_fail_msg as _repl_fail_msg,
-    _set_trace as _set_trace,
-    _sync_pause_from_builtin as _sync_pause_from_builtin,
-    breakpoint as breakpoint,
-    maybe_init_greenback as maybe_init_greenback,
-    maybe_import_greenback as maybe_import_greenback,
-    pause as pause,
-    pause_from_sync as pause_from_sync,
-)
-from ._post_mortem import (
-    BoxedMaybeException as BoxedMaybeException,
-    maybe_open_crash_handler as maybe_open_crash_handler,
-    open_crash_handler as open_crash_handler,
-    post_mortem as post_mortem,
-    _crash_msg as _crash_msg,
-    _maybe_enter_pm as _maybe_enter_pm,
-)
-from ._sync import (
-    maybe_wait_for_debugger as maybe_wait_for_debugger,
-    acquire_debug_lock as acquire_debug_lock,
-)
-from ._sigint import (
-    sigint_shield as sigint_shield,
-    _ctlc_ignore_header as _ctlc_ignore_header
-)
-
-log = get_logger(__name__)
-
-# ----------------
-# XXX PKG TODO XXX
-# ----------------
-# refine the internal impl and APIs!
-#
-# -[ ] rework `._pause()` and it's branch-cases for root vs.
-#     subactor:
-#  -[ ] `._pause_from_root()` + `_pause_from_subactor()`?
-#  -[ ]  do the de-factor based on bg-thread usage in
-#    `.pause_from_sync()` & `_pause_from_bg_root_thread()`.
-#  -[ ] drop `debug_func == None` case which is confusing af..
-#  -[ ]  factor out `_enter_repl_sync()` into a util func for calling
-#    the `_set_trace()` / `_post_mortem()` APIs?
-#
-# -[ ] figure out if we need `acquire_debug_lock()` and/or re-implement
-#    it as part of the `.pause_from_sync()` rework per above?
-#
-# -[ ] pair the `._pause_from_subactor()` impl with a "debug nursery"
-#   that's dynamically allocated inside the `._rpc` task thus
-#   avoiding the `._service_n.start()` usage for the IPC request?
-#  -[ ] see the TODO inside `._rpc._errors_relayed_via_ipc()`
-#
-# -[ ] impl a `open_debug_request()` which encaps all
-#   `request_root_stdio_lock()` task scheduling deats
-#   + `DebugStatus` state mgmt; which should prolly be re-branded as
-#   a `DebugRequest` type anyway AND with suppoort for bg-thread
-#   (from root actor) usage?
-#
-# -[ ] handle the `xonsh` case for bg-root-threads in the SIGINT
-#     handler!
-#   -[ ] do we need to do the same for subactors?
-#   -[ ] make the failing tests finally pass XD
-#
-# -[ ] simplify `maybe_wait_for_debugger()` to be a root-task only
-#     API?
-#   -[ ] currently it's implemented as that so might as well make it
-#     formal?

tractor/devx/debug/_post_mortem.py

@@ -1,410 +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/>.
-
-'''
-Post-mortem debugging APIs and surrounding machinery for both
-sync and async contexts.
-
-Generally we maintain the same semantics a `pdb.post.mortem()` but
-with actor-tree-wide sync/cooperation around any (sub)actor's use of
-the root's TTY.
-
-'''
-from __future__ import annotations
-import bdb
-from contextlib import (
-    AbstractContextManager,
-    contextmanager as cm,
-    nullcontext,
-)
-from functools import (
-    partial,
-)
-import inspect
-import sys
-import traceback
-from typing import (
-    Callable,
-    Sequence,
-    Type,
-    TYPE_CHECKING,
-)
-from types import (
-    TracebackType,
-    FrameType,
-)
-
-from msgspec import Struct
-import trio
-from tractor._exceptions import (
-    NoRuntime,
-)
-from tractor import _state
-from tractor._state import (
-    current_actor,
-    debug_mode,
-)
-from tractor.log import get_logger
-from tractor.trionics import (
-    is_multi_cancelled,
-)
-from ._trace import (
-    _pause,
-)
-from ._tty_lock import (
-    DebugStatus,
-)
-from ._repl import (
-    PdbREPL,
-    mk_pdb,
-    TractorConfig as TractorConfig,
-)
-
-if TYPE_CHECKING:
-    from trio.lowlevel import Task
-    from tractor._runtime import (
-        Actor,
-    )
-
-_crash_msg: str = (
-    'Opening a pdb REPL in crashed actor'
-)
-
-log = get_logger(__package__)
-
-
-class BoxedMaybeException(Struct):
-    '''
-    Box a maybe-exception for post-crash introspection usage
-    from the body of a `open_crash_handler()` scope.
-
-    '''
-    value: BaseException|None = None
-
-    # handler can suppress crashes dynamically
-    raise_on_exit: bool|Sequence[Type[BaseException]] = True
-
-    def pformat(self) -> str:
-        '''
-        Repr the boxed `.value` error in more-than-string
-        repr form.
-
-        '''
-        if not self.value:
-            return f'<{type(self).__name__}( .value=None )>'
-
-        return (
-            f'<{type(self.value).__name__}(\n'
-            f' |_.value = {self.value}\n'
-            f')>\n'
-        )
-
-    __repr__ = pformat
-
-
-def _post_mortem(
-    repl: PdbREPL,  # normally passed by `_pause()`
-
-    # XXX all `partial`-ed in by `post_mortem()` below!
-    tb: TracebackType,
-    api_frame: FrameType,
-
-    shield: bool = False,
-    hide_tb: bool = True,
-
-    # maybe pre/post REPL entry
-    repl_fixture: (
-        AbstractContextManager[bool]
-        |None
-    ) = None,
-
-    boxed_maybe_exc: BoxedMaybeException|None = None,
-
-) -> None:
-    '''
-    Enter the ``pdbpp`` port mortem entrypoint using our custom
-    debugger instance.
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    # maybe enter any user fixture
-    enter_repl: bool = DebugStatus.maybe_enter_repl_fixture(
-        repl=repl,
-        repl_fixture=repl_fixture,
-        boxed_maybe_exc=boxed_maybe_exc,
-    )
-    if not enter_repl:
-        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>
-
-    except NoRuntime:
-        actor_repr: str = '<no-actor-runtime?>'
-
-    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'
-
-    )
-
-    # 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,
-    )
-
-    # 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(
-    *,
-    tb: TracebackType|None = None,
-    api_frame: FrameType|None = None,
-    hide_tb: bool = False,
-
-    # TODO: support shield here just like in `pause()`?
-    # shield: bool = False,
-
-    **_pause_kwargs,
-
-) -> None:
-    '''
-    Our builtin async equivalient of `pdb.post_mortem()` which can be
-    used inside exception handlers.
-
-    It's also used for the crash handler when `debug_mode == True` ;)
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    tb: TracebackType = tb or sys.exc_info()[2]
-
-    # TODO: do upward stack scan for highest @api_frame and
-    # use its parent frame as the expected user-app code
-    # interact point.
-    api_frame: FrameType = api_frame or inspect.currentframe()
-
-    # TODO, move to submod `._pausing` or ._api? _trace
-    await _pause(
-        debug_func=partial(
-            _post_mortem,
-            api_frame=api_frame,
-            tb=tb,
-        ),
-        hide_tb=hide_tb,
-        **_pause_kwargs
-    )
-
-
-async def _maybe_enter_pm(
-    err: BaseException,
-    *,
-    tb: TracebackType|None = None,
-    api_frame: FrameType|None = None,
-    hide_tb: bool = False,
-
-    # only enter debugger REPL when returns `True`
-    debug_filter: Callable[
-        [BaseException|BaseExceptionGroup],
-        bool,
-    ] = lambda err: not is_multi_cancelled(err),
-    **_pause_kws,
-):
-    if (
-        debug_mode()
-
-        # NOTE: don't enter debug mode recursively after quitting pdb
-        # Iow, don't re-enter the repl if the `quit` command was issued
-        # by the user.
-        and not isinstance(err, bdb.BdbQuit)
-
-        # XXX: if the error is the likely result of runtime-wide
-        # cancellation, we don't want to enter the debugger since
-        # there's races between when the parent actor has killed all
-        # comms and when the child tries to contact said parent to
-        # acquire the tty lock.
-
-        # Really we just want to mostly avoid catching KBIs here so there
-        # might be a simpler check we can do?
-        and
-        debug_filter(err)
-    ):
-        api_frame: FrameType = api_frame or inspect.currentframe()
-        tb: TracebackType = tb or sys.exc_info()[2]
-        await post_mortem(
-            api_frame=api_frame,
-            tb=tb,
-            **_pause_kws,
-        )
-        return True
-
-    else:
-        return False
-
-
-# TODO: better naming and what additionals?
-# - [ ] optional runtime plugging?
-# - [ ] detection for sync vs. async code?
-# - [ ] specialized REPL entry when in distributed mode?
-# -[x] hide tb by def
-# - [x] allow ignoring kbi Bo
-@cm
-def open_crash_handler(
-    catch: set[BaseException] = {
-        BaseException,
-    },
-    ignore: set[BaseException] = {
-        KeyboardInterrupt,
-        trio.Cancelled,
-    },
-    hide_tb: bool = True,
-
-    repl_fixture: (
-        AbstractContextManager[bool]  # pre/post REPL entry
-        |None
-    ) = None,
-    raise_on_exit: bool|Sequence[Type[BaseException]] = True,
-):
-    '''
-    Generic "post mortem" crash handler using `pdbp` REPL debugger.
-
-    We expose this as a CLI framework addon to both `click` and
-    `typer` users so they can quickly wrap cmd endpoints which get
-    automatically wrapped to use the runtime's `debug_mode: bool`
-    AND `pdbp.pm()` around any code that is PRE-runtime entry
-    - any sync code which runs BEFORE the main call to
-      `trio.run()`.
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    # TODO, yield a `outcome.Error`-like boxed type?
-    # -[~] use `outcome.Value/Error` X-> frozen!
-    # -[x] write our own..?
-    # -[ ] consider just wtv is used by `pytest.raises()`?
-    #
-    boxed_maybe_exc = BoxedMaybeException(
-        raise_on_exit=raise_on_exit,
-    )
-    err: BaseException
-    try:
-        yield boxed_maybe_exc
-    except tuple(catch) as err:
-        boxed_maybe_exc.value = err
-        if (
-            type(err) not in ignore
-            and
-            not is_multi_cancelled(
-                err,
-                ignore_nested=ignore
-            )
-        ):
-            try:
-                # use our re-impl-ed version of `pdbp.xpm()`
-                _post_mortem(
-                    repl=mk_pdb(),
-                    tb=sys.exc_info()[2],
-                    api_frame=inspect.currentframe().f_back,
-                    hide_tb=hide_tb,
-
-                    repl_fixture=repl_fixture,
-                    boxed_maybe_exc=boxed_maybe_exc,
-                )
-            except bdb.BdbQuit:
-                __tracebackhide__: bool = False
-                raise err
-
-        if (
-            raise_on_exit is True
-            or (
-                raise_on_exit is not False
-                and (
-                    set(raise_on_exit)
-                    and
-                    type(err) in raise_on_exit
-                )
-            )
-            and
-            boxed_maybe_exc.raise_on_exit == raise_on_exit
-        ):
-            raise err
-
-
-@cm
-def maybe_open_crash_handler(
-    pdb: bool|None = None,
-    hide_tb: bool = True,
-
-    **kwargs,
-):
-    '''
-    Same as `open_crash_handler()` but with bool input flag
-    to allow conditional handling.
-
-    Normally this is used with CLI endpoints such that if the --pdb
-    flag is passed the pdb REPL is engaed on any crashes B)
-
-    '''
-    __tracebackhide__: bool = hide_tb
-
-    if pdb is None:
-        pdb: bool = _state.is_debug_mode()
-
-    rtctx = nullcontext(
-        enter_result=BoxedMaybeException()
-    )
-    if pdb:
-        rtctx = open_crash_handler(
-            hide_tb=hide_tb,
-            **kwargs,
-        )
-
-    with rtctx as boxed_maybe_exc:
-        yield boxed_maybe_exc

tractor/devx/debug/_repl.py

@@ -1,207 +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/>.
-
-'''
-`pdpp.Pdb` extentions/customization and other delegate usage.
-
-'''
-from functools import (
-    cached_property,
-)
-import os
-
-import pdbp
-from tractor._state import (
-    is_root_process,
-)
-
-from ._tty_lock import (
-    Lock,
-    DebugStatus,
-)
-
-
-class TractorConfig(pdbp.DefaultConfig):
-    '''
-    Custom `pdbp` config which tries to use the best tradeoff
-    between pretty and minimal.
-
-    '''
-    use_pygments: bool = True
-    sticky_by_default: bool = False
-    enable_hidden_frames: bool = True
-
-    # much thanks @mdmintz for the hot tip!
-    # fixes line spacing issue when resizing terminal B)
-    truncate_long_lines: bool = False
-
-    # ------ - ------
-    # our own custom config vars mostly
-    # for syncing with the actor tree's singleton
-    # TTY `Lock`.
-
-
-class PdbREPL(pdbp.Pdb):
-    '''
-    Add teardown hooks and local state describing any
-    ongoing TTY `Lock` request dialog.
-
-    '''
-    # override the pdbp config with our coolio one
-    # NOTE: this is only loaded when no `~/.pdbrc` exists
-    # so we should prolly pass it into the .__init__() instead?
-    # i dunno, see the `DefaultFactory` and `pdb.Pdb` impls.
-    DefaultConfig = TractorConfig
-
-    status = DebugStatus
-
-    # NOTE: see details in stdlib's `bdb.py`
-    # def user_exception(self, frame, exc_info):
-    #     '''
-    #     Called when we stop on an exception.
-    #     '''
-    #     log.warning(
-    #         'Exception during REPL sesh\n\n'
-    #         f'{frame}\n\n'
-    #         f'{exc_info}\n\n'
-    #     )
-
-    # NOTE: this actually hooks but i don't see anyway to detect
-    # if an error was caught.. this is why currently we just always
-    # call `DebugStatus.release` inside `_post_mortem()`.
-    # def preloop(self):
-    #     print('IN PRELOOP')
-    #     super().preloop()
-
-    # TODO: cleaner re-wrapping of all this?
-    # -[ ] figure out how to disallow recursive .set_trace() entry
-    #     since that'll cause deadlock for us.
-    # -[ ] maybe a `@cm` to call `super().<same_meth_name>()`?
-    # -[ ] look at hooking into the `pp` hook specially with our
-    #     own set of pretty-printers?
-    #    * `.pretty_struct.Struct.pformat()`
-    #    * `.pformat(MsgType.pld)`
-    #    * `.pformat(Error.tb_str)`?
-    #    * .. maybe more?
-    #
-    def set_continue(self):
-        try:
-            super().set_continue()
-        finally:
-            # NOTE: for subactors the stdio lock is released via the
-            # allocated RPC locker task, so for root we have to do it
-            # manually.
-            if (
-                is_root_process()
-                and
-                Lock._debug_lock.locked()
-                and
-                DebugStatus.is_main_trio_thread()
-            ):
-                # Lock.release(raise_on_thread=False)
-                Lock.release()
-
-            # XXX AFTER `Lock.release()` for root local repl usage
-            DebugStatus.release()
-
-    def set_quit(self):
-        try:
-            super().set_quit()
-        finally:
-            if (
-                is_root_process()
-                and
-                Lock._debug_lock.locked()
-                and
-                DebugStatus.is_main_trio_thread()
-            ):
-                # Lock.release(raise_on_thread=False)
-                Lock.release()
-
-            # XXX after `Lock.release()` for root local repl usage
-            DebugStatus.release()
-
-    # XXX NOTE: we only override this because apparently the stdlib pdb
-    # bois likes to touch the SIGINT handler as much as i like to touch
-    # my d$%&.
-    def _cmdloop(self):
-        self.cmdloop()
-
-    @cached_property
-    def shname(self) -> str | None:
-        '''
-        Attempt to return the login shell name with a special check for
-        the infamous `xonsh` since it seems to have some issues much
-        different from std shells when it comes to flushing the prompt?
-
-        '''
-        # SUPER HACKY and only really works if `xonsh` is not used
-        # before spawning further sub-shells..
-        shpath = os.getenv('SHELL', None)
-
-        if shpath:
-            if (
-                os.getenv('XONSH_LOGIN', default=False)
-                or 'xonsh' in shpath
-            ):
-                return 'xonsh'
-
-            return os.path.basename(shpath)
-
-        return None
-
-
-def mk_pdb() -> PdbREPL:
-    '''
-    Deliver a new `PdbREPL`: a multi-process safe `pdbp.Pdb`-variant
-    using the magic of `tractor`'s SC-safe IPC.
-
-    B)
-
-    Our `pdb.Pdb` subtype accomplishes multi-process safe debugging
-    by:
-
-    - mutexing access to the root process' std-streams (& thus parent
-      process TTY) via an IPC managed `Lock` singleton per
-      actor-process tree.
-
-    - temporarily overriding any subactor's SIGINT handler to shield
-      during live REPL sessions in sub-actors such that cancellation
-      is never (mistakenly) triggered by a ctrl-c and instead only by
-      explicit runtime API requests or after the
-      `pdb.Pdb.interaction()` call has returned.
-
-    FURTHER, the `pdbp.Pdb` instance is configured to be `trio`
-    "compatible" from a SIGINT handling perspective; we mask out
-    the default `pdb` handler and instead apply `trio`s default
-    which mostly addresses all issues described in:
-
-     - https://github.com/python-trio/trio/issues/1155
-
-    The instance returned from this factory should always be
-    preferred over the default `pdb[p].set_trace()` whenever using
-    a `pdb` REPL inside a `trio` based runtime.
-
-    '''
-    pdb = PdbREPL()
-
-    # XXX: These are the important flags mentioned in
-    # https://github.com/python-trio/trio/issues/1155
-    # which resolve the traceback spews to console.
-    pdb.allow_kbdint = True
-    pdb.nosigint = True
-    return pdb

tractor/devx/debug/_sigint.py

@@ -1,333 +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/>.
-
-'''
-A custom SIGINT handler which mainly shields actor (task)
-cancellation during REPL interaction.
-
-'''
-from __future__ import annotations
-from typing import (
-    TYPE_CHECKING,
-)
-import trio
-from tractor.log import get_logger
-from tractor._state import (
-    current_actor,
-    is_root_process,
-)
-from ._repl import (
-    PdbREPL,
-)
-from ._tty_lock import (
-    any_connected_locker_child,
-    DebugStatus,
-    Lock,
-)
-
-if TYPE_CHECKING:
-    from tractor.ipc import (
-        Channel,
-    )
-    from tractor._runtime import (
-        Actor,
-    )
-
-log = get_logger(__name__)
-
-_ctlc_ignore_header: str = (
-    'Ignoring SIGINT while debug REPL in use'
-)
-
-
-def sigint_shield(
-    signum: int,
-    frame: 'frame',  # type: ignore # noqa
-    *args,
-
-) -> None:
-    '''
-    Specialized, debugger-aware SIGINT handler.
-
-    In childred we always ignore/shield for SIGINT to avoid
-    deadlocks since cancellation should always be managed by the
-    supervising parent actor. The root actor-proces is always
-    cancelled on ctrl-c.
-
-    '''
-    __tracebackhide__: bool = True
-    actor: Actor = current_actor()
-
-    def do_cancel():
-        # If we haven't tried to cancel the runtime then do that instead
-        # of raising a KBI (which may non-gracefully destroy
-        # a ``trio.run()``).
-        if not actor._cancel_called:
-            actor.cancel_soon()
-
-        # If the runtime is already cancelled it likely means the user
-        # hit ctrl-c again because teardown didn't fully take place in
-        # which case we do the "hard" raising of a local KBI.
-        else:
-            raise KeyboardInterrupt
-
-    # only set in the actor actually running the REPL
-    repl: PdbREPL|None = DebugStatus.repl
-
-    # TODO: maybe we should flatten out all these cases using
-    # a match/case?
-    #
-    # root actor branch that reports whether or not a child
-    # has locked debugger.
-    if is_root_process():
-        # log.warning(
-        log.devx(
-            'Handling SIGINT in root actor\n'
-            f'{Lock.repr()}'
-            f'{DebugStatus.repr()}\n'
-        )
-        # try to see if the supposed (sub)actor in debug still
-        # has an active connection to *this* actor, and if not
-        # it's likely they aren't using the TTY lock / debugger
-        # and we should propagate SIGINT normally.
-        any_connected: bool = any_connected_locker_child()
-
-        problem = (
-            f'root {actor.uid} handling SIGINT\n'
-            f'any_connected: {any_connected}\n\n'
-
-            f'{Lock.repr()}\n'
-        )
-
-        if (
-            (ctx := Lock.ctx_in_debug)
-            and
-            (uid_in_debug := ctx.chan.uid) # "someone" is (ostensibly) using debug `Lock`
-        ):
-            name_in_debug: str = uid_in_debug[0]
-            assert not repl
-            # if not repl:  # but it's NOT us, the root actor.
-            # sanity: since no repl ref is set, we def shouldn't
-            # be the lock owner!
-            assert name_in_debug != 'root'
-
-            # IDEAL CASE: child has REPL as expected
-            if any_connected:  # there are subactors we can contact
-                # XXX: only if there is an existing connection to the
-                # (sub-)actor in debug do we ignore SIGINT in this
-                # parent! Otherwise we may hang waiting for an actor
-                # which has already terminated to unlock.
-                #
-                # NOTE: don't emit this with `.pdb()` level in
-                # root without a higher level.
-                log.runtime(
-                    _ctlc_ignore_header
-                    +
-                    f' by child '
-                    f'{uid_in_debug}\n'
-                )
-                problem = None
-
-            else:
-                problem += (
-                    '\n'
-                    f'A `pdb` REPL is SUPPOSEDLY in use by child {uid_in_debug}\n'
-                    f'BUT, no child actors are IPC contactable!?!?\n'
-                )
-
-        # IDEAL CASE: root has REPL as expected
-        else:
-            # root actor still has this SIGINT handler active without
-            # an actor using the `Lock` (a bug state) ??
-            # => so immediately cancel any stale lock cs and revert
-            # the handler!
-            if not DebugStatus.repl:
-                # TODO: WHEN should we revert back to ``trio``
-                # handler if this one is stale?
-                # -[ ] maybe after a counts work of ctl-c mashes?
-                # -[ ] use a state var like `stale_handler: bool`?
-                problem += (
-                    'No subactor is using a `pdb` REPL according `Lock.ctx_in_debug`?\n'
-                    'BUT, the root should be using it, WHY this handler ??\n\n'
-                    'So either..\n'
-                    '- some root-thread is using it but has no `.repl` set?, OR\n'
-                    '- something else weird is going on outside the runtime!?\n'
-                )
-            else:
-                # NOTE: since we emit this msg on ctl-c, we should
-                # also always re-print the prompt the tail block!
-                log.pdb(
-                    _ctlc_ignore_header
-                    +
-                    f' by root actor..\n'
-                    f'{DebugStatus.repl_task}\n'
-                    f' |_{repl}\n'
-                )
-                problem = None
-
-        # XXX if one is set it means we ARE NOT operating an ideal
-        # case where a child subactor or us (the root) has the
-        # lock without any other detected problems.
-        if problem:
-
-            # detect, report and maybe clear a stale lock request
-            # cancel scope.
-            lock_cs: trio.CancelScope = Lock.get_locking_task_cs()
-            maybe_stale_lock_cs: bool = (
-                lock_cs is not None
-                and not lock_cs.cancel_called
-            )
-            if maybe_stale_lock_cs:
-                problem += (
-                    '\n'
-                    'Stale `Lock.ctx_in_debug._scope: CancelScope` detected?\n'
-                    f'{Lock.ctx_in_debug}\n\n'
-
-                    '-> Calling ctx._scope.cancel()!\n'
-                )
-                lock_cs.cancel()
-
-            # TODO: wen do we actually want/need this, see above.
-            # DebugStatus.unshield_sigint()
-            log.warning(problem)
-
-    # child actor that has locked the debugger
-    elif not is_root_process():
-        log.debug(
-            f'Subactor {actor.uid} handling SIGINT\n\n'
-            f'{Lock.repr()}\n'
-        )
-
-        rent_chan: Channel = actor._parent_chan
-        if (
-            rent_chan is None
-            or
-            not rent_chan.connected()
-        ):
-            log.warning(
-                'This sub-actor thinks it is debugging '
-                'but it has no connection to its parent ??\n'
-                f'{actor.uid}\n'
-                'Allowing SIGINT propagation..'
-            )
-            DebugStatus.unshield_sigint()
-
-        repl_task: str|None = DebugStatus.repl_task
-        req_task: str|None = DebugStatus.req_task
-        if (
-            repl_task
-            and
-            repl
-        ):
-            log.pdb(
-                _ctlc_ignore_header
-                +
-                f' by local task\n\n'
-                f'{repl_task}\n'
-                f' |_{repl}\n'
-            )
-        elif req_task:
-            log.debug(
-                _ctlc_ignore_header
-                +
-                f' by local request-task and either,\n'
-                f'- someone else is already REPL-in and has the `Lock`, or\n'
-                f'- some other local task already is replin?\n\n'
-                f'{req_task}\n'
-            )
-
-        # TODO can we remove this now?
-        # -[ ] does this path ever get hit any more?
-        else:
-            msg: str = (
-                'SIGINT shield handler still active BUT, \n\n'
-            )
-            if repl_task is None:
-                msg += (
-                    '- No local task claims to be in debug?\n'
-                )
-
-            if repl is None:
-                msg += (
-                    '- No local REPL is currently active?\n'
-                )
-
-            if req_task is None:
-                msg += (
-                    '- No debug request task is active?\n'
-                )
-
-            log.warning(
-                msg
-                +
-                'Reverting handler to `trio` default!\n'
-            )
-            DebugStatus.unshield_sigint()
-
-            # XXX ensure that the reverted-to-handler actually is
-            # able to rx what should have been **this** KBI ;)
-            do_cancel()
-
-        # TODO: how to handle the case of an intermediary-child actor
-        # that **is not** marked in debug mode? See oustanding issue:
-        # https://github.com/goodboy/tractor/issues/320
-        # elif debug_mode():
-
-    # maybe redraw/print last REPL output to console since
-    # we want to alert the user that more input is expect since
-    # nothing has been done dur to ignoring sigint.
-    if (
-        DebugStatus.repl  # only when current actor has a REPL engaged
-    ):
-        flush_status: str = (
-            'Flushing stdout to ensure new prompt line!\n'
-        )
-
-        # XXX: yah, mega hack, but how else do we catch this madness XD
-        if (
-            repl.shname == 'xonsh'
-        ):
-            flush_status += (
-                '-> ALSO re-flushing due to `xonsh`..\n'
-            )
-            repl.stdout.write(repl.prompt)
-
-        # log.warning(
-        log.devx(
-            flush_status
-        )
-        repl.stdout.flush()
-
-        # TODO: better console UX to match the current "mode":
-        # -[ ] for example if in sticky mode where if there is output
-        #   detected as written to the tty we redraw this part underneath
-        #   and erase the past draw of this same bit above?
-        # repl.sticky = True
-        # repl._print_if_sticky()
-
-        # also see these links for an approach from `ptk`:
-        # https://github.com/goodboy/tractor/issues/130#issuecomment-663752040
-        # https://github.com/prompt-toolkit/python-prompt-toolkit/blob/c2c6af8a0308f9e5d7c0e28cb8a02963fe0ce07a/prompt_toolkit/patch_stdout.py
-    else:
-        log.devx(
-        # log.warning(
-            'Not flushing stdout since not needed?\n'
-            f'|_{repl}\n'
-        )
-
-    # XXX only for tracing this handler
-    log.devx('exiting SIGINT')

tractor/devx/debug/_sync.py

@@ -1,220 +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/>.
-
-'''
-Debugger synchronization APIs to ensure orderly access and
-non-TTY-clobbering graceful teardown.
-
-
-'''
-from __future__ import annotations
-from contextlib import (
-    asynccontextmanager as acm,
-)
-from functools import (
-    partial,
-)
-from typing import (
-    AsyncGenerator,
-    Callable,
-)
-
-from tractor.log import get_logger
-import trio
-from trio.lowlevel import (
-    current_task,
-    Task,
-)
-from tractor._context import Context
-from tractor._state import (
-    current_actor,
-    debug_mode,
-    is_root_process,
-)
-from ._repl import (
-    TractorConfig as TractorConfig,
-)
-from ._tty_lock import (
-    Lock,
-    request_root_stdio_lock,
-    any_connected_locker_child,
-)
-from ._sigint import (
-    sigint_shield as sigint_shield,
-    _ctlc_ignore_header as _ctlc_ignore_header
-)
-
-log = get_logger(__package__)
-
-
-async def maybe_wait_for_debugger(
-    poll_steps: int = 2,
-    poll_delay: float = 0.1,
-    child_in_debug: bool = False,
-
-    header_msg: str = '',
-    _ll: str = 'devx',
-
-) -> bool:  # was locked and we polled?
-
-    if (
-        not debug_mode()
-        and
-        not child_in_debug
-    ):
-        return False
-
-    logmeth: Callable = getattr(log, _ll)
-
-    msg: str = header_msg
-    if (
-        is_root_process()
-    ):
-        # If we error in the root but the debugger is
-        # engaged we don't want to prematurely kill (and
-        # thus clobber access to) the local tty since it
-        # will make the pdb repl unusable.
-        # Instead try to wait for pdb to be released before
-        # tearing down.
-        ctx_in_debug: Context|None = Lock.ctx_in_debug
-        in_debug: tuple[str, str]|None = (
-            ctx_in_debug.chan.uid
-            if ctx_in_debug
-            else None
-        )
-        if in_debug == current_actor().uid:
-            log.debug(
-                msg
-                +
-                'Root already owns the TTY LOCK'
-            )
-            return True
-
-        elif in_debug:
-            msg += (
-                f'Debug `Lock` in use by subactor\n|\n|_{in_debug}\n'
-            )
-            # TODO: could this make things more deterministic?
-            # wait to see if a sub-actor task will be
-            # scheduled and grab the tty lock on the next
-            # tick?
-            # XXX => but it doesn't seem to work..
-            # await trio.testing.wait_all_tasks_blocked(cushion=0)
-        else:
-            logmeth(
-                msg
-                +
-                'Root immediately acquired debug TTY LOCK'
-            )
-            return False
-
-        for istep in range(poll_steps):
-            if (
-                Lock.req_handler_finished is not None
-                and not Lock.req_handler_finished.is_set()
-                and in_debug is not None
-            ):
-                # caller_frame_info: str = pformat_caller_frame()
-                logmeth(
-                    msg
-                    +
-                    '\n^^ Root is waiting on tty lock release.. ^^\n'
-                    # f'{caller_frame_info}\n'
-                )
-
-                if not any_connected_locker_child():
-                    Lock.get_locking_task_cs().cancel()
-
-                with trio.CancelScope(shield=True):
-                    await Lock.req_handler_finished.wait()
-
-                log.devx(
-                    f'Subactor released debug lock\n'
-                    f'|_{in_debug}\n'
-                )
-                break
-
-            # is no subactor locking debugger currently?
-            if (
-                in_debug is None
-                and (
-                    Lock.req_handler_finished is None
-                    or Lock.req_handler_finished.is_set()
-                )
-            ):
-                logmeth(
-                    msg
-                    +
-                    'Root acquired tty lock!'
-                )
-                break
-
-            else:
-                logmeth(
-                    'Root polling for debug:\n'
-                    f'poll step: {istep}\n'
-                    f'poll delya: {poll_delay}\n\n'
-                    f'{Lock.repr()}\n'
-                )
-                with trio.CancelScope(shield=True):
-                    await trio.sleep(poll_delay)
-                    continue
-
-        return True
-
-    # else:
-    #     # TODO: non-root call for #320?
-    #     this_uid: tuple[str, str] = current_actor().uid
-    #     async with acquire_debug_lock(
-    #         subactor_uid=this_uid,
-    #     ):
-    #         pass
-    return False
-
-
-@acm
-async def acquire_debug_lock(
-    subactor_uid: tuple[str, str],
-) -> AsyncGenerator[
-    trio.CancelScope|None,
-    tuple,
-]:
-    '''
-    Request to acquire the TTY `Lock` in the root actor, release on
-    exit.
-
-    This helper is for actor's who don't actually need to acquired
-    the debugger but want to wait until the lock is free in the
-    process-tree root such that they don't clobber an ongoing pdb
-    REPL session in some peer or child!
-
-    '''
-    if not debug_mode():
-        yield None
-        return
-
-    task: Task = current_task()
-    async with trio.open_nursery() as n:
-        ctx: Context = await n.start(
-            partial(
-                request_root_stdio_lock,
-                actor_uid=subactor_uid,
-                task_uid=(task.name, id(task)),
-            )
-        )
-        yield ctx
-        ctx.cancel()

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
@@ -249,279 +247,3 @@ def pformat_cs(
         +
         fields
     )
-
-
-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.
-    #
-    # ?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.
-    #
-    # try not to take any of this seriously yet XD
-    #
-    # > is a "play operator" indicating (CPU bound)
-    #   exec/work/ops required at the "lowest level computing"
-    #
-    # execution primititves (tasks, threads, actors..) denote their
-    # lifetime with '(' and ')' since parentheses normally are used
-    # in many langs to denote function calls.
-    #
-    # starting = (
-    # >(  opening/starting; beginning of the thread-of-exec (toe?)
-    # (>  opened/started,  (finished spawning toe)
-    # |_<Task: blah blah..>  repr of toe, in py these look like <objs>
-    #
-    # >) closing/exiting/stopping,
-    # )> closed/exited/stopped,
-    # |_<Task: blah blah..>
-    #   [OR <), )< ?? ]
-    #
-    # ending = )
-    # >c) cancelling to close/exit
-    # c)> cancelled (caused close), OR?
-    #  |_<Actor: ..>
-    #   OR maybe "<c)" which better indicates the cancel being
-    #   "delivered/returned" / returned" to LHS?
-    #
-    # >x)  erroring to eventuall exit
-    # x)>  errored and terminated
-    #  |_<Actor: ...>
-    #
-    # scopes: supers/nurseries, IPC-ctxs, sessions, perms, etc.
-    # >{  opening
-    # {>  opened
-    # }>  closed
-    # >}  closing
-    #
-    # storage: like queues, shm-buffers, files, etc..
-    # >[  opening
-    # [>  opened
-    #  |_<FileObj: ..>
-    #
-    # >]  closing
-    # ]>  closed
-
-    # IPC ops: channels, transports, msging
-    # =>  req msg
-    # <=  resp msg
-    # <=> 2-way streaming (of msgs)
-    # <-  recv 1 msg
-    # ->  send 1 msg
-    #
-    # TODO: still not sure on R/L-HS approach..?
-    # =>(  send-req to exec start (task, actor, thread..)
-    # (<=  recv-req to ^
-    #
-    # (<=  recv-req ^
-    # <=(  recv-resp opened remote exec primitive
-    # <=)  recv-resp closed
-    #
-    # )<=c req to stop due to cancel
-    # c=>) req to stop due to cancel
-    #
-    # =>{  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)
-
-    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,
-) -> 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..
-
-    '''
-    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
-        )
-
-
-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/ipc/_chan.py

@@ -171,22 +171,10 @@ class Channel:
         )
         assert transport.raddr == addr
         chan = Channel(transport=transport)
-
-        # ?TODO, compact this into adapter level-methods?
-        # -[ ] would avoid extra repr-calcs if level not active?
-        #   |_ how would the `calc_if_level` look though? func?
-        if log.at_least_level('runtime'):
-            from tractor.devx import (
-                pformat as _pformat,
-            )
-            chan_repr: str = _pformat.nest_from_op(
-                input_op='[>',
-                text=chan.pformat(),
-                nest_indent=1,
-            )
         log.runtime(
             f'Connected channel IPC transport\n'
-                f'{chan_repr}'
+            f'[>\n'
+            f' |_{chan}\n'
         )
         return chan
 
@@ -208,12 +196,9 @@ class Channel:
             self._transport.codec = orig
 
     # TODO: do a .src/.dst: str for maddrs?
-    def pformat(
-        self,
-        privates: bool = False,
-    ) -> str:
+    def pformat(self) -> str:
         if not self._transport:
-            return '<Channel( with inactive transport? )>'
+            return '<Channel with inactive transport?>'
 
         tpt: MsgTransport = self._transport
         tpt_name: str = type(tpt).__name__
@@ -221,35 +206,26 @@ class Channel:
             'connected' if self.connected()
             else 'closed'
         )
-        repr_str: str = (
+        return (
             f'<Channel(\n'
             f' |_status: {tpt_status!r}\n'
-        ) + (
             f'   _closed={self._closed}\n'
             f'   _cancel_called={self._cancel_called}\n'
-            if privates else ''
-        ) + (  # peer-actor (processs) section
-            f' |_peer: {self.aid.reprol()!r}\n'
-            if self.aid else ' |_peer: <unknown>\n'
-        ) + (
+            f'\n'
+            f' |_peer: {self.aid}\n'
+            f'\n'
             f' |_msgstream: {tpt_name}\n'
-            f'   maddr: {tpt.maddr!r}\n'
-            f'   proto: {tpt.laddr.proto_key!r}\n'
-            f'   layer: {tpt.layer_key!r}\n'
-            f'   codec: {tpt.codec_key!r}\n'
-            f'   .laddr={tpt.laddr}\n'
-            f'   .raddr={tpt.raddr}\n'
-        ) + (
-            f'   ._transport.stream={tpt.stream}\n'
-            f'   ._transport.drained={tpt.drained}\n'
-            if privates else ''
-        ) + (
+            f'   proto={tpt.laddr.proto_key!r}\n'
+            f'   layer={tpt.layer_key!r}\n'
+            f'   laddr={tpt.laddr}\n'
+            f'   raddr={tpt.raddr}\n'
+            f'   codec={tpt.codec_key!r}\n'
+            f'   stream={tpt.stream}\n'
+            f'   maddr={tpt.maddr!r}\n'
+            f'   drained={tpt.drained}\n'
             f'   _send_lock={tpt._send_lock.statistics()}\n'
-            if privates else ''
-        ) + (
-            ')>\n'
+            f')>\n'
         )
-        return repr_str
 
     # NOTE: making this return a value that can be passed to
     # `eval()` is entirely **optional** FYI!
@@ -271,10 +247,6 @@ class Channel:
     def raddr(self) -> Address|None:
         return self._transport.raddr if self._transport else None
 
-    @property
-    def maddr(self) -> str:
-        return self._transport.maddr if self._transport else '<no-tpt>'
-
     # TODO: something like,
     # `pdbp.hideframe_on(errors=[MsgTypeError])`
     # instead of the `try/except` hack we have rn..
@@ -462,8 +434,8 @@ class Channel:
         await self.send(aid)
         peer_aid: Aid = await self.recv()
         log.runtime(
-            f'Received hanshake with peer\n'
-            f'<= {peer_aid.reprol(sin_uuid=False)}\n'
+            f'Received hanshake with peer actor,\n'
+            f'{peer_aid}\n'
         )
         # NOTE, we always are referencing the remote peer!
         self.aid = peer_aid

tractor/ipc/_mp_bs.py

@@ -17,16 +17,9 @@
 Utils to tame mp non-SC madeness
 
 '''
-
-# !TODO! in 3.13 this can be disabled (the-same/similarly) using
-# a flag,
-# - [ ] soo if it works like this, drop this module entirely for
-#   3.13+ B)
-#  |_https://docs.python.org/3/library/multiprocessing.shared_memory.html
-#
 def disable_mantracker():
     '''
-    Disable all `multiprocessing` "resource tracking" machinery since
+    Disable all ``multiprocessing``` "resource tracking" machinery since
     it's an absolute multi-threaded mess of non-SC madness.
 
     '''

tractor/ipc/_server.py

@@ -26,7 +26,7 @@ from contextlib import (
 from functools import partial
 from itertools import chain
 import inspect
-import textwrap
+from pprint import pformat
 from types import (
     ModuleType,
 )
@@ -43,10 +43,7 @@ from trio import (
     SocketListener,
 )
 
-from ..devx.pformat import (
-    ppfmt,
-    nest_from_op,
-)
+# from ..devx import _debug
 from .._exceptions import (
     TransportClosed,
 )
@@ -144,8 +141,9 @@ async def maybe_wait_on_canced_subs(
 
     ):
         log.cancel(
-            'Waiting on cancel request to peer\n'
-            f'c)=> {chan.aid.reprol()}@[{chan.maddr}]\n'
+            'Waiting on cancel request to peer..\n'
+            f'c)=>\n'
+            f'  |_{chan.aid}\n'
         )
 
         # XXX: this is a soft wait on the channel (and its
@@ -181,7 +179,7 @@ async def maybe_wait_on_canced_subs(
                 log.warning(
                     'Draining msg from disconnected peer\n'
                     f'{chan_info}'
-                    f'{ppfmt(msg)}\n'
+                    f'{pformat(msg)}\n'
                 )
                 # cid: str|None = msg.get('cid')
                 cid: str|None = msg.cid
@@ -250,7 +248,7 @@ async def maybe_wait_on_canced_subs(
                 if children := local_nursery._children:
                     # indent from above local-nurse repr
                     report += (
-                        f'   |_{ppfmt(children)}\n'
+                        f'   |_{pformat(children)}\n'
                     )
 
                 log.warning(report)
@@ -281,9 +279,8 @@ async def maybe_wait_on_canced_subs(
                     log.runtime(
                         f'Peer IPC broke but subproc is alive?\n\n'
 
-                        f'<=x {chan.aid.reprol()}@[{chan.maddr}]\n'
-                        f'\n'
-                        f'{proc}\n'
+                        f'<=x {chan.aid}@{chan.raddr}\n'
+                        f'   |_{proc}\n'
                     )
 
     return local_nursery
@@ -321,16 +318,15 @@ async def handle_stream_from_peer(
     server._no_more_peers = trio.Event()  # unset by making new
 
     # TODO, debug_mode tooling for when hackin this lower layer?
-    # with debug.maybe_open_crash_handler(
+    # with _debug.maybe_open_crash_handler(
     #     pdb=True,
     # ) as boxerr:
 
     chan = Channel.from_stream(stream)
     con_status: str = (
-        f'New inbound IPC transport connection\n'
-        f'<=( {stream!r}\n'
+        'New inbound IPC connection <=\n'
+        f'|_{chan}\n'
     )
-    con_status_steps: str = ''
 
     # initial handshake with peer phase
     try:
@@ -376,7 +372,7 @@ async def handle_stream_from_peer(
     if _pre_chan := server._peers.get(uid):
         familiar: str = 'pre-existing-peer'
     uid_short: str = f'{uid[0]}[{uid[1][-6:]}]'
-    con_status_steps += (
+    con_status += (
         f' -> Handshake with {familiar} `{uid_short}` complete\n'
     )
 
@@ -401,7 +397,7 @@ async def handle_stream_from_peer(
         None,
     )
     if event:
-        con_status_steps += (
+        con_status += (
             ' -> Waking subactor spawn waiters: '
             f'{event.statistics().tasks_waiting}\n'
             f' -> Registered IPC chan for child actor {uid}@{chan.raddr}\n'
@@ -412,7 +408,7 @@ async def handle_stream_from_peer(
         event.set()
 
     else:
-        con_status_steps += (
+        con_status += (
             f' -> Registered IPC chan for peer actor {uid}@{chan.raddr}\n'
         )  # type: ignore
 
@@ -426,15 +422,8 @@ async def handle_stream_from_peer(
     # TODO: can we just use list-ref directly?
     chans.append(chan)
 
-    con_status_steps += ' -> Entering RPC msg loop..\n'
-    log.runtime(
-        con_status
-        +
-        textwrap.indent(
-            con_status_steps,
-            prefix=' '*3,  # align to first-ln
-        )
-    )
+    con_status += ' -> Entering RPC msg loop..\n'
+    log.runtime(con_status)
 
     # Begin channel management - respond to remote requests and
     # process received reponses.
@@ -467,67 +456,41 @@ async def handle_stream_from_peer(
             disconnected=disconnected,
         )
 
-        # `Channel` teardown and closure sequence
+        # ``Channel`` teardown and closure sequence
         # drop ref to channel so it can be gc-ed and disconnected
-        #
-        # -[x]TODO mk this be like
-        # <=x Channel(
-        #     |_field: blah
-        # )>
-        op_repr: str = '<=x '
-        chan_repr: str = nest_from_op(
-            input_op=op_repr,
-            op_suffix='',
-            nest_prefix='',
-            text=chan.pformat(),
-            nest_indent=len(op_repr)-1,
-            rm_from_first_ln='<',
-        )
-
         con_teardown_status: str = (
-            f'IPC channel disconnect\n'
-            f'\n'
-            f'{chan_repr}\n'
-            f'\n'
+            f'IPC channel disconnected:\n'
+            f'<=x uid: {chan.aid}\n'
+            f'   |_{pformat(chan)}\n\n'
         )
-
         chans.remove(chan)
 
         # TODO: do we need to be this pedantic?
         if not chans:
             con_teardown_status += (
-                f'-> No more channels with {chan.aid.reprol()!r}\n'
+                f'-> No more channels with {chan.aid}'
             )
             server._peers.pop(uid, None)
 
-        if peers := list(server._peers.values()):
-            peer_cnt: int = len(peers)
-            if (
-                (first := peers[0][0]) is not chan
-                and
-                not disconnected
-                and
-                peer_cnt > 1
-            ):
-                con_teardown_status += (
-                    f'-> Remaining IPC {peer_cnt-1!r} peers:\n'
+        peers_str: str = ''
+        for uid, chans in server._peers.items():
+            peers_str += (
+                f'uid: {uid}\n'
             )
-                for chans in server._peers.values():
-                    first: Channel = chans[0]
-                    if not (
-                        first is chan
-                        and
-                        disconnected
-                    ):
+            for i, chan in enumerate(chans):
+                peers_str += (
+                    f' |_[{i}] {pformat(chan)}\n'
+                )
+
         con_teardown_status += (
-                            f'  |_{first.aid.reprol()!r} -> {len(chans)!r} chans\n'
+            f'-> Remaining IPC {len(server._peers)} peers: {peers_str}\n'
         )
 
         # No more channels to other actors (at all) registered
         # as connected.
         if not server._peers:
             con_teardown_status += (
-                '-> Signalling no more peer connections!\n'
+                'Signalling no more peer channel connections'
             )
             server._no_more_peers.set()
 
@@ -541,8 +504,8 @@ async def handle_stream_from_peer(
                 and
                 _state.is_debug_mode()
             ):
-                from ..devx import debug
-                pdb_lock = debug.Lock
+                from ..devx import _debug
+                pdb_lock = _debug.Lock
                 pdb_lock._blocked.add(uid)
 
                 # TODO: NEEEDS TO BE TESTED!
@@ -577,7 +540,7 @@ async def handle_stream_from_peer(
                                 f'last disconnected child uid: {uid}\n'
                                 f'locking child uid: {pdb_user_uid}\n'
                             )
-                            await debug.maybe_wait_for_debugger(
+                            await _debug.maybe_wait_for_debugger(
                                 child_in_debug=True
                             )
 
@@ -616,10 +579,10 @@ async def handle_stream_from_peer(
 
 class Endpoint(Struct):
     '''
-    An instance of an IPC "bound" address where the lifetime of an
-    "ability to accept connections" and handle the subsequent
-    sequence-of-packets (maybe oriented as sessions) is determined by
-    the underlying nursery scope(s).
+    An instance of an IPC "bound" address where the lifetime of the
+    "ability to accept connections" (from clients) and then handle
+    those inbound sessions or sequences-of-packets is determined by
+    a (maybe pair of) nurser(y/ies).
 
     '''
     addr: Address
@@ -637,24 +600,6 @@ class Endpoint(Struct):
         MsgTransport,  # handle to encoded-msg transport stream
     ] = {}
 
-    def pformat(
-        self,
-        indent: int = 0,
-        privates: bool = False,
-    ) -> str:
-        type_repr: str = type(self).__name__
-        fmtstr: str = (
-            # !TODO, always be ns aware!
-            # f'|_netns: {netns}\n'
-            f' |.addr: {self.addr!r}\n'
-            f' |_peers: {len(self.peer_tpts)}\n'
-        )
-        return (
-            f'<{type_repr}(\n'
-            f'{fmtstr}'
-            f')>'
-        )
-
     async def start_listener(self) -> SocketListener:
         tpt_mod: ModuleType = inspect.getmodule(self.addr)
         lstnr: SocketListener = await tpt_mod.start_listener(
@@ -694,13 +639,11 @@ class Endpoint(Struct):
 class Server(Struct):
     _parent_tn: Nursery
     _stream_handler_tn: Nursery
-
     # level-triggered sig for whether "no peers are currently
     # connected"; field is **always** set to an instance but
     # initialized with `.is_set() == True`.
     _no_more_peers: trio.Event
 
-    # active eps as allocated by `.listen_on()`
     _endpoints: list[Endpoint] = []
 
     # connection tracking & mgmt
@@ -708,19 +651,12 @@ class Server(Struct):
         str,  # uaid
         list[Channel],  # IPC conns from peer
     ] = defaultdict(list)
-
-    # events-table with entries registered unset while the local
-    # actor is waiting on a new actor to inbound connect, often
-    # a parent waiting on its child just after spawn.
     _peer_connected: dict[
         tuple[str, str],
         trio.Event,
     ] = {}
 
     # syncs for setup/teardown sequences
-    # - null when not yet booted,
-    # - unset when active,
-    # - set when fully shutdown with 0 eps active.
     _shutdown: trio.Event|None = None
 
     # TODO, maybe just make `._endpoints: list[Endpoint]` and
@@ -728,6 +664,7 @@ class Server(Struct):
     # @property
     # def addrs2eps(self) -> dict[Address, Endpoint]:
     #     ...
+
     @property
     def proto_keys(self) -> list[str]:
         return [
@@ -753,7 +690,7 @@ class Server(Struct):
             # TODO: obvi a different server type when we eventually
             # support some others XD
             log.runtime(
-                f'Cancelling server(s) for tpt-protos\n'
+                f'Cancelling server(s) for\n'
                 f'{self.proto_keys!r}\n'
             )
             self._parent_tn.cancel_scope.cancel()
@@ -780,14 +717,6 @@ class Server(Struct):
                 f'protos: {tpt_protos!r}\n'
             )
 
-    def len_peers(
-        self,
-    ) -> int:
-        return len([
-            chan.connected()
-            for chan in chain(*self._peers.values())
-        ])
-
     def has_peers(
         self,
         check_chans: bool = False,
@@ -801,11 +730,13 @@ class Server(Struct):
             has_peers
             and
             check_chans
-            and
-            (peer_cnt := self.len_peers())
         ):
             has_peers: bool = (
-                peer_cnt > 0
+                any(chan.connected()
+                    for chan in chain(
+                        *self._peers.values()
+                    )
+                )
                 and
                 has_peers
             )
@@ -872,66 +803,30 @@ class Server(Struct):
 
         return ev.is_set()
 
-    @property
-    def repr_state(self) -> str:
-        '''
-        A `str`-status describing the current state of this
-        IPC server in terms of the current operating "phase".
-
-        '''
-        status = 'server is active'
-        if self.has_peers():
-            peer_cnt: int = self.len_peers()
-            status: str = (
-                f'{peer_cnt!r} peer chans'
-            )
-        else:
-            status: str = 'No peer chans'
-
-        if self.is_shutdown():
-            status: str = 'server-shutdown'
-
-        return status
-
-    def pformat(
-        self,
-        privates: bool = False,
-    ) -> str:
+    def pformat(self) -> str:
         eps: list[Endpoint] = self._endpoints
 
-        # state_repr: str = (
-        #     f'{len(eps)!r} endpoints active'
-        # )
-        fmtstr = (
-            f' |_state: {self.repr_state!r}\n'
+        state_repr: str = (
+            f'{len(eps)!r} IPC-endpoints active'
+        )
+        fmtstr = (
+            f' |_state: {state_repr}\n'
+            f'   no_more_peers: {self.has_peers()}\n'
         )
-        if privates:
-            fmtstr += f'   no_more_peers: {self.has_peers()}\n'
-
         if self._shutdown is not None:
             shutdown_stats: EventStatistics = self._shutdown.statistics()
             fmtstr += (
                 f'   task_waiting_on_shutdown: {shutdown_stats}\n'
             )
 
-        if eps := self._endpoints:
-            addrs: list[tuple] = [
-                ep.addr for ep in eps
-            ]
-            repr_eps: str = ppfmt(addrs)
-
         fmtstr += (
-                f' |_endpoints: {repr_eps}\n'
-                # ^TODO? how to indent closing ']'..
-            )
-
-        if peers := self._peers:
-            fmtstr += (
-                f' |_peers: {len(peers)} connected\n'
+            # TODO, use the `ppfmt()` helper from `modden`!
+            f' |_endpoints: {pformat(self._endpoints)}\n'
+            f' |_peers: {len(self._peers)} connected\n'
         )
 
         return (
-            f'<Server(\n'
+            f'<IPCServer(\n'
             f'{fmtstr}'
             f')>\n'
         )
@@ -990,8 +885,8 @@ class Server(Struct):
             )
 
         log.runtime(
-            f'Binding endpoints\n'
-            f'{ppfmt(accept_addrs)}\n'
+            f'Binding to endpoints for,\n'
+            f'{accept_addrs}\n'
         )
         eps: list[Endpoint] = await self._parent_tn.start(
             partial(
@@ -1001,19 +896,13 @@ class Server(Struct):
                 listen_addrs=accept_addrs,
             )
         )
-        self._endpoints.extend(eps)
-
-        serv_repr: str = nest_from_op(
-            input_op='(>',
-            text=self.pformat(),
-            nest_indent=1,
-        )
         log.runtime(
-            f'Started IPC server\n'
-            f'{serv_repr}'
+            f'Started IPC endpoints\n'
+            f'{eps}\n'
         )
 
-        # XXX, a little sanity on new ep allocations
+        self._endpoints.extend(eps)
+        # XXX, just a little bit of sanity
         group_tn: Nursery|None = None
         ep: Endpoint
         for ep in eps:
@@ -1067,13 +956,9 @@ async def _serve_ipc_eps(
                     stream_handler_tn=stream_handler_tn,
                 )
                 try:
-                    ep_sclang: str = nest_from_op(
-                        input_op='>[',
-                        text=f'{ep.pformat()}',
-                    )
                     log.runtime(
                         f'Starting new endpoint listener\n'
-                        f'{ep_sclang}\n'
+                        f'{ep}\n'
                     )
                     listener: trio.abc.Listener = await ep.start_listener()
                     assert listener is ep._listener
@@ -1111,6 +996,17 @@ async def _serve_ipc_eps(
                     handler_nursery=stream_handler_tn
                 )
             )
+            # TODO, wow make this message better! XD
+            log.runtime(
+                'Started server(s)\n'
+                +
+                '\n'.join([f'|_{addr}' for addr in listen_addrs])
+            )
+
+            log.runtime(
+                f'Started IPC endpoints\n'
+                f'{eps}\n'
+            )
             task_status.started(
                 eps,
             )
@@ -1153,7 +1049,8 @@ async def open_ipc_server(
         try:
             yield ipc_server
             log.runtime(
-                'Server-tn running until terminated\n'
+                f'Waiting on server to shutdown or be cancelled..\n'
+                f'{ipc_server}'
             )
             # TODO? when if ever would we want/need this?
             # with trio.CancelScope(shield=True):

tractor/ipc/_tcp.py

@@ -18,6 +18,7 @@ TCP implementation of tractor.ipc._transport.MsgTransport protocol
 
 '''
 from __future__ import annotations
+import ipaddress
 from typing import (
     ClassVar,
 )
@@ -50,13 +51,45 @@ class TCPAddress(
     _host: str
     _port: int
 
+    def __post_init__(self):
+        try:
+            ipaddress.ip_address(self._host)
+        except ValueError as valerr:
+            raise ValueError(
+                'Invalid {type(self).__name__}._host = {self._host!r}\n'
+            ) from valerr
+
     proto_key: ClassVar[str] = 'tcp'
     unwrapped_type: ClassVar[type] = tuple[str, int]
     def_bindspace: ClassVar[str] = '127.0.0.1'
 
+    # ?TODO, actually validate ipv4/6 with stdlib's `ipaddress`
     @property
     def is_valid(self) -> bool:
-        return self._port != 0
+        '''
+        Predicate to ensure a valid socket-address pair.
+
+        '''
+        return (
+            self._port != 0
+            and
+            (ipaddr := ipaddress.ip_address(self._host))
+            and not (
+                ipaddr.is_reserved
+                or
+                ipaddr.is_unspecified
+                or
+                ipaddr.is_link_local
+                or
+                ipaddr.is_link_local
+                or
+                ipaddr.is_multicast
+                or
+                ipaddr.is_global
+            )
+        )
+        # ^XXX^ see various properties of invalid addrs here,
+        # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address
 
     @property
     def bindspace(self) -> str:
@@ -127,9 +160,10 @@ async def start_listener(
     Start a TCP socket listener on the given `TCPAddress`.
 
     '''
-    log.runtime(
-        f'Trying socket bind\n'
-        f'>[ {addr}\n'
+    log.info(
+        f'Attempting to bind TCP socket\n'
+        f'>[\n'
+        f'|_{addr}\n'
     )
     # ?TODO, maybe we should just change the lower-level call this is
     # using internall per-listener?
@@ -144,10 +178,11 @@ async def start_listener(
     assert len(listeners) == 1
     listener = listeners[0]
     host, port = listener.socket.getsockname()[:2]
-    bound_addr: TCPAddress = type(addr).from_addr((host, port))
+
     log.info(
         f'Listening on TCP socket\n'
-        f'[> {bound_addr}\n'
+        f'[>\n'
+        f' |_{addr}\n'
     )
     return listener
 

tractor/log.py

@@ -26,9 +26,8 @@ from logging import (
     Logger,
     StreamHandler,
 )
-import threading
-
 import colorlog  # type: ignore
+
 import trio
 
 from ._state import current_actor
@@ -45,7 +44,7 @@ LOG_FORMAT = (
     "{log_color}{asctime}{reset}"
     " {bold_white}{thin_white}({reset}"
     "{thin_white}{actor_name}[{actor_uid}], "
-    "{process}, {thread_uid}, {task_uid}){reset}{bold_white}{thin_white})"
+    "{process}, {task}){reset}{bold_white}{thin_white})"
     " {reset}{log_color}[{reset}{bold_log_color}{levelname}{reset}{log_color}]"
     " {log_color}{name}"
     " {thin_white}{filename}{log_color}:{reset}{thin_white}{lineno}{log_color}"
@@ -82,35 +81,10 @@ BOLD_PALETTE = {
 }
 
 
-def at_least_level(
-    log: Logger|LoggerAdapter,
-    level: int|str,
-) -> bool:
-    '''
-    Predicate to test if a given level is active.
-
-    '''
-    if isinstance(level, str):
-        level: int = CUSTOM_LEVELS[level.upper()]
-
-    if log.getEffectiveLevel() <= level:
-        return True
-    return False
-
-
 # TODO: this isn't showing the correct '{filename}'
 # as it did before..
 class StackLevelAdapter(LoggerAdapter):
 
-    def at_least_level(
-        self,
-        level: str,
-    ) -> bool:
-        return at_least_level(
-            log=self,
-            level=level,
-        )
-
     def transport(
         self,
         msg: str,
@@ -249,19 +223,11 @@ def pformat_task_uid(
     return f'{task.name}[{tid_part}]'
 
 
-def pformat_thread_uid() -> str:
-    curr_thr: threading.Thread = threading.current_thread()
-    return (
-        f'{curr_thr.name}@{curr_thr.ident}'
-    )
-
-
 _conc_name_getters = {
-    'task_uid': pformat_task_uid,
+    'task': pformat_task_uid,
     'actor': lambda: current_actor(),
     'actor_name': lambda: current_actor().name,
     'actor_uid': lambda: current_actor().uid[1][:6],
-    'thread_uid': pformat_thread_uid,
 }
 
 
@@ -271,11 +237,10 @@ class ActorContextInfo(Mapping):
 
     '''
     _context_keys = (
-        'task_uid',
+        'task',
         'actor',
         'actor_name',
         'actor_uid',
-        'thread_uid',
     )
 
     def __len__(self):
@@ -305,9 +270,7 @@ def get_logger(
     subsys_spec: str|None = None,
 
 ) -> StackLevelAdapter:
-    '''
-    Return the `tractor`-library root logger or a sub-logger for
-    `name` if provided.
+    '''Return the package log or a sub-logger for ``name`` if provided.
 
     '''
     log: Logger
@@ -319,7 +282,7 @@ def get_logger(
         name != _proj_name
     ):
 
-        # NOTE: for handling for modules that use `get_logger(__name__)`
+        # NOTE: for handling for modules that use ``get_logger(__name__)``
         # we make the following stylistic choice:
         # - always avoid duplicate project-package token
         #   in msg output: i.e. tractor.tractor.ipc._chan.py in header
@@ -368,7 +331,7 @@ def get_logger(
 
 def get_console_log(
     level: str|None = None,
-    logger: Logger|StackLevelAdapter|None = None,
+    logger: Logger|None = None,
     **kwargs,
 
 ) -> LoggerAdapter:
@@ -381,23 +344,12 @@ def get_console_log(
     Yeah yeah, i know we can use `logging.config.dictConfig()`. You do it.
 
     '''
-    # get/create a stack-aware-adapter
-    if (
-        logger
-        and
-        isinstance(logger, StackLevelAdapter)
-    ):
-        # XXX, for ex. when passed in by a caller wrapping some
-        # other lib's logger instance with our level-adapter.
-        log = logger
-
-    else:
-        log: StackLevelAdapter = get_logger(
+    log = get_logger(
         logger=logger,
         **kwargs
-        )
+    )  # set a root logger
+    logger: Logger = log.logger
 
-    logger: Logger|StackLevelAdapter = log.logger
     if not level:
         return log
 
@@ -415,7 +367,10 @@ def get_console_log(
             None,
         )
     ):
-        fmt: str = LOG_FORMAT  # always apply our format?
+        fmt = LOG_FORMAT
+        # if logger:
+        #     fmt = None
+
         handler = StreamHandler()
         formatter = colorlog.ColoredFormatter(
             fmt=fmt,
@@ -436,3 +391,19 @@ def get_loglevel() -> str:
 
 # global module logger for tractor itself
 log: StackLevelAdapter = get_logger('tractor')
+
+
+def at_least_level(
+    log: Logger|LoggerAdapter,
+    level: int|str,
+) -> bool:
+    '''
+    Predicate to test if a given level is active.
+
+    '''
+    if isinstance(level, str):
+        level: int = CUSTOM_LEVELS[level.upper()]
+
+    if log.getEffectiveLevel() <= level:
+        return True
+    return False

tractor/msg/_ops.py

@@ -608,7 +608,7 @@ async def drain_to_final_msg(
             #
             # -[ ] make sure pause points work here for REPLing
             #   the runtime itself; i.e. ensure there's no hangs!
-            # |_from tractor.devx.debug import pause
+            # |_from tractor.devx._debug import pause
             #   await pause()
 
         # NOTE: we get here if the far end was

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/msg/types.py

@@ -154,39 +154,6 @@ class Aid(
     #     should also include at least `.pid` (equiv to port for tcp)
     #     and/or host-part always?
 
-    @property
-    def uid(self) -> tuple[str, str]:
-        '''
-        Legacy actor "unique-id" pair format.
-
-        '''
-        return (
-            self.name,
-            self.uuid,
-        )
-
-    def reprol(
-        self,
-        sin_uuid: bool = True,
-    ) -> str:
-        if not sin_uuid:
-            return (
-                f'{self.name}[{self.uuid[:6]}]@{self.pid!r}'
-            )
-        return (
-            f'{self.name}@{self.pid!r}'
-        )
-
-    # mk hashable via `.uuid`
-    def __hash__(self) -> int:
-        return hash(self.uuid)
-
-    def __eq__(self, other: Aid) -> bool:
-        return self.uuid == other.uuid
-
-    # use pretty fmt since often repr-ed for console/log
-    __repr__ = pretty_struct.Struct.__repr__
-
 
 class SpawnSpec(
     pretty_struct.Struct,

tractor/to_asyncio.py

@@ -38,6 +38,7 @@ from typing import (
 import tractor
 from tractor._exceptions import (
     InternalError,
+    is_multi_cancelled,
     TrioTaskExited,
     TrioCancelled,
     AsyncioTaskExited,
@@ -48,7 +49,7 @@ from tractor._state import (
     _runtime_vars,
 )
 from tractor._context import Unresolved
-from tractor.devx import debug
+from tractor.devx import _debug
 from tractor.log import (
     get_logger,
     StackLevelAdapter,
@@ -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,
@@ -481,12 +479,12 @@ def _run_asyncio_task(
     if (
         debug_mode()
         and
-        (greenback := debug.maybe_import_greenback(
+        (greenback := _debug.maybe_import_greenback(
             force_reload=True,
             raise_not_found=False,
         ))
     ):
-        log.devx(
+        log.info(
             f'Bestowing `greenback` portal for `asyncio`-task\n'
             f'{task}\n'
         )
@@ -843,7 +841,7 @@ async def translate_aio_errors(
     except BaseException as _trio_err:
         trio_err = chan._trio_err = _trio_err
         # await tractor.pause(shield=True)  # workx!
-        entered: bool = await debug._maybe_enter_pm(
+        entered: bool = await _debug._maybe_enter_pm(
             trio_err,
             api_frame=inspect.currentframe(),
         )
@@ -1408,7 +1406,7 @@ def run_as_asyncio_guest(
             )
             # XXX make it obvi we know this isn't supported yet!
             assert 0
-            # await debug.maybe_init_greenback(
+            # await _debug.maybe_init_greenback(
             #     force_reload=True,
             # )
 

tractor/trionics/__init__.py

@@ -31,9 +31,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,16 +22,11 @@ first-class-`trio` from a historical perspective B)
 from contextlib import (
     asynccontextmanager as acm,
 )
-from typing import (
-    Literal,
-)
-
-import trio
 
 
 def maybe_collapse_eg(
     beg: BaseExceptionGroup,
-) -> BaseException|bool:
+) -> BaseException:
     '''
     If the input beg can collapse to a single non-eg sub-exception,
     return it instead.
@@ -40,13 +35,11 @@ def maybe_collapse_eg(
     if len(excs := beg.exceptions) == 1:
         return excs[0]
 
-    return False
+    return beg
 
 
 @acm
-async def collapse_eg(
-    hide_tb: bool = True,
-):
+async def collapse_eg():
     '''
     If `BaseExceptionGroup` raised in the body scope is
     "collapse-able" (in the same way that
@@ -54,75 +47,12 @@ async def collapse_eg(
     only raise the lone emedded non-eg in in place.
 
     '''
-    __tracebackhide__: bool = hide_tb
     try:
         yield
     except* BaseException as beg:
         if (
             exc := maybe_collapse_eg(beg)
-        ):
-            if cause := exc.__cause__:
-                raise exc from cause
-
+        ) is not beg:
             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
@@ -72,6 +70,7 @@ async def maybe_open_nursery(
         yield nursery
     else:
         async with lib.open_nursery(**kwargs) as nursery:
+            if lib == trio:
                 nursery.cancel_scope.shield = shield
             yield nursery
 
@@ -113,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)
@@ -145,15 +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() 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,
@@ -170,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,185 +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 ish discussion @ `trio`-core,
-# https://github.com/python-trio/trio/issues/455#issuecomment-2785122216
-#
-@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
-    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

uv.lock

@@ -417,7 +417,7 @@ dev = [
     { name = "pyperclip", specifier = ">=1.9.0" },
     { name = "pytest", specifier = ">=8.3.5" },
     { name = "stackscope", specifier = ">=0.2.2,<0.3" },
-    { name = "typing-extensions", specifier = ">=4.13.2" },
+    { name = "typing-extensions", specifier = ">=4.14.1" },
     { name = "xonsh", specifier = ">=0.19.2" },
 ]
 
@@ -452,11 +452,11 @@ wheels = [
 
 [[package]]
 name = "typing-extensions"
-version = "4.13.2"
+version = "4.14.1"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/f6/37/23083fcd6e35492953e8d2aaaa68b860eb422b34627b13f2ce3eb6106061/typing_extensions-4.13.2.tar.gz", hash = "sha256:e6c81219bd689f51865d9e372991c540bda33a0379d5573cddb9a3a23f7caaef", size = 106967, upload-time = "2025-04-10T14:19:05.416Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/98/5a/da40306b885cc8c09109dc2e1abd358d5684b1425678151cdaed4731c822/typing_extensions-4.14.1.tar.gz", hash = "sha256:38b39f4aeeab64884ce9f74c94263ef78f3c22467c8724005483154c26648d36", size = 107673, upload-time = "2025-07-04T13:28:34.16Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/8b/54/b1ae86c0973cc6f0210b53d508ca3641fb6d0c56823f288d108bc7ab3cc8/typing_extensions-4.13.2-py3-none-any.whl", hash = "sha256:a439e7c04b49fec3e5d3e2beaa21755cadbbdc391694e28ccdd36ca4a1408f8c", size = 45806, upload-time = "2025-04-10T14:19:03.967Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/00/d631e67a838026495268c2f6884f3711a15a9a2a96cd244fdaea53b823fb/typing_extensions-4.14.1-py3-none-any.whl", hash = "sha256:d1e1e3b58374dc93031d6eda2420a48ea44a36c2b4766a4fdeb3710755731d76", size = 43906, upload-time = "2025-07-04T13:28:32.743Z" },
 ]
 
 [[package]]