From f75865fb2e591831bfffdc4722e65a235a233b89 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Fri, 17 Apr 2026 19:03:00 -0400
Subject: [PATCH] Tidy `spawn/` subpkg docstrings and imports

Drop unused `TYPE_CHECKING` imports (`Channel`,
`_server`), remove commented-out `import os` in
`_entry.py`, and use `get_runtime_vars()` accessor
instead of bare `_runtime_vars` in `_trio.py`.

Also,
- freshen `__init__.py` layout docstring for the
  new per-backend submod structure
- update `_spawn.py` + `_trio.py` module docstrings

(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 tractor/spawn/__init__.py | 23 +++++++++--------------
 tractor/spawn/_entry.py   |  1 -
 tractor/spawn/_mp.py      |  1 -
 tractor/spawn/_spawn.py   |  5 ++---
 tractor/spawn/_trio.py    | 10 ++++------
 5 files changed, 15 insertions(+), 25 deletions(-)

diff --git a/tractor/spawn/__init__.py b/tractor/spawn/__init__.py
index 06ba413e..3f363889 100644
--- a/tractor/spawn/__init__.py
+++ b/tractor/spawn/__init__.py
@@ -17,29 +17,24 @@
 '''
 Actor process spawning machinery using multiple backends.
 
-Layout
-------
-- `._spawn`: the "core" supervisor machinery — spawn-method
-  registry (`SpawnMethodKey`, `_methods`, `_spawn_method`,
-  `_ctx`, `try_set_start_method`), the `new_proc` dispatcher,
-  and the cross-backend helpers `exhaust_portal`,
-  `cancel_on_completion`, `hard_kill`, `soft_kill`,
-  `proc_waiter`.
+- `._spawn`: cross-backend subactor-as-sub[proc|int] spawning
+  and supervision routines.
 
 Per-backend submodules (each exposes a single `*_proc()`
 coroutine registered in `_spawn._methods`):
 
 - `._trio`: the `trio`-native subprocess backend (default,
   all platforms), spawns via `trio.lowlevel.open_process()`.
-- `._mp`: the stdlib `multiprocessing` backends —
-  `'mp_spawn'` and `'mp_forkserver'` variants — driven by
-  the `mp.context` bound to `_spawn._ctx`.
+
+- `._mp`: the stdlib `multiprocessing` backend variants — driven by
+  the `mp.context` bound to `_spawn._ctx`:
+  * `'mp_spawn'`,
+  * `'mp_forkserver'` 
 
 Entry-point helpers live in `._entry`/`._mp_fixup_main`/
 `._forkserver_override`.
 
-NOTE: to avoid circular imports, this ``__init__`` does NOT
-eagerly import submodules. Use direct module paths like
-``tractor.spawn._spawn`` or ``tractor.spawn._trio`` instead.
+NOTE: to avoid circular imports, this ``__init__`` does NOT eagerly
+import submodules.
 
 '''
diff --git a/tractor/spawn/_entry.py b/tractor/spawn/_entry.py
index b33e78d9..3143d9c4 100644
--- a/tractor/spawn/_entry.py
+++ b/tractor/spawn/_entry.py
@@ -21,7 +21,6 @@ Sub-process entry points.
 from __future__ import annotations
 from functools import partial
 import multiprocessing as mp
-# import os
 from typing import (
     Any,
     TYPE_CHECKING,
diff --git a/tractor/spawn/_mp.py b/tractor/spawn/_mp.py
index addc8996..d0c8af32 100644
--- a/tractor/spawn/_mp.py
+++ b/tractor/spawn/_mp.py
@@ -57,7 +57,6 @@ from ._spawn import (
 if TYPE_CHECKING:
     from tractor.ipc import (
         _server,
-        Channel,
     )
     from tractor.runtime._supervise import ActorNursery
 
diff --git a/tractor/spawn/_spawn.py b/tractor/spawn/_spawn.py
index d040813a..f9cc0a51 100644
--- a/tractor/spawn/_spawn.py
+++ b/tractor/spawn/_spawn.py
@@ -15,7 +15,8 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 """
-Machinery for actor process spawning using multiple backends.
+Top level routines & machinery for actor-as-process/subint spawning
+over multiple backends.
 
 """
 from __future__ import annotations
@@ -35,7 +36,6 @@ from trio import TaskStatus
 
 from ..devx import debug
 from tractor.runtime._state import (
-    debug_mode,
     _runtime_vars,
 )
 from tractor.log import get_logger
@@ -47,7 +47,6 @@ from tractor.msg import types as msgtypes
 
 if TYPE_CHECKING:
     from tractor.ipc import (
-        _server,
         Channel,
     )
     from tractor.runtime._supervise import ActorNursery
diff --git a/tractor/spawn/_trio.py b/tractor/spawn/_trio.py
index a79d1c8d..bdb97c75 100644
--- a/tractor/spawn/_trio.py
+++ b/tractor/spawn/_trio.py
@@ -15,11 +15,10 @@
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 '''
-The `trio` subprocess spawning backend.
+The `trio`-subprocess backend; the default for cross-platform.
 
 Spawns sub-actors as fresh OS processes driven by
-`trio.lowlevel.open_process()` — our default, cross-platform
-spawn method.
+`trio.lowlevel.open_process()`.
 
 '''
 from __future__ import annotations
@@ -40,7 +39,7 @@ from tractor.runtime._state import (
     current_actor,
     is_root_process,
     debug_mode,
-    _runtime_vars,
+    get_runtime_vars,
 )
 from tractor.log import get_logger
 from tractor.discovery._addr import UnwrappedAddress
@@ -60,7 +59,6 @@ from ._spawn import (
 if TYPE_CHECKING:
     from tractor.ipc import (
         _server,
-        Channel,
     )
     from tractor.runtime._supervise import ActorNursery
 
@@ -248,7 +246,7 @@ async def trio_proc(
                             await proc.wait()
 
                 await debug.maybe_wait_for_debugger(
-                    child_in_debug=_runtime_vars.get(
+                    child_in_debug=get_runtime_vars().get(
                         '_debug_mode', False
                     ),
                     header_msg=(