Mv core mods to `runtime/`, `spawn/`, `discovery/` subpkgs

Restructure the flat `tractor/` top-level private mods
into (more nested) subpackages:

- `runtime/`: `_runtime`, `_portal`, `_rpc`, `_state`,
  `_supervise`
- `spawn/`: `_spawn`, `_entry`, `_forkserver_override`,
  `_mp_fixup_main`
- `discovery/`: `_addr`, `_discovery`, `_multiaddr`

Each subpkg `__init__.py` is kept lazy (no eager
imports) to avoid circular import issues.

Also,
- update all intra-pkg imports across ~35 mods to use
  the new subpkg paths (e.g. `from .runtime._state`
  instead of `from ._state`)

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code

tractor/__init__.py

@@ -30,17 +30,17 @@ from ._streaming import (
     MsgStream as MsgStream,
     stream as stream,
 )
-from ._discovery import (
+from .discovery._discovery import (
     get_registry as get_registry,
     find_actor as find_actor,
     wait_for_actor as wait_for_actor,
     query_actor as query_actor,
 )
-from ._supervise import (
+from .runtime._supervise import (
     open_nursery as open_nursery,
     ActorNursery as ActorNursery,
 )
-from ._state import (
+from .runtime._state import (
     RuntimeVars as RuntimeVars,
     current_actor as current_actor,
     current_ipc_ctx as current_ipc_ctx,
@@ -67,6 +67,6 @@ from ._root import (
     open_root_actor as open_root_actor,
 )
 from .ipc import Channel as Channel
-from ._portal import Portal as Portal
-from ._runtime import Actor as Actor
+from .runtime._portal import Portal as Portal
+from .runtime._runtime import Actor as Actor
 # from . import hilevel as hilevel

tractor/_child.py

@@ -22,8 +22,8 @@ import argparse
 
 from ast import literal_eval
 
-from ._runtime import Actor
-from ._entry import _trio_main
+from .runtime._runtime import Actor
+from .spawn._entry import _trio_main
 
 
 def parse_uid(arg):

tractor/_context.py

@@ -97,7 +97,7 @@ from ._streaming import (
     MsgStream,
     open_stream_from_ctx,
 )
-from ._state import (
+from .runtime._state import (
     current_actor,
     debug_mode,
     _ctxvar_Context,
@@ -107,8 +107,8 @@ from .trionics import (
 )
 # ------ - ------
 if TYPE_CHECKING:
-    from ._portal import Portal
-    from ._runtime import Actor
+    from .runtime._portal import Portal
+    from .runtime._runtime import Actor
     from .ipc._transport import MsgTransport
     from .devx._frame_stack import (
         CallerInfo,

tractor/_exceptions.py

@@ -43,7 +43,7 @@ from msgspec import (
     ValidationError,
 )
 
-from tractor._state import current_actor
+from tractor.runtime._state import current_actor
 from tractor.log import get_logger
 from tractor.msg import (
     Error,

tractor/_root.py

@@ -37,19 +37,19 @@ import warnings
 
 import trio
 
-from . import _runtime
+from .runtime import _runtime
 from .devx import (
     debug,
     _frame_stack,
     pformat as _pformat,
 )
-from . import _spawn
-from . import _state
+from .spawn import _spawn
+from .runtime import _state
 from . import log
 from .ipc import (
     _connect_chan,
 )
-from ._addr import (
+from .discovery._addr import (
     Address,
     UnwrappedAddress,
     default_lo_addrs,

tractor/_streaming.py

@@ -55,7 +55,7 @@ from tractor.msg import (
 )
 
 if TYPE_CHECKING:
-    from ._runtime import Actor
+    from .runtime._runtime import Actor
     from ._context import Context
     from .ipc import Channel
 

tractor/_testing/addr.py

@@ -26,9 +26,7 @@ import random
 from typing import (
     Type,
 )
-from tractor import (
-    _addr,
-)
+from tractor.discovery import _addr
 
 
 def get_rando_addr(

tractor/devx/_stackscope.py

@@ -45,17 +45,15 @@ from typing import (
 )
 
 import trio
-from tractor import (
-    _state,
-    log as logmod,
-)
+from tractor.runtime import _state
+from tractor import log as logmod
 from tractor.devx import debug
 
 log = logmod.get_logger()
 
 
 if TYPE_CHECKING:
-    from tractor._spawn import ProcessType
+    from tractor.spawn._spawn import ProcessType
     from tractor import (
         Actor,
         ActorNursery,

tractor/devx/debug/_post_mortem.py

@@ -53,8 +53,8 @@ import trio
 from tractor._exceptions import (
     NoRuntime,
 )
-from tractor import _state
-from tractor._state import (
+from tractor.runtime import _state
+from tractor.runtime._state import (
     current_actor,
     debug_mode,
 )
@@ -76,7 +76,7 @@ from ._repl import (
 
 if TYPE_CHECKING:
     from trio.lowlevel import Task
-    from tractor._runtime import (
+    from tractor.runtime._runtime import (
         Actor,
     )
 

tractor/devx/debug/_repl.py

@@ -25,7 +25,7 @@ from functools import (
 import os
 
 import pdbp
-from tractor._state import (
+from tractor.runtime._state import (
     is_root_process,
 )
 

tractor/devx/debug/_sigint.py

@@ -27,7 +27,7 @@ from typing import (
 )
 import trio
 from tractor.log import get_logger
-from tractor._state import (
+from tractor.runtime._state import (
     current_actor,
     is_root_process,
 )
@@ -44,7 +44,7 @@ if TYPE_CHECKING:
     from tractor.ipc import (
         Channel,
     )
-    from tractor._runtime import (
+    from tractor.runtime._runtime import (
         Actor,
     )
 

tractor/devx/debug/_sync.py

@@ -40,7 +40,7 @@ from trio.lowlevel import (
     Task,
 )
 from tractor._context import Context
-from tractor._state import (
+from tractor.runtime._state import (
     current_actor,
     debug_mode,
     is_root_process,

tractor/devx/debug/_trace.py

@@ -55,12 +55,12 @@ import tractor
 from tractor.log import get_logger
 from tractor.to_asyncio import run_trio_task_in_future
 from tractor._context import Context
-from tractor import _state
+from tractor.runtime import _state
 from tractor._exceptions import (
     NoRuntime,
     InternalError,
 )
-from tractor._state import (
+from tractor.runtime._state import (
     current_actor,
     current_ipc_ctx,
     is_root_process,
@@ -87,7 +87,7 @@ from ..pformat import (
 if TYPE_CHECKING:
     from trio.lowlevel import Task
     from threading import Thread
-    from tractor._runtime import (
+    from tractor.runtime._runtime import (
         Actor,
     )
     # from ._post_mortem import BoxedMaybeException

tractor/devx/debug/_tty_lock.py

@@ -55,12 +55,12 @@ import tractor
 from tractor.to_asyncio import run_trio_task_in_future
 from tractor.log import get_logger
 from tractor._context import Context
-from tractor import _state
+from tractor.runtime import _state
 from tractor._exceptions import (
     DebugRequestError,
     InternalError,
 )
-from tractor._state import (
+from tractor.runtime._state import (
     current_actor,
     is_root_process,
 )
@@ -71,7 +71,7 @@ if TYPE_CHECKING:
     from tractor.ipc import (
         IPCServer,
     )
-    from tractor._runtime import (
+    from tractor.runtime._runtime import (
         Actor,
     )
     from ._repl import (
@@ -1013,7 +1013,7 @@ async def request_root_stdio_lock(
     DebugStatus.req_task = current_task()
     req_err: BaseException|None = None
     try:
-        from tractor._discovery import get_root
+        from tractor.discovery._discovery import get_root
         # NOTE: we need this to ensure that this task exits
         # BEFORE the REPl instance raises an error like
         # `bdb.BdbQuit` directly, OW you get a trio cs stack

tractor/discovery/__init__.py

@@ -0,0 +1,26 @@
+# 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/>.
+
+'''
+Discovery (protocols) API for automatic addressing
+and location management of (service) actors.
+
+NOTE: to avoid circular imports, this ``__init__``
+does NOT eagerly import submodules. Use direct
+module paths like ``tractor.discovery._addr`` or
+``tractor.discovery._discovery`` instead.
+
+'''

tractor/discovery/_addr.py

@@ -27,15 +27,15 @@ from trio import (
     SocketListener,
 )
 
-from .log import get_logger
-from ._state import (
+from ..log import get_logger
+from ..runtime._state import (
     _def_tpt_proto,
 )
-from .ipc._tcp import TCPAddress
-from .ipc._uds import UDSAddress
+from ..ipc._tcp import TCPAddress
+from ..ipc._uds import UDSAddress
 
 if TYPE_CHECKING:
-    from ._runtime import Actor
+    from ..runtime._runtime import Actor
 
 log = get_logger()
 

tractor/discovery/_discovery.py

@@ -28,29 +28,29 @@ from typing import (
 from contextlib import asynccontextmanager as acm
 
 from tractor.log import get_logger
-from .trionics import (
+from ..trionics import (
     gather_contexts,
     collapse_eg,
 )
-from .ipc import _connect_chan, Channel
+from ..ipc import _connect_chan, Channel
 from ._addr import (
     UnwrappedAddress,
     Address,
     wrap_address
 )
-from ._portal import (
+from ..runtime._portal import (
     Portal,
     open_portal,
     LocalPortal,
 )
-from ._state import (
+from ..runtime._state import (
     current_actor,
     _runtime_vars,
     _def_tpt_proto,
 )
 
 if TYPE_CHECKING:
-    from ._runtime import Actor
+    from ..runtime._runtime import Actor
 
 
 log = get_logger()

tractor/experimental/_pubsub.py

@@ -244,8 +244,12 @@ def pub(
         task2lock[name] = trio.StrictFIFOLock()
 
     @wrapt.decorator
-    async def wrapper(agen, instance, args, kwargs):
-
+    async def wrapper(
+        agen,
+        instance,
+        args,
+        kwargs,
+    ):
         # XXX: this is used to extract arguments properly as per the
         # `wrapt` docs
         async def _execute(

tractor/ipc/_chan.py

@@ -39,7 +39,7 @@ from ._types import (
     transport_from_addr,
     transport_from_stream,
 )
-from tractor._addr import (
+from tractor.discovery._addr import (
     is_wrapped_addr,
     wrap_address,
     Address,

tractor/ipc/_server.py

@@ -50,26 +50,24 @@ from ..devx.pformat import (
 from .._exceptions import (
     TransportClosed,
 )
-from .. import _rpc
+from ..runtime import _rpc
 from ..msg import (
     MsgType,
     Struct,
     types as msgtypes,
 )
 from ..trionics import maybe_open_nursery
-from .. import (
-    _state,
-    log,
-)
-from .._addr import Address
+from ..runtime import _state
+from .. import log
+from ..discovery._addr import Address
 from ._chan import Channel
 from ._transport import MsgTransport
 from ._uds import UDSAddress
 from ._tcp import TCPAddress
 
 if TYPE_CHECKING:
-    from .._runtime import Actor
-    from .._supervise import ActorNursery
+    from ..runtime._runtime import Actor
+    from ..runtime._supervise import ActorNursery
 
 
 log = log.get_logger()
@@ -970,7 +968,7 @@ class Server(Struct):
         in `accept_addrs`.
 
         '''
-        from .._addr import (
+        from ..discovery._addr import (
             default_lo_addrs,
             wrap_address,
         )

tractor/ipc/_transport.py

@@ -54,7 +54,7 @@ from tractor.msg import (
 )
 
 if TYPE_CHECKING:
-    from tractor._addr import Address
+    from tractor.discovery._addr import Address
 
 log = get_logger()
 

tractor/ipc/_uds.py

@@ -53,14 +53,14 @@ from tractor.log import get_logger
 from tractor.ipc._transport import (
     MsgpackTransport,
 )
-from tractor._state import (
+from tractor.runtime._state import (
     get_rt_dir,
     current_actor,
     is_root_process,
 )
 
 if TYPE_CHECKING:
-    from ._runtime import Actor
+    from tractor.runtime._runtime import Actor
 
 
 # Platform-specific credential passing constants

tractor/log.py

@@ -47,7 +47,7 @@ import colorlog  # type: ignore
 # import colored_traceback.auto  # ?TODO, need better config?
 import trio
 
-from ._state import current_actor
+from .runtime._state import current_actor
 
 
 _default_loglevel: str = 'ERROR'

tractor/msg/_ops.py

@@ -50,7 +50,7 @@ from tractor._exceptions import (
     _mk_recv_mte,
     pack_error,
 )
-from tractor._state import (
+from tractor.runtime._state import (
     current_ipc_ctx,
 )
 from ._codec import (

tractor/runtime/__init__.py

@@ -0,0 +1,26 @@
+# 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/>.
+
+'''
+The actor runtime: core machinery for the
+actor-model implemented on a `trio` task runtime.
+
+NOTE: to avoid circular imports, this ``__init__``
+does NOT eagerly import submodules. Use direct
+module paths like ``tractor.runtime._state`` or
+``tractor.runtime._runtime`` instead.
+
+'''

tractor/runtime/_portal.py

@@ -39,30 +39,30 @@ import warnings
 
 import trio
 
-from .trionics import (
+from ..trionics import (
     maybe_open_nursery,
     collapse_eg,
 )
 from ._state import (
     current_actor,
 )
-from .ipc import Channel
-from .log import get_logger
-from .msg import (
+from ..ipc import Channel
+from ..log import get_logger
+from ..msg import (
     # Error,
     PayloadMsg,
     NamespacePath,
     Return,
 )
-from ._exceptions import (
+from .._exceptions import (
     NoResult,
     TransportClosed,
 )
-from ._context import (
+from .._context import (
     Context,
     open_context_from_portal,
 )
-from ._streaming import (
+from .._streaming import (
     MsgStream,
 )
 

tractor/runtime/_rpc.py

@@ -43,11 +43,11 @@ from trio import (
     TaskStatus,
 )
 
-from .ipc import Channel
-from ._context import (
+from ..ipc import Channel
+from .._context import (
     Context,
 )
-from ._exceptions import (
+from .._exceptions import (
     ContextCancelled,
     RemoteActorError,
     ModuleNotExposed,
@@ -56,19 +56,19 @@ from ._exceptions import (
     pack_error,
     unpack_error,
 )
-from .trionics import (
+from ..trionics import (
     collapse_eg,
     is_multi_cancelled,
     maybe_raise_from_masking_exc,
 )
-from .devx import (
+from ..devx import (
     debug,
     add_div,
     pformat as _pformat,
 )
 from . import _state
-from .log import get_logger
-from .msg import (
+from ..log import get_logger
+from ..msg import (
     current_codec,
     MsgCodec,
     PayloadT,

tractor/runtime/_runtime.py

@@ -84,46 +84,46 @@ from tractor.msg import (
     pretty_struct,
     types as msgtypes,
 )
-from .trionics import (
+from ..trionics import (
     collapse_eg,
     maybe_open_nursery,
 )
-from .ipc import (
+from ..ipc import (
     Channel,
     # IPCServer,  # causes cycles atm..
     _server,
 )
-from ._addr import (
+from ..discovery._addr import (
     UnwrappedAddress,
     Address,
     # default_lo_addrs,
     get_address_cls,
     wrap_address,
 )
-from ._context import (
+from .._context import (
     mk_context,
     Context,
 )
-from .log import get_logger
-from ._exceptions import (
+from ..log import get_logger
+from .._exceptions import (
     ContextCancelled,
     InternalError,
     ModuleNotExposed,
     MsgTypeError,
     unpack_error,
 )
-from .devx import (
+from ..devx import (
     debug,
     pformat as _pformat
 )
-from ._discovery import get_registry
+from ..discovery._discovery import get_registry
 from ._portal import Portal
 from . import _state
-from . import _mp_fixup_main
+from ..spawn import _mp_fixup_main
 from . import _rpc
 
 if TYPE_CHECKING:
-    from ._supervise import ActorNursery
+    from ._supervise import ActorNursery  # noqa
     from trio._channel import MemoryChannelState
 
 
@@ -908,7 +908,7 @@ class Actor:
                 # TODO! -[ ] another `Struct` for rtvs..
                 rvs: dict[str, Any] = spawnspec._runtime_vars
                 if rvs['_debug_mode']:
-                    from .devx import (
+                    from ..devx import (
                         enable_stack_on_sig,
                         maybe_init_greenback,
                     )

tractor/runtime/_state.py

@@ -40,7 +40,7 @@ from msgspec import (
 
 if TYPE_CHECKING:
     from ._runtime import Actor
-    from ._context import Context
+    from .._context import Context
 
 
 # default IPC transport protocol settings
@@ -182,7 +182,7 @@ def current_actor(
         _current_actor is None
     ):
         msg: str = 'No local actor has been initialized yet?\n'
-        from ._exceptions import NoRuntime
+        from .._exceptions import NoRuntime
 
         if last := last_actor():
             msg += (
@@ -248,7 +248,7 @@ def current_ipc_ctx(
         not ctx
         and error_on_not_set
     ):
-        from ._exceptions import InternalError
+        from .._exceptions import InternalError
         raise InternalError(
             'No IPC context has been allocated for this task yet?\n'
             f'|_{current_task()}\n'

tractor/runtime/_supervise.py

@@ -30,36 +30,36 @@ import warnings
 import trio
 
 
-from .devx import (
+from ..devx import (
     debug,
     pformat as _pformat,
 )
-from ._addr import (
+from ..discovery._addr import (
     UnwrappedAddress,
     mk_uuid,
 )
 from ._state import current_actor, is_main_process
-from .log import get_logger, get_loglevel
+from ..log import get_logger, get_loglevel
 from ._runtime import Actor
 from ._portal import Portal
-from .trionics import (
+from ..trionics import (
     is_multi_cancelled,
     collapse_eg,
 )
-from ._exceptions import (
+from .._exceptions import (
     ContextCancelled,
 )
-from ._root import (
+from .._root import (
     open_root_actor,
 )
 from . import _state
-from . import _spawn
+from ..spawn import _spawn
 
 
 if TYPE_CHECKING:
     import multiprocessing as mp
-    # from .ipc._server import IPCServer
-    from .ipc import IPCServer
+    # from ..ipc._server import IPCServer
+    from ..ipc import IPCServer
 
 
 log = get_logger()

tractor/spawn/__init__.py

@@ -0,0 +1,26 @@
+# 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/>.
+
+'''
+Actor process spawning machinery using
+multiple backends (trio, multiprocessing).
+
+NOTE: to avoid circular imports, this ``__init__``
+does NOT eagerly import submodules. Use direct
+module paths like ``tractor.spawn._spawn`` or
+``tractor.spawn._entry`` instead.
+
+'''

tractor/spawn/_entry.py

@@ -29,19 +29,19 @@ from typing import (
 
 import trio  # type: ignore
 
-from .log import (
+from ..log import (
     get_console_log,
     get_logger,
 )
-from . import _state
-from .devx import (
+from ..runtime import _state
+from ..devx import (
     _frame_stack,
     pformat,
 )
-# from .msg import pretty_struct
-from .to_asyncio import run_as_asyncio_guest
-from ._addr import UnwrappedAddress
-from ._runtime import (
+# from ..msg import pretty_struct
+from ..to_asyncio import run_as_asyncio_guest
+from ..discovery._addr import UnwrappedAddress
+from ..runtime._runtime import (
     async_main,
     Actor,
 )

tractor/spawn/_forkserver_override.py

@@ -125,7 +125,7 @@ class PatchedForkServer(ForkServer):
                 self._forkserver_pid = None
 
             # XXX only thing that changed!
-            cmd = ('from tractor._forkserver_override import main; ' +
+            cmd = ('from tractor.spawn._forkserver_override import main; ' +
                    'main(%d, %d, %r, **%r)')
 
             if self._preload_modules:

tractor/spawn/_spawn.py

@@ -34,11 +34,11 @@ from typing import (
 import trio
 from trio import TaskStatus
 
-from .devx import (
+from ..devx import (
     debug,
     pformat as _pformat
 )
-from tractor._state import (
+from tractor.runtime._state import (
     current_actor,
     is_main_process,
     is_root_process,
@@ -46,10 +46,10 @@ from tractor._state import (
     _runtime_vars,
 )
 from tractor.log import get_logger
-from tractor._addr import UnwrappedAddress
-from tractor._portal import Portal
-from tractor._runtime import Actor
-from tractor._entry import _mp_main
+from tractor.discovery._addr import UnwrappedAddress
+from tractor.runtime._portal import Portal
+from tractor.runtime._runtime import Actor
+from ._entry import _mp_main
 from tractor._exceptions import ActorFailure
 from tractor.msg import (
     types as msgtypes,
@@ -58,11 +58,11 @@ from tractor.msg import (
 
 
 if TYPE_CHECKING:
-    from ipc import (
+    from tractor.ipc import (
         _server,
         Channel,
     )
-    from ._supervise import ActorNursery
+    from tractor.runtime._supervise import ActorNursery
     ProcessType = TypeVar('ProcessType', mp.Process, trio.Process)
 
 

tractor/to_asyncio.py

@@ -43,7 +43,7 @@ from tractor._exceptions import (
     AsyncioTaskExited,
     AsyncioCancelled,
 )
-from tractor._state import (
+from tractor.runtime._state import (
     debug_mode,
     _runtime_vars,
 )

tractor/trionics/_mngrs.py

@@ -37,7 +37,7 @@ from typing import (
 )
 
 import trio
-from tractor._state import current_actor
+from tractor.runtime._state import current_actor
 from tractor.log import get_logger
 # from ._beg import collapse_eg
 # from ._taskc import (