Hide some API frames, port to new `._debug` apis

- start tossing in `__tracebackhide__`s to various eps which don't need
  to show in tbs or in the pdb REPL.
- port final `._maybe_enter_pm()` to pass a `api_frame`.
- start comment-marking up some API eps with `@api_frame`
  in prep for actually using the new frame-stack tracing.

tractor/_root.py

@@ -18,7 +18,7 @@
 Root actor runtime ignition(s).
 
 '''
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager as acm
 from functools import partial
 import importlib
 import logging
@@ -60,7 +60,7 @@ _default_lo_addrs: list[tuple[str, int]] = [(
 logger = log.get_logger('tractor')
 
 
-@asynccontextmanager
+@acm
 async def open_root_actor(
 
     *,
@@ -96,6 +96,7 @@ async def open_root_actor(
     Runtime init entry point for ``tractor``.
 
     '''
+    __tracebackhide__ = True
     # TODO: stick this in a `@cm` defined in `devx._debug`?
     #
     # Override the global debugger hook to make it play nice with
@@ -358,7 +359,11 @@ async def open_root_actor(
                 BaseExceptionGroup,
             ) as err:
 
-                entered: bool = await _debug._maybe_enter_pm(err)
+                import inspect
+                entered: bool = await _debug._maybe_enter_pm(
+                    err,
+                    api_frame=inspect.currentframe(),
+                )
 
                 if (
                     not entered

tractor/_spawn.py

@@ -142,7 +142,9 @@ async def exhaust_portal(
     '''
     __tracebackhide__ = True
     try:
-        log.debug(f"Waiting on final result from {actor.uid}")
+        log.debug(
+            f'Waiting on final result from {actor.uid}'
+        )
 
         # XXX: streams should never be reaped here since they should
         # always be established and shutdown using a context manager api
@@ -195,7 +197,10 @@ async def cancel_on_completion(
     # if this call errors we store the exception for later
     # in ``errors`` which will be reraised inside
     # an exception group and we still send out a cancel request
-    result: Any|Exception = await exhaust_portal(portal, actor)
+    result: Any|Exception = await exhaust_portal(
+        portal,
+        actor,
+    )
     if isinstance(result, Exception):
         errors[actor.uid]: Exception = result
         log.cancel(
@@ -503,14 +508,6 @@ async def trio_proc(
             )
         )
 
-        # await chan.send({
-        #     '_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,
-        # })
-
         # track subactor in current nursery
         curr_actor: Actor = current_actor()
         curr_actor._actoruid2nursery[subactor.uid] = actor_nursery
@@ -554,8 +551,8 @@ async def trio_proc(
         # killing the process too early.
         if proc:
             log.cancel(f'Hard reap sequence starting for {subactor.uid}')
-            with trio.CancelScope(shield=True):
 
+            with trio.CancelScope(shield=True):
                 # don't clobber an ongoing pdb
                 if cancelled_during_spawn:
                     # Try again to avoid TTY clobbering.

tractor/_supervise.py

@@ -346,8 +346,6 @@ async def _open_and_supervise_one_cancels_all_nursery(
     actor: Actor,
 
 ) -> typing.AsyncGenerator[ActorNursery, None]:
-
-    # TODO: yay or nay?
     __tracebackhide__ = True
 
     # the collection of errors retreived from spawned sub-actors
@@ -519,6 +517,7 @@ async def _open_and_supervise_one_cancels_all_nursery(
 
 
 @acm
+# @api_frame
 async def open_nursery(
     **kwargs,
 
@@ -538,6 +537,7 @@ async def open_nursery(
     which cancellation scopes correspond to each spawned subactor set.
 
     '''
+    __tracebackhide__ = True
     implicit_runtime: bool = False
     actor: Actor = current_actor(err_on_no_runtime=False)
     an: ActorNursery|None = None