Draft test-doc for "out-of-band" `asyncio.Task`..

Since there's no way to activate `greenback`'s portal in such cases, we
should at least have a test verifying our very loud error about the
inability to support this usage..

pyproject.toml

@@ -2,12 +2,14 @@
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+# ------ build-system ------
+
 [project]
 name = "tractor"
 version = "0.1.0a6dev0"
 description = 'structured concurrent `trio`-"actors"'
 authors = [{ name = "Tyler Goodlet", email = "goodboy_foss@protonmail.com" }]
-requires-python = "~=3.11"
+requires-python = ">= 3.11"
 readme = "docs/README.rst"
 license = "AGPL-3.0-or-later"
 keywords = [
@@ -30,32 +32,60 @@ classifiers = [
   "Topic :: System :: Distributed Computing",
 ]
 dependencies = [
+# trio runtime and friends
+  # (poetry) proper range specs,
+  # https://packaging.python.org/en/latest/discussions/install-requires-vs-requirements/#id5
+  # TODO, for 3.13 we must go go `0.27` which means we have to
+  # disable strict egs or port to handling them internally!
+  # trio='^0.27'
   "trio>=0.24,<0.25",
   "tricycle>=0.4.1,<0.5",
   "trio-typing>=0.10.0,<0.11",
+
   "wrapt>=1.16.0,<2",
   "colorlog>=6.8.2,<7",
+
+# built-in multi-actor `pdb` REPL
   "pdbp>=1.5.0,<2",
+
+# typed IPC msging
+# TODO, get back on release once 3.13 support is out!
   "msgspec",
 ]
 
+# ------ project ------
+
 [dependency-groups]
 dev = [
+  # test suite
+  # TODO: maybe some of these layout choices?
+  # https://docs.pytest.org/en/8.0.x/explanation/goodpractices.html#choosing-a-test-layout-import-rules
   "pytest>=8.2.0,<9",
   "pexpect>=4.9.0,<5",
+  # `tractor.devx` tooling
   "greenback>=1.2.1,<2",
   "stackscope>=0.2.2,<0.3",
+
+  # xonsh usage/integration (namely as @goodboy's sh of choice Bp)
+  "xonsh>=0.19.1",
   "xontrib-vox>=0.0.1,<0.0.2",
   "prompt-toolkit>=3.0.43,<4",
   "xonsh-vox-tabcomplete>=0.5,<0.6",
+  "pyperclip>=1.9.0",
 ]
 
+# TODO, distributed (multi-host) extensions
+# linux kernel networking
+# 'pyroute2
+
 [tool.hatch.build.targets.sdist]
 include = ["tractor"]
 
 [tool.hatch.build.targets.wheel]
 include = ["tractor"]
 
+# ------ dependency-groups ------
+
 [tool.towncrier]
 package = "tractor"
 filename = "NEWS.rst"
@@ -100,5 +130,9 @@ addopts = [
 ]
 log_cli = false
 
+# ------ tool.towncrier ------
+
 [tool.uv.sources]
 msgspec = { git = "https://github.com/jcrist/msgspec.git" }
+
+# ------ tool.uv.sources ------

ruff.toml

@@ -52,7 +52,7 @@ fixable = ["ALL"]
 unfixable = []
 
 # Allow unused variables when underscore-prefixed.
-dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+# dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 
 [format]
 # Use single quotes in `ruff format`.

tests/conftest.py

@@ -150,6 +150,18 @@ def pytest_generate_tests(metafunc):
         metafunc.parametrize("start_method", [spawn_backend], scope='module')
 
 
+# TODO: a way to let test scripts (like from `examples/`)
+# guarantee they won't registry addr collide!
+# @pytest.fixture
+# def open_test_runtime(
+#     reg_addr: tuple,
+# ) -> AsyncContextManager:
+#     return partial(
+#         tractor.open_nursery,
+#         registry_addrs=[reg_addr],
+#     )
+
+
 def sig_prog(proc, sig):
     "Kill the actor-process with ``sig``."
     proc.send_signal(sig)

tests/devx/test_pause_from_non_trio.py

@@ -218,10 +218,9 @@ def expect_any_of(
         )
 
     return expected_patts
-    # yield child
 
 
-def test_pause_from_asyncio_task(
+def test_sync_pause_from_aio_task(
     spawn,
     ctlc: bool
     # ^TODO, fix for `asyncio`!!
@@ -327,3 +326,25 @@ def test_pause_from_asyncio_task(
 
     child.sendline('c')
     child.expect(EOF)
+
+
+def test_sync_pause_from_non_greenbacked_aio_task():
+    '''
+    Where the `breakpoint()` caller task is NOT spawned by
+    `tractor.to_asyncio` and thus never activates
+    a `greenback.ensure_portal()` beforehand, presumably bc the task
+    was started by some lib/dep as in often seen in the field.
+
+    Ensure sync pausing works when the pause is in,
+
+    - the root actor running in infected-mode?
+      |_ since we don't need any IPC to acquire the debug lock?
+      |_ is there some way to handle this like the non-main-thread case?
+
+    All other cases need to error out appropriately right?
+
+    - for any subactor we can't avoid needing the repl lock..
+      |_ is there a way to hook into `asyncio.ensure_future(obj)`?
+
+    '''
+    pass

tractor/devx/__init__.py

@@ -41,3 +41,38 @@ from .pformat import (
     pformat_caller_frame as pformat_caller_frame,
     pformat_boxed_tb as pformat_boxed_tb,
 )
+
+
+def _enable_readline_feats() -> str:
+    '''
+    Handle `readline` when compiled with `libedit` to avoid breaking
+    tab completion in `pdbp` (and its dep `tabcompleter`)
+    particularly since `uv` cpython distis are compiled this way..
+
+    See docs for deats,
+    https://docs.python.org/3/library/readline.html#module-readline
+
+    Originally discovered soln via SO answer,
+    https://stackoverflow.com/q/49287102
+
+    '''
+    import readline
+    if (
+        # 3.13+ attr
+        # https://docs.python.org/3/library/readline.html#readline.backend
+        (getattr(readline, 'backend', False) == 'libedit')
+        or
+        'libedit' in readline.__doc__
+    ):
+        readline.parse_and_bind("python:bind -v")
+        readline.parse_and_bind("python:bind ^I rl_complete")
+        return 'libedit'
+    else:
+        readline.parse_and_bind("tab: complete")
+        readline.parse_and_bind("set editing-mode vi")
+        readline.parse_and_bind("set keymap vi")
+        return 'readline'
+
+
+# TODO, move this to a new `.devx._pdbp` mod?
+_enable_readline_feats()

uv.lock

@@ -1,5 +1,6 @@
 version = 1
-requires-python = ">=3.11, <4"
+revision = 1
+requires-python = ">=3.11"
 
 [[package]]
 name = "async-generator"
@@ -252,6 +253,12 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8a/0b/9fcc47d19c48b59121088dd6da2488a49d5f72dacf8262e2790a1d2c7d15/pygments-2.19.1-py3-none-any.whl", hash = "sha256:9ea1544ad55cecf4b8242fab6dd35a93bbce657034b0611ee383099054ab6d8c", size = 1225293 },
 ]
 
+[[package]]
+name = "pyperclip"
+version = "1.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/30/23/2f0a3efc4d6a32f3b63cdff36cd398d9701d26cda58e3ab97ac79fb5e60d/pyperclip-1.9.0.tar.gz", hash = "sha256:b7de0142ddc81bfc5c7507eea19da920b92252b548b96186caf94a5e2527d310", size = 20961 }
+
 [[package]]
 name = "pyreadline3"
 version = "3.5.4"
@@ -334,8 +341,10 @@ dev = [
     { name = "greenback" },
     { name = "pexpect" },
     { name = "prompt-toolkit" },
+    { name = "pyperclip" },
     { name = "pytest" },
     { name = "stackscope" },
+    { name = "xonsh" },
     { name = "xonsh-vox-tabcomplete" },
     { name = "xontrib-vox" },
 ]
@@ -356,8 +365,10 @@ dev = [
     { name = "greenback", specifier = ">=1.2.1,<2" },
     { name = "pexpect", specifier = ">=4.9.0,<5" },
     { name = "prompt-toolkit", specifier = ">=3.0.43,<4" },
+    { name = "pyperclip", specifier = ">=1.9.0" },
     { name = "pytest", specifier = ">=8.2.0,<9" },
     { name = "stackscope", specifier = ">=0.2.2,<0.3" },
+    { name = "xonsh", specifier = ">=0.19.1" },
     { name = "xonsh-vox-tabcomplete", specifier = ">=0.5,<0.6" },
     { name = "xontrib-vox", specifier = ">=0.0.1,<0.0.2" },
 ]