From b71afdc6151831fe1d7c6258953c28dcb449e4ee Mon Sep 17 00:00:00 2001
From: Tyler Goodlet <jgbt@protonmail.com>
Date: Tue, 17 Jun 2025 17:47:27 -0400
Subject: [PATCH] Bah! just refine `devx.pformat.nest_from_op()`now!

Since we're gonna prolly start using it for serious..
- drop `back_from_op`.
- rename `tree_str` -> `text`
- move the huge comment-doc for "sclang" into the fn body.
- change all usage to reflect.
---
 tractor/_entry.py       | 12 +++++------
 tractor/_root.py        |  2 +-
 tractor/_runtime.py     |  6 +++---
 tractor/devx/pformat.py | 46 ++++++++++++++++++++---------------------
 4 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/tractor/_entry.py b/tractor/_entry.py
index 18bee7a6..8fffed5f 100644
--- a/tractor/_entry.py
+++ b/tractor/_entry.py
@@ -139,8 +139,8 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='>(',  # see syntax ideas above
-                tree_str=actor_info,
-                back_from_op=2,  # since "complete"
+                text=actor_info,
+                nest_indent=2,  # since "complete"
             )
         )
     logmeth = log.info
@@ -149,8 +149,8 @@ def _trio_main(
         +
         pformat.nest_from_op(
             input_op=')>',  # like a "closed-to-play"-icon from super perspective
-            tree_str=actor_info,
-            back_from_op=1,
+            text=actor_info,
+            nest_indent=1,
         )
     )
     try:
@@ -167,7 +167,7 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='c)>',  # closed due to cancel (see above)
-                tree_str=actor_info,
+                text=actor_info,
             )
         )
     except BaseException as err:
@@ -177,7 +177,7 @@ def _trio_main(
             +
             pformat.nest_from_op(
                 input_op='x)>',  # closed by error
-                tree_str=actor_info,
+                text=actor_info,
             )
         )
         # NOTE since we raise a tb will already be shown on the
diff --git a/tractor/_root.py b/tractor/_root.py
index e9c35f7f..51dfc660 100644
--- a/tractor/_root.py
+++ b/tractor/_root.py
@@ -521,7 +521,7 @@ async def open_root_actor(
 
                     op_nested_actor_repr: str = _pformat.nest_from_op(
                         input_op='>) ',
-                        tree_str=actor.pformat(),
+                        text=actor.pformat(),
                         nest_prefix='|_',
                     )
                     logger.info(
diff --git a/tractor/_runtime.py b/tractor/_runtime.py
index 2f9749a2..1d89c63d 100644
--- a/tractor/_runtime.py
+++ b/tractor/_runtime.py
@@ -1698,10 +1698,10 @@ async def async_main(
         )
 
     op_nested_actor_repr: str = _pformat.nest_from_op(
-        input_op=')> ',
-        tree_str=actor.pformat(),
+        input_op=')>',
+        text=actor.pformat(),
         nest_prefix='|_',
-        back_from_op=2,
+        nest_indent=1,  # under >
     )
     teardown_report += (
         'Actor runtime exited\n'
diff --git a/tractor/devx/pformat.py b/tractor/devx/pformat.py
index a3cfa5f4..a8ad8e5e 100644
--- a/tractor/devx/pformat.py
+++ b/tractor/devx/pformat.py
@@ -250,11 +250,28 @@ def pformat_cs(
 
 
 def nest_from_op(
-    input_op: str,
+    input_op: str,  # TODO, Literal of all op-"symbols" from below?
+    text: str,
+
+    nest_prefix: str = '|_',
+    nest_indent: int = 0,
+    # XXX indent `next_prefix` "to-the-right-of" `input_op`
+    # by this count of whitespaces (' ').
+
+) -> 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? 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.
+    # ?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
     #
@@ -320,24 +337,7 @@ def nest_from_op(
     #
     # =>{  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,
-    nest_prefix: str = '|_',
-    nest_indent: 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.
-
-    '''
-    nest_indent = nest_indent or back_from_op  # <- rm latter!
+    #
     if (
         nest_prefix
         and
@@ -350,7 +350,7 @@ def nest_from_op(
 
     tree_str_indent: int = len(nest_prefix)
     indented_tree_str: str = textwrap.indent(
-        tree_str,
+        text,
         prefix=' '*tree_str_indent
     )
     # inject any provided nesting-prefix chars