python-tty 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

python_tty/__init__.py

@@ -1,15 +1,18 @@
-from python_tty.config import Config
-from python_tty.console_factory import ConsoleFactory
-from python_tty.runtime.events import (
-    EventBase,
-    RuntimeEvent,
-    RuntimeEventKind,
-    UIEvent,
-    UIEventLevel,
-    UIEventListener,
-    UIEventSpeaker,
-)
-from python_tty.runtime.router import proxy_print
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from python_tty.config import Config
+    from python_tty.console_factory import ConsoleFactory
+    from python_tty.runtime.events import (
+        EventBase,
+        RuntimeEvent,
+        RuntimeEventKind,
+        UIEvent,
+        UIEventLevel,
+        UIEventListener,
+        UIEventSpeaker,
+    )
+    from python_tty.runtime.router import proxy_print
 
 __all__ = [
     "UIEvent",
@@ -23,3 +26,44 @@ __all__ = [
     "Config",
     "proxy_print",
 ]
+
+
+def __getattr__(name):
+    if name == "Config":
+        from python_tty.config import Config
+        return Config
+    if name == "ConsoleFactory":
+        from python_tty.console_factory import ConsoleFactory
+        return ConsoleFactory
+    if name == "proxy_print":
+        from python_tty.runtime.router import proxy_print
+        return proxy_print
+    if name in {
+        "UIEvent",
+        "UIEventLevel",
+        "EventBase",
+        "RuntimeEvent",
+        "RuntimeEventKind",
+        "UIEventListener",
+        "UIEventSpeaker",
+    }:
+        from python_tty.runtime.events import (
+            EventBase,
+            RuntimeEvent,
+            RuntimeEventKind,
+            UIEvent,
+            UIEventLevel,
+            UIEventListener,
+            UIEventSpeaker,
+        )
+        mapping = {
+            "UIEvent": UIEvent,
+            "UIEventLevel": UIEventLevel,
+            "EventBase": EventBase,
+            "RuntimeEvent": RuntimeEvent,
+            "RuntimeEventKind": RuntimeEventKind,
+            "UIEventListener": UIEventListener,
+            "UIEventSpeaker": UIEventSpeaker,
+        }
+        return mapping[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

python_tty/testing/__init__.py

@@ -0,0 +1,12 @@
+from python_tty.testing.decorators import tty_testable
+from python_tty.testing.discovery import discover_tests
+from python_tty.testing.harness import CommandHarness, InvocationHarness
+from python_tty.testing.results import TestRunResult
+
+__all__ = [
+    "tty_testable",
+    "discover_tests",
+    "CommandHarness",
+    "InvocationHarness",
+    "TestRunResult",
+]

python_tty/testing/capture.py

@@ -0,0 +1,72 @@
+from contextlib import contextmanager
+from typing import Dict, Iterable, List, Optional
+
+from python_tty.runtime.events import RuntimeEvent, UIEvent
+from python_tty.runtime.router import BaseRouter
+
+
+class CollectingRouter(BaseRouter):
+    """In-memory router used by test harnesses to capture UI events."""
+
+    def __init__(self):
+        self.events: List[object] = []
+
+    def emit(self, event):
+        self.events.append(event)
+
+
+@contextmanager
+def capture_executor_events(executor, sink: List[object]):
+    """Temporarily intercept executor.publish_event and append events to sink."""
+
+    original = executor.publish_event
+
+    def _publish(run_id, event):
+        sink.append(event)
+        return original(run_id, event)
+
+    executor.publish_event = _publish
+    try:
+        yield sink
+    finally:
+        executor.publish_event = original
+
+
+def build_output_records(runtime_events: Iterable[object], ui_events: Optional[Iterable[object]] = None):
+    """Normalize runtime/UI events into a lightweight output record list."""
+
+    outputs: List[Dict[str, object]] = []
+    for event in runtime_events:
+        outputs.append(_event_to_record(event, channel="runtime"))
+    for event in ui_events or []:
+        outputs.append(_event_to_record(event, channel="ui"))
+    return outputs
+
+
+def _event_to_record(event: object, channel: str):
+    if isinstance(event, RuntimeEvent):
+        kind = getattr(event.kind, "value", event.kind)
+    else:
+        kind = None
+    if isinstance(event, (RuntimeEvent, UIEvent)):
+        level = getattr(getattr(event, "level", None), "value", getattr(event, "level", None))
+        return {
+            "channel": channel,
+            "kind": kind,
+            "message": getattr(event, "msg", None),
+            "level": level,
+            "source": getattr(event, "source", None),
+            "event_type": getattr(event, "event_type", None),
+            "run_id": getattr(event, "run_id", None),
+            "seq": getattr(event, "seq", None),
+        }
+    return {
+        "channel": channel,
+        "kind": kind,
+        "message": str(event),
+        "level": None,
+        "source": None,
+        "event_type": None,
+        "run_id": None,
+        "seq": None,
+    }

python_tty/testing/decorators.py

@@ -0,0 +1,67 @@
+import inspect
+from typing import Any, Dict
+
+from python_tty.commands import BaseCommands
+from python_tty.commands.registry import CommandInfo
+from python_tty.exceptions.console_exception import ConsoleInitException
+
+
+TESTABLE_ATTR = "__tty_testable__"
+TEST_META_ATTR = "__tty_test_meta__"
+TEST_SCOPE_ATTR = "__tty_test_scope__"
+
+
+def tty_testable(target=None, **meta):
+    """Mark command classes/methods as discoverable by python_tty.testing."""
+
+    if target is None:
+        return lambda real_target: tty_testable(real_target, **meta)
+
+    if inspect.isclass(target):
+        if not issubclass(target, BaseCommands):
+            raise ConsoleInitException(
+                "@tty_testable class target must inherit BaseCommands"
+            )
+        _mark_testable(target, scope="class", meta=meta)
+        return target
+
+    if callable(target):
+        func = _unwrap_callable(target)
+        if not _is_registered_command_method(func):
+            raise ConsoleInitException(
+                "@tty_testable method target must be a registered command method "
+                "(decorate with @register_command first)"
+            )
+        _mark_testable(func, scope="method", meta=meta)
+        return target
+
+    raise ConsoleInitException(
+        "@tty_testable target must be a BaseCommands subclass or registered command method"
+    )
+
+
+def _unwrap_callable(value):
+    return getattr(value, "__func__", value)
+
+
+def _is_registered_command_method(func) -> bool:
+    if not callable(func):
+        return False
+    info = getattr(func, "info", None)
+    return isinstance(info, CommandInfo)
+
+
+def _mark_testable(target, scope: str, meta: Dict[str, Any]):
+    existing_meta = _read_meta(target)
+    merged_meta = dict(existing_meta)
+    merged_meta.update(meta)
+    setattr(target, TESTABLE_ATTR, True)
+    setattr(target, TEST_META_ATTR, merged_meta)
+    setattr(target, TEST_SCOPE_ATTR, scope)
+
+
+def _read_meta(target):
+    meta = getattr(target, TEST_META_ATTR, None)
+    if isinstance(meta, dict):
+        return meta
+    return {}

python_tty/testing/discovery.py

@@ -0,0 +1,263 @@
+import inspect
+import types
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple
+
+from python_tty.commands import BaseCommands
+from python_tty.commands.registry import COMMAND_REGISTRY
+from python_tty.consoles.registry import REGISTRY
+from python_tty.testing.decorators import TEST_META_ATTR, TESTABLE_ATTR
+
+
+@dataclass
+class DiscoveredTestCase:
+    """Metadata for a single command test case discovered from command classes."""
+
+    command_id: str
+    command_name: str
+    console_name: Optional[str]
+    console_cls: Optional[type]
+    commands_cls: type
+    method_name: str
+    method: object
+    class_marked: bool
+    method_marked: bool
+    test_meta: Dict[str, Any] = field(default_factory=dict)
+
+
+class DiscoveredTestSuite:
+    """Stable suite wrapper returned by discover_tests()."""
+
+    def __init__(self, cases: Sequence[DiscoveredTestCase]):
+        ordered = sorted(cases, key=lambda c: c.command_id)
+        deduped: Dict[str, DiscoveredTestCase] = {}
+        for case in ordered:
+            deduped[case.command_id] = case
+        self._cases: Tuple[DiscoveredTestCase, ...] = tuple(deduped.values())
+        self._cases_by_id: Dict[str, DiscoveredTestCase] = dict(deduped)
+
+    @property
+    def cases(self) -> Tuple[DiscoveredTestCase, ...]:
+        return self._cases
+
+    def list_cases(self) -> List[DiscoveredTestCase]:
+        return list(self._cases)
+
+    def get_case(self, command_id: str) -> Optional[DiscoveredTestCase]:
+        return self._cases_by_id.get(command_id)
+
+    def ids(self) -> List[str]:
+        return [case.command_id for case in self._cases]
+
+    def __len__(self):
+        return len(self._cases)
+
+    def __iter__(self):
+        return iter(self._cases)
+
+
+def discover_tests(*targets, command_ids: Optional[Iterable[str]] = None):
+    """Explicitly discover command test cases from modules/classes/methods/ids."""
+
+    expanded_targets = _expand_targets(targets)
+    explicit_command_ids: Set[str] = set(command_ids or [])
+    commands_classes: List[type] = []
+    explicit_classes: Set[type] = set()
+    explicit_methods: Set[object] = set()
+
+    for target in expanded_targets:
+        if isinstance(target, str):
+            explicit_command_ids.add(target)
+            continue
+
+        if inspect.isclass(target) and issubclass(target, BaseCommands):
+            commands_classes.append(target)
+            explicit_classes.add(target)
+            continue
+
+        if isinstance(target, types.ModuleType):
+            commands_classes.extend(_collect_commands_classes_from_module(target))
+            continue
+
+        if isinstance(target, BaseCommands):
+            commands_cls = target.__class__
+            commands_classes.append(commands_cls)
+            explicit_classes.add(commands_cls)
+            continue
+
+        func = _unwrap_callable(target)
+        if callable(func) and hasattr(func, "info"):
+            explicit_methods.add(func)
+            owner_cls = _resolve_owner_commands_cls(func)
+            if owner_cls is not None:
+                commands_classes.append(owner_cls)
+            continue
+
+        raise ValueError(f"Unsupported discover_tests target: {target!r}")
+
+    if explicit_command_ids:
+        commands_classes.extend(_collect_classes_by_command_ids(explicit_command_ids))
+
+    unique_classes = _unique_ordered(commands_classes)
+    cases: List[DiscoveredTestCase] = []
+
+    for commands_cls in unique_classes:
+        class_marked = bool(getattr(commands_cls, TESTABLE_ATTR, False))
+        class_meta = _read_meta(commands_cls)
+        is_explicit_class = commands_cls in explicit_classes
+        console_bindings = _resolve_console_bindings(commands_cls)
+        command_defs = COMMAND_REGISTRY.collect_from_commands_cls(commands_cls)
+
+        for command_def in command_defs:
+            method = _resolve_method(commands_cls, command_def.func)
+            method_marked = bool(getattr(method, TESTABLE_ATTR, False))
+            method_meta = _read_meta(method)
+            method_selected = _is_method_selected(method, explicit_methods)
+
+            for console_name, console_cls in console_bindings:
+                command_id = _build_command_id(console_name, command_def.func_name)
+                by_id = command_id in explicit_command_ids
+                include = is_explicit_class or class_marked or method_marked or method_selected or by_id
+                if not include:
+                    continue
+                case_meta = dict(class_meta)
+                case_meta.update(method_meta)
+                cases.append(
+                    DiscoveredTestCase(
+                        command_id=command_id,
+                        command_name=command_def.func_name,
+                        console_name=console_name,
+                        console_cls=console_cls,
+                        commands_cls=commands_cls,
+                        method_name=method.__name__,
+                        method=method,
+                        class_marked=class_marked,
+                        method_marked=method_marked,
+                        test_meta=case_meta,
+                    )
+                )
+
+    return DiscoveredTestSuite(cases)
+
+
+def _expand_targets(targets) -> List[object]:
+    expanded: List[object] = []
+    for target in targets:
+        if target is None:
+            continue
+        if isinstance(target, (list, tuple, set)):
+            expanded.extend(_expand_targets(tuple(target)))
+            continue
+        expanded.append(target)
+    return expanded
+
+
+def _collect_commands_classes_from_module(module: types.ModuleType) -> List[type]:
+    classes: List[type] = []
+    for _, cls in inspect.getmembers(module, inspect.isclass):
+        if not issubclass(cls, BaseCommands) or cls is BaseCommands:
+            continue
+        if cls.__module__ != module.__name__:
+            continue
+        classes.append(cls)
+    return classes
+
+
+def _collect_classes_by_command_ids(command_ids: Iterable[str]) -> List[type]:
+    classes: List[type] = []
+    for command_id in command_ids:
+        console_name = _extract_console_name(command_id)
+        if not console_name:
+            continue
+        for registry_name, console_cls, _ in REGISTRY.iter_consoles():
+            if registry_name != console_name:
+                continue
+            commands_cls = COMMAND_REGISTRY.get_commands_cls(console_cls)
+            if commands_cls is not None:
+                classes.append(commands_cls)
+    return classes
+
+
+def _resolve_console_bindings(commands_cls) -> List[Tuple[str, Optional[type]]]:
+    bindings: List[Tuple[str, Optional[type]]] = []
+    for console_name, console_cls, _ in REGISTRY.iter_consoles():
+        resolved = COMMAND_REGISTRY.get_commands_cls(console_cls)
+        if resolved is commands_cls:
+            bindings.append((console_name, console_cls))
+    if bindings:
+        return bindings
+    fallback = getattr(commands_cls, "console_name", None)
+    if not fallback:
+        fallback = commands_cls.__name__.lower()
+    return [(fallback, None)]
+
+
+def _extract_console_name(command_id: str) -> Optional[str]:
+    if not isinstance(command_id, str):
+        return None
+    if not command_id.startswith("cmd:"):
+        return None
+    parts = command_id.split(":", 2)
+    if len(parts) != 3:
+        return None
+    return parts[1] or None
+
+
+def _resolve_owner_commands_cls(func) -> Optional[type]:
+    module = inspect.getmodule(func)
+    if module is None:
+        return None
+    qualname = getattr(func, "__qualname__", "")
+    qualname = qualname.split(".<locals>", 1)[0]
+    if "." not in qualname:
+        return None
+    cls_path = qualname.rsplit(".", 1)[0]
+    owner = module
+    for part in cls_path.split("."):
+        owner = getattr(owner, part, None)
+        if owner is None:
+            return None
+    if inspect.isclass(owner) and issubclass(owner, BaseCommands):
+        return owner
+    return None
+
+
+def _resolve_method(commands_cls, fallback):
+    name = getattr(fallback, "__name__", None)
+    if name and hasattr(commands_cls, name):
+        return getattr(commands_cls, name)
+    return fallback
+
+
+def _is_method_selected(method, selected_methods: Set[object]) -> bool:
+    method = _unwrap_callable(method)
+    for selected in selected_methods:
+        if _unwrap_callable(selected) is method:
+            return True
+    return False
+
+
+def _unwrap_callable(value):
+    return getattr(value, "__func__", value)
+
+
+def _read_meta(target) -> Dict[str, Any]:
+    meta = getattr(target, TEST_META_ATTR, None)
+    if isinstance(meta, dict):
+        return dict(meta)
+    return {}
+
+
+def _unique_ordered(values: Iterable[type]) -> List[type]:
+    seen: Set[type] = set()
+    ordered: List[type] = []
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        ordered.append(value)
+    return ordered
+
+
+def _build_command_id(console_name: str, command_name: str):
+    return f"cmd:{console_name}:{command_name}"

python_tty/testing/harness.py

@@ -0,0 +1,295 @@
+import uuid
+from typing import Dict, Iterable, List, Optional
+
+from prompt_toolkit.document import Document
+
+from python_tty.config import ExecutorConfig
+from python_tty.executor import CommandExecutor, Invocation
+from python_tty.executor.execution import ExecutionBinding, ExecutionContext
+from python_tty.runtime.context import use_run_context
+from python_tty.runtime.provider import use_router
+from python_tty.testing.capture import CollectingRouter, build_output_records, capture_executor_events
+from python_tty.testing.discovery import DiscoveredTestCase, DiscoveredTestSuite, discover_tests
+from python_tty.testing.results import TestRunResult
+
+
+class CommandHarness:
+    """Lightweight harness for directly invoking a single command method."""
+
+    def __init__(self, service=None, manager=None, suite: Optional[DiscoveredTestSuite] = None, source: str = "test"):
+        self._service = service
+        self._manager = manager
+        self._suite = suite
+        self._source = source
+
+    def run(
+        self,
+        target,
+        *,
+        command_id: Optional[str] = None,
+        argv: Optional[Iterable[str]] = None,
+        kwargs: Optional[Dict[str, object]] = None,
+        raw_text: Optional[str] = None,
+        validate: bool = True,
+        service=None,
+        manager=None,
+        raise_exceptions: bool = False,
+        run_id: Optional[str] = None,
+    ) -> TestRunResult:
+        """Execute one discovered command and return a structured TestRunResult."""
+
+        case = _resolve_case(target, command_id=command_id, suite=self._suite)
+        resolved_service = self._service if service is None else service
+        resolved_manager = self._manager if manager is None else manager
+        resolved_kwargs = dict(kwargs or {})
+
+        console = _build_console_stub(case, resolved_service, resolved_manager)
+        commands = case.commands_cls(console)
+        console.commands = commands
+        command_def = _resolve_command_def(commands, case)
+
+        resolved_argv = _resolve_argv(commands, command_def, argv=argv, raw_text=raw_text)
+        invocation = _build_invocation(case, resolved_argv, resolved_kwargs, raw_text, self._source, run_id)
+
+        runtime_events: List[object] = []
+        router = CollectingRouter()
+        return_value = None
+        exception = None
+        validator_ran = False
+
+        try:
+            with use_router(router):
+                with use_run_context(
+                    run_id=invocation.run_id,
+                    source=invocation.source,
+                    emitter=lambda event: runtime_events.append(event),
+                    command_id=invocation.command_id,
+                ):
+                    if validate and command_def.validator is not None:
+                        validator_ran = True
+                        _run_validator(commands, command_def, raw_text, resolved_argv)
+                    return_value = _invoke(commands, command_def, resolved_argv, resolved_kwargs)
+        except Exception as exc:  # pragma: no cover - exercised via tests
+            exception = exc
+            if raise_exceptions:
+                raise
+
+        outputs = build_output_records(runtime_events, router.events)
+        return TestRunResult(
+            ok=exception is None,
+            command_id=case.command_id,
+            return_value=return_value,
+            exception=exception,
+            outputs=outputs,
+            runtime_events=list(runtime_events),
+            validator_ran=validator_ran,
+            invocation=invocation,
+            run_id=invocation.run_id,
+        )
+
+
+class InvocationHarness:
+    """Harness for testing command invocation via ExecutionContext/ExecutionBinding."""
+
+    def __init__(
+        self,
+        service=None,
+        manager=None,
+        suite: Optional[DiscoveredTestSuite] = None,
+        source: str = "test",
+        executor: Optional[CommandExecutor] = None,
+    ):
+        self._service = service
+        self._manager = manager
+        self._suite = suite
+        self._source = source
+        self._executor = executor
+
+    def run(
+        self,
+        target,
+        *,
+        command_id: Optional[str] = None,
+        argv: Optional[Iterable[str]] = None,
+        kwargs: Optional[Dict[str, object]] = None,
+        raw_text: Optional[str] = None,
+        through_executor: bool = False,
+        validate: bool = True,
+        service=None,
+        manager=None,
+        executor: Optional[CommandExecutor] = None,
+        raise_exceptions: bool = False,
+        run_id: Optional[str] = None,
+    ) -> TestRunResult:
+        """Run one command through the framework invocation path."""
+
+        case = _resolve_case(target, command_id=command_id, suite=self._suite)
+        resolved_service = self._service if service is None else service
+        resolved_manager = self._manager if manager is None else manager
+        resolved_kwargs = dict(kwargs or {})
+
+        console = _build_console_stub(case, resolved_service, resolved_manager)
+        commands = case.commands_cls(console)
+        console.commands = commands
+        command_def = _resolve_command_def(commands, case)
+        resolved_argv = _resolve_argv(commands, command_def, argv=argv, raw_text=raw_text)
+
+        invocation = _build_invocation(case, resolved_argv, resolved_kwargs, raw_text, self._source, run_id)
+        ctx = ExecutionContext(
+            source=invocation.source,
+            console_name=case.console_name,
+            command_name=case.command_name,
+            command_id=case.command_id,
+            argv=list(resolved_argv),
+            kwargs=dict(resolved_kwargs),
+            raw_cmd=raw_text,
+            run_id=invocation.run_id,
+        )
+        binding = ExecutionBinding(service=resolved_service, manager=resolved_manager, ctx=ctx, console=console)
+
+        runtime_events: List[object] = []
+        router = CollectingRouter()
+        return_value = None
+        exception = None
+        validator_ran = False
+
+        try:
+            with use_router(router):
+                if validate and command_def.validator is not None:
+                    validator_ran = True
+                    _run_validator(commands, command_def, raw_text, resolved_argv)
+
+                if through_executor:
+                    active_executor, owns_executor = _resolve_executor(executor or self._executor)
+                    with capture_executor_events(active_executor, runtime_events):
+                        run_ref = active_executor.submit_threadsafe(invocation, handler=lambda inv: binding.execute(inv))
+                        invocation.run_id = run_ref
+                        return_value = active_executor.wait_result_sync(run_ref)
+                    if owns_executor:
+                        active_executor.shutdown_threadsafe(wait=False)
+                else:
+                    with use_run_context(
+                        run_id=invocation.run_id,
+                        source=invocation.source,
+                        emitter=lambda event: runtime_events.append(event),
+                        command_id=invocation.command_id,
+                    ):
+                        return_value = binding.execute(invocation)
+        except Exception as exc:  # pragma: no cover - exercised via tests
+            exception = exc
+            if raise_exceptions:
+                raise
+
+        outputs = build_output_records(runtime_events, router.events)
+        return TestRunResult(
+            ok=exception is None,
+            command_id=case.command_id,
+            return_value=return_value,
+            exception=exception,
+            outputs=outputs,
+            runtime_events=list(runtime_events),
+            validator_ran=validator_ran,
+            invocation=invocation,
+            run_id=invocation.run_id,
+        )
+
+
+def _resolve_case(target, command_id: Optional[str], suite: Optional[DiscoveredTestSuite]) -> DiscoveredTestCase:
+    if isinstance(target, DiscoveredTestCase):
+        return target
+
+    if isinstance(target, str):
+        if suite is None:
+            raise ValueError("Command id target requires a discovery suite")
+        case = suite.get_case(target)
+        if case is None:
+            raise ValueError(f"Command id not found in suite: {target}")
+        return case
+
+    if suite is not None and command_id is not None:
+        case = suite.get_case(command_id)
+        if case is not None:
+            return case
+
+    command_ids = [command_id] if command_id is not None else None
+    discovered = discover_tests(target, command_ids=command_ids)
+
+    if command_id is not None:
+        case = discovered.get_case(command_id)
+        if case is None:
+            raise ValueError(f"Command id not discovered: {command_id}")
+        return case
+
+    if len(discovered) != 1:
+        raise ValueError(
+            "Target resolves to multiple cases; pass command_id or a DiscoveredTestCase"
+        )
+    return discovered.cases[0]
+
+
+def _build_console_stub(case: DiscoveredTestCase, service, manager):
+    class _ConsoleStub:
+        pass
+
+    stub = _ConsoleStub()
+    stub.service = service
+    stub.manager = manager
+    stub.console_name = case.console_name
+    return stub
+
+
+def _resolve_command_def(commands, case: DiscoveredTestCase):
+    command_def = commands.get_command_def_by_id(case.command_id)
+    if command_def is None:
+        command_def = commands.get_command_def(case.command_name)
+    if command_def is None:
+        raise ValueError(f"Command definition not found for {case.command_id}")
+    return command_def
+
+
+def _resolve_argv(commands, command_def, argv: Optional[Iterable[str]], raw_text: Optional[str]) -> List[str]:
+    if argv is not None:
+        return [str(value) for value in argv]
+    if raw_text is None:
+        return []
+    return list(commands.deserialize_args(command_def, raw_text))
+
+
+def _run_validator(commands, command_def, raw_text: Optional[str], argv: List[str]):
+    text = raw_text if raw_text is not None else " ".join(argv)
+    validator = commands._build_validator(command_def)
+    validator.validate(Document(text=text))
+
+
+def _invoke(commands, command_def, argv: List[str], kwargs: Dict[str, object]):
+    if argv or kwargs:
+        return command_def.func(commands, *argv, **kwargs)
+    return command_def.func(commands)
+
+
+def _build_invocation(
+    case: DiscoveredTestCase,
+    argv: List[str],
+    kwargs: Dict[str, object],
+    raw_text: Optional[str],
+    source: str,
+    run_id: Optional[str],
+):
+    resolved_run_id = run_id or str(uuid.uuid4())
+    return Invocation(
+        run_id=resolved_run_id,
+        source=source,
+        console_id=case.console_name,
+        command_id=case.command_id,
+        command_name=case.command_name,
+        argv=list(argv),
+        kwargs=dict(kwargs),
+        raw_cmd=raw_text,
+    )
+
+
+def _resolve_executor(executor: Optional[CommandExecutor]):
+    if executor is not None:
+        return executor, False
+    config = ExecutorConfig(workers=1, sync_in_threadpool=False, emit_run_events=True)
+    return CommandExecutor(config=config), True

python_tty/testing/results.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class TestRunResult:
+    """Structured test execution result for the testing harnesses."""
+
+    ok: bool
+    command_id: Optional[str]
+    return_value: Any = None
+    exception: Optional[BaseException] = None
+    outputs: List[Dict[str, Any]] = field(default_factory=list)
+    runtime_events: List[object] = field(default_factory=list)
+    validator_ran: bool = False
+    invocation: Optional[object] = None
+    run_id: Optional[str] = None

python_tty-0.2.2.dist-info/METADATA

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: python-tty
+Version: 0.2.2
+Summary: A multi-console TTY framework for complex CLI/TTY apps
+Home-page: https://github.com/ROOKIEMIE/python-tty
+Author: ROOKIEMIE
+License: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: prompt_toolkit>=3.0.32
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: tqdm
+Requires-Dist: uvicorn>=0.27.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Command Line Framework (TTY + Executor + RPC/Web)
+
+[中文](README_zh.md)
+
+## Project Introduction
+
+`python-tty` is a multi-console command framework centered on TTY interaction, with a shared runtime execution model (`Invocation -> Executor -> RuntimeEvent`) that can be reused by RPC/Web frontends.
+
+This repository now includes an official lightweight testing API (`python_tty.testing`) so external projects can test individual command methods without booting the full TTY kernel.
+
+Architecture and module-relationship details were moved out of README and are maintained in [docs/Schema.md](docs/Schema.md).
+
+## Quick Start Example
+
+```python
+from python_tty.console_factory import ConsoleFactory
+
+# service can be any business object that commands access via self.console.service
+service = object()
+
+factory = ConsoleFactory(service=service)
+factory.start()
+```
+
+Typical setup flow:
+1. Define command classes with `@register_command`.
+2. Bind command classes to consoles with `@commands`.
+3. Register console topology with `@root` / `@sub` / `@multi`.
+4. Start `ConsoleFactory`.
+
+Decorator registration example (`commands`, `root`, `sub`, `multi`):
+
+```python
+from prompt_toolkit.styles import Style
+
+from python_tty.commands import BaseCommands
+from python_tty.commands.decorators import commands, register_command
+from python_tty.consoles import MainConsole, SubConsole, multi, root, sub
+
+
+class RootCommands(BaseCommands):
+    @register_command("ping", "health check")
+    def run_ping(self):
+        return "pong"
+
+
+class ModuleCommands(BaseCommands):
+    @register_command("status", "module status")
+    def run_status(self):
+        return "ok"
+
+
+@root
+@commands(RootCommands)
+class RootConsole(MainConsole):
+    console_name = "root"
+    def __init__(self, parent=None, manager=None):
+        super().__init__([("class:prompt", "root> ")], Style.from_dict({"": ""}), parent=parent, manager=manager)
+
+
+@sub("root")
+@commands(ModuleCommands)
+class ModuleConsole(SubConsole):
+    console_name = "module"
+    def __init__(self, parent=None, manager=None):
+        super().__init__([("class:prompt", "module> ")], Style.from_dict({"": ""}), parent=parent, manager=manager)
+
+
+@multi({"root": "tools", "module": "tools"})
+@commands(ModuleCommands)
+class ToolsConsole(SubConsole):
+    # runtime names become root_tools / module_tools
+    def __init__(self, parent=None, manager=None):
+        super().__init__([("class:prompt", "tools> ")], Style.from_dict({"": ""}), parent=parent, manager=manager)
+```
+
+## Detailed Configuration Explanation
+
+Configuration entry: `python_tty/config/config.py`.
+Top-level type: `Config`.
+
+### ConsoleFactoryConfig
+
+- `run_mode`: `"tty"` or `"concurrent"`.
+- `start_executor`: auto start executor during factory startup.
+- `executor_in_thread`: in tty mode, run executor loop in a background thread.
+- `executor_thread_name`: executor thread name.
+- `tty_thread_name`: tty thread name in concurrent mode.
+- `shutdown_executor`: shutdown executor when factory stops.
+
+### ExecutorConfig
+
+- `workers`: worker task count.
+- `retain_last_n`: keep only last N completed runs.
+- `ttl_seconds`: TTL for completed runs.
+- `pop_on_wait`: remove run state after wait result.
+- `exempt_exceptions`: exceptions treated as cancellation.
+- `emit_run_events`: emit state events (`start/success/failure/...`).
+- `event_history_max`: max history events per run.
+- `event_history_ttl`: history TTL per run.
+- `sync_in_threadpool`: run sync handlers in threadpool.
+- `threadpool_workers`: threadpool size.
+- `audit`: nested `AuditConfig`.
+
+### AuditConfig
+
+- `enabled`: enable audit sink.
+- `file_path`: jsonl output file.
+- `stream`: output stream (mutually exclusive with `file_path`).
+- `async_mode`: async sink writer.
+- `flush_interval`: async flush interval.
+- `keep_in_memory`: keep records in memory for tests.
+- `sink`: custom sink instance.
+
+### RPCConfig
+
+- `enabled`: start gRPC server.
+- `bind_host` / `port`: bind address.
+- `max_message_bytes`: gRPC payload limit.
+- `keepalive_time_ms` / `keepalive_timeout_ms` / `keepalive_permit_without_calls`: keepalive controls.
+- `max_concurrent_rpcs`: concurrency limit.
+- `max_streams_per_client`: stream fanout limit.
+- `stream_backpressure_queue_size`: stream queue size.
+- `default_deny`: deny by default when exposure is missing.
+- `require_rpc_exposed`: require `exposure.rpc=True`.
+- `allowed_principals`: principal allowlist.
+- `admin_principals`: admin principal list (allowlist bypass only).
+- `require_audit`: require audit for RPC invoke.
+- `trust_client_principal`: trust request principal directly.
+- `mtls`: nested `MTLSServerConfig`.
+
+### MTLSServerConfig
+
+- `enabled`: enable mTLS.
+- `server_cert_file` / `server_key_file`: server cert/key.
+- `client_ca_file`: CA bundle for client cert verification.
+- `require_client_cert`: enforce client cert.
+- `principal_keys`: auth_context keys for principal extraction.
+
+### WebConfig
+
+- `enabled`: start web server.
+- `bind_host` / `port`: bind address.
+- `root_path`: reverse proxy root path.
+- `cors_allow_origins` / `cors_allow_credentials` / `cors_allow_methods` / `cors_allow_headers`: CORS controls.
+- `meta_enabled`: enable `/meta` endpoint.
+- `meta_cache_control_max_age`: `/meta` cache-control max-age.
+- `ws_snapshot_enabled`: enable snapshot websocket.
+- `ws_snapshot_include_jobs`: include running jobs in snapshots.
+- `ws_max_connections`: websocket connection limit.
+- `ws_heartbeat_interval`: heartbeat interval.
+- `ws_send_queue_size`: websocket send queue size.
+
+## Testing API Usage Examples
+
+Public imports:
+
+```python
+from python_tty.testing import (
+    tty_testable,
+    discover_tests,
+    CommandHarness,
+    InvocationHarness,
+    TestRunResult,
+)
+```
+
+### 1. Mark command class or command method
+
+```python
+from python_tty.commands import BaseCommands
+from python_tty.commands.decorators import register_command
+from python_tty.testing import tty_testable
+
+@tty_testable(component="smoke")
+class UserCommands(BaseCommands):
+    @register_command("ping", "health check")
+    def run_ping(self):
+        return "pong"
+
+class PartialCommands(BaseCommands):
+    @tty_testable(component="critical")
+    @register_command("login", "login flow")
+    def run_login(self, username):
+        return username
+
+    @register_command("debug", "not included unless explicitly selected")
+    def run_debug(self):
+        return "debug"
+```
+
+### 2. Explicit discovery (test-only, no startup auto-scan)
+
+```python
+import my_project.commands as command_module
+from python_tty.testing import discover_tests
+
+suite = discover_tests(command_module)
+all_cases = suite.list_cases()
+
+case = suite.get_case("cmd:usercommands:ping")
+
+# explicit selection still works without decorators
+explicit_suite = discover_tests(
+    command_module,
+    command_ids=["cmd:partialcommands:debug"],
+)
+```
+
+### 3. Run a command with CommandHarness
+
+```python
+from types import SimpleNamespace
+from python_tty.testing import CommandHarness
+
+harness = CommandHarness(service=SimpleNamespace(name="svc"), suite=suite)
+result: TestRunResult = harness.run("cmd:usercommands:ping")
+
+assert result.ok
+assert result.return_value == "pong"
+```
+
+### 4. Toggle validation on/off
+
+```python
+# validator enabled
+result_on = harness.run("cmd:partialcommands:login", argv=[], validate=True)
+assert result_on.ok is False
+assert result_on.validator_ran is True
+
+# validator disabled
+result_off = harness.run("cmd:partialcommands:login", argv=[], validate=False)
+assert result_off.validator_ran is False
+```
+
+### 5. Run through InvocationHarness runtime path
+
+```python
+inv_harness = InvocationHarness(suite=suite)
+
+# direct runtime binding execution
+direct_result = inv_harness.run("cmd:usercommands:ping", through_executor=False)
+
+# executor-backed execution (captures state/runtime events)
+executor_result = inv_harness.run("cmd:usercommands:ping", through_executor=True)
+```
+
+### 6. Inspect TestRunResult
+
+```python
+result = inv_harness.run("cmd:usercommands:ping", through_executor=True)
+
+print(result.ok)
+print(result.return_value)
+print(result.exception)
+print(result.outputs)        # normalized output records
+print(result.runtime_events) # raw RuntimeEvent objects
+print(result.run_id)
+```

{python_tty-0.2.1.dist-info → python_tty-0.2.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-python_tty/__init__.py,sha256=BcJf6R5DOsMPCZCsCMJ_6WUUO8NqJ8Fnbq4WbK7-cL0,521
+python_tty/__init__.py,sha256=XmsJQetBnxtcm_6S4T8_0IuS0k8S8LuyszNd-a5Ge0Y,1842
 python_tty/console_factory.py,sha256=N-JKToa8AnVwZtrq-BksMH0lM6vN_xHVzo8LjsfwFuk,7552
 python_tty/audit/__init__.py,sha256=4VjFUH4KWjO-ZRBOCAZed5IT7zNVTfJOO-HaMTm762E,152
 python_tty/audit/sink.py,sha256=9jyfhe6FEbsde-VIHpqJ4O7OEpoG3glOigE-guhRgJE,4821
@@ -52,12 +52,18 @@ python_tty/session/manager.py,sha256=OrNtz6IGUGmdceiOvf7cUUZ324eE8baAYQ-GVdc689c
 python_tty/session/models.py,sha256=Op4rQFuDb4P0bNGK1J7KOelYlKo2hlAtFz0rxkoxZ7E,476
 python_tty/session/policy.py,sha256=Hm-NYrCG0obLrPCvNdhtdziD4hP2gOYeLYNirFc_sQ0,348
 python_tty/session/store.py,sha256=cYHmja_0g8VcXqXrztuHOjd0v_cG4l7awHfHhRB-qqk,3571
+python_tty/testing/__init__.py,sha256=eeMjfp_s3zZIqU8aB33_8IHVqRXWVpMOENqJ-PCrc7w,362
+python_tty/testing/capture.py,sha256=2_GxARCz-Q27V_v4b6Mk2E08Ilx-5MBJukI4Tig0tHM,2225
+python_tty/testing/decorators.py,sha256=r4qAzf_atfQuijnqjy90J-43mIPrf2XEQ70xxm4q9HA,2048
+python_tty/testing/discovery.py,sha256=mnc9aI6Y0PtohmDpKt3QxpBwWxeiZt7qbBqIjlSqr0M,9000
+python_tty/testing/harness.py,sha256=oZhrPyzBRphlbCRu1ow0iYYEUwbxWjUd5ecJYQFDjh8,11046
+python_tty/testing/results.py,sha256=rZ9gbpPLdotKIeabHSFkJrjhxXv0klaXJLtrFN943Gc,541
 python_tty/utils/__init__.py,sha256=iU2MEk7j-8Sl4fiT4IsoOxQdq7MK70qpaD-87F0As9g,261
 python_tty/utils/table.py,sha256=oTjdhSM3C-NbjdghLysb7c3rgu_B-IbJtcactBGFtN0,10764
 python_tty/utils/tokenize.py,sha256=TnZd1o6LmvqbMWON_RTVk4q664TviIQTFVkNX4CTUBs,1055
-python_tty-0.2.1.dist-info/licenses/LICENSE,sha256=bR2Wj7Il7KNny38LiDGrASo12StUfpReF--OewXD5cw,10349
-python_tty-0.2.1.dist-info/licenses/NOTICE,sha256=UiuDFTGN2ACyjBHAg4AoH6jM9aQRSgXjt2AYNUCI4ck,86
-python_tty-0.2.1.dist-info/METADATA,sha256=xwSQCmLa6Z3AJUq4xsZxOHFct5mgFjfDju_jjTTsVIU,7656
-python_tty-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-python_tty-0.2.1.dist-info/top_level.txt,sha256=ZAEMWTGLkGwrlNN-lOeuJzAHB_xHAiEAecJ7CzS7FnY,11
-python_tty-0.2.1.dist-info/RECORD,,
+python_tty-0.2.2.dist-info/licenses/LICENSE,sha256=bR2Wj7Il7KNny38LiDGrASo12StUfpReF--OewXD5cw,10349
+python_tty-0.2.2.dist-info/licenses/NOTICE,sha256=UiuDFTGN2ACyjBHAg4AoH6jM9aQRSgXjt2AYNUCI4ck,86
+python_tty-0.2.2.dist-info/METADATA,sha256=veeUPHKfI05vBAIArMfkTLNwDnBTPH7qRoZpMAG1vpw,9081
+python_tty-0.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_tty-0.2.2.dist-info/top_level.txt,sha256=ZAEMWTGLkGwrlNN-lOeuJzAHB_xHAiEAecJ7CzS7FnY,11
+python_tty-0.2.2.dist-info/RECORD,,

{python_tty-0.2.1.dist-info → python_tty-0.2.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.10.2)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_tty-0.2.1.dist-info/METADATA

@@ -1,215 +0,0 @@
-Metadata-Version: 2.4
-Name: python-tty
-Version: 0.2.1
-Summary: A multi-console TTY framework for complex CLI/TTY apps
-Home-page: https://github.com/ROOKIEMIE/python-tty
-Author: ROOKIEMIE
-License: Apache-2.0
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-Requires-Dist: fastapi>=0.110.0
-Requires-Dist: grpcio>=1.60.0
-Requires-Dist: prompt_toolkit>=3.0.32
-Requires-Dist: protobuf>=4.25.0
-Requires-Dist: tqdm
-Requires-Dist: uvicorn>=0.27.0
-Dynamic: author
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Command Line Framework (TTY + Executor + RPC/Web)
-
-[中文](README_zh.md)
-
-This project focuses on the TTY core while providing a unified executor, runtime events, RPC/Web frontends, and session management for complex CLI/TTY apps and lightweight service endpoints.
-
-## Concepts
-
-Console layer:
-- `python_tty/consoles/core.py`: `BaseConsole`, `MainConsole`, `SubConsole`
-- `python_tty/consoles/manager.py` and `python_tty/consoles/registry.py` for lifecycle and registration
-
-Commands layer:
-- `python_tty/commands/core.py`: `BaseCommands`, `CommandValidator`
-- `python_tty/commands/registry.py`: `CommandRegistry`, `ArgSpec`
-- `python_tty/commands/general.py`: `GeneralValidator`, `GeneralCompleter`
-- `python_tty/commands/mixins.py`: `CommandMixin` and built-in mixins
-
-Execution and runtime:
-- `python_tty/executor/executor.py`: `CommandExecutor` (unified execution entry)
-- `python_tty/runtime/jobs.py`: `JobStore` (RunState/Invocation/event history)
-- `python_tty/runtime/events.py`: `RuntimeEvent`, `UIEvent`, `UIEventLevel`
-- `python_tty/runtime/router.py`: `proxy_print` and output routing
-
-Session and callbacks:
-- `python_tty/session/manager.py`: `SessionManager` (lifecycle + submit + constraints)
-- `python_tty/session/store.py`: `SessionStore` (in-memory session state)
-- `python_tty/session/callbacks.py`: callback subscriptions (thread-safe cancel)
-
-RPC/Web:
-- `python_tty/frontends/rpc`: gRPC Invoke + event streaming
-- `python_tty/frontends/web`: FastAPI + WS snapshot (Meta)
-
-Table rendering:
-- `python_tty/utils/table.py`: table rendering (auto wrap supported)
-
-TTY / RPC scheduling logic in Executor:
-- TTY: builds `Invocation`, submits via `executor.submit_threadsafe()`, workers emit `RuntimeEvent`.
-- RPC: builds `Invocation`, enforces exposure/allowlist/audit, `StreamEvents` subscribes to event queues.
-
-## Configuration
-
-Config entry is `python_tty/config/config.py`.
-
-ConsoleFactoryConfig:
-- `run_mode`: `"tty"` or `"concurrent"`; decides whether the main thread runs the loop + TTY thread.
-- `start_executor`: auto-start executor on factory start.
-- `executor_in_thread`: start executor in a background thread in TTY mode.
-- `executor_thread_name`: executor loop thread name.
-- `tty_thread_name`: TTY thread name in concurrent mode.
-- `shutdown_executor`: shutdown executor when factory stops.
-
-ExecutorConfig:
-- `workers`: number of workers (execution concurrency).
-- `retain_last_n`: keep last N completed runs in memory.
-- `ttl_seconds`: TTL for completed runs.
-- `pop_on_wait`: drop run state after wait_result.
-- `exempt_exceptions`: treat these as cancellation.
-- `emit_run_events`: emit start/success/failure state events.
-- `event_history_max`: max events per run.
-- `event_history_ttl`: TTL for per-run history.
-- `sync_in_threadpool`: run sync handlers in a thread pool.
-- `threadpool_workers`: max thread pool workers.
-- `audit`: `AuditConfig` for audit sink.
-
-AuditConfig:
-- `enabled`: enable audit.
-- `file_path`: JSONL file output.
-- `stream`: stream output (exclusive with file_path).
-- `async_mode`: async writer mode.
-- `flush_interval`: async flush interval.
-- `keep_in_memory`: keep records in memory (tests).
-- `sink`: custom AuditSink instance.
-
-RPCConfig:
-- `enabled`: start RPC server.
-- `bind_host` / `port`: listen address and port.
-- `max_message_bytes`: max gRPC message size.
-- `keepalive_time_ms` / `keepalive_timeout_ms` / `keepalive_permit_without_calls`: keepalive options.
-- `max_concurrent_rpcs`: max RPC concurrency.
-- `max_streams_per_client`: max concurrent streams per client.
-- `stream_backpressure_queue_size`: per-stream queue limit.
-- `default_deny`: deny when exposure is missing.
-- `require_rpc_exposed`: require `exposure.rpc=True`.
-- `allowed_principals`: principal allowlist.
-- `admin_principals`: admin principals (bypass allowlist only).
-- `require_audit`: RPC requires audit sink.
-- `trust_client_principal`: trust `request.principal` (default False).
-- `mtls`: `MTLSServerConfig`.
-
-MTLSServerConfig:
-- `enabled`: enable mTLS.
-- `server_cert_file` / `server_key_file`: server cert/key.
-- `client_ca_file`: client CA bundle.
-- `require_client_cert`: require client certs.
-- `principal_keys`: auth_context keys for principal extraction.
-
-WebConfig:
-- `enabled`: start Web server.
-- `bind_host` / `port`: listen address and port.
-- `root_path`: reverse-proxy root path.
-- `cors_*`: CORS options.
-- `meta_enabled`: enable `/meta`.
-- `meta_cache_control_max_age`: cache max-age for `/meta`.
-- `ws_snapshot_enabled`: enable `/meta/snapshot` websocket.
-- `ws_snapshot_include_jobs`: include running job summary.
-- `ws_max_connections`: max WS connections.
-- `ws_heartbeat_interval`: WS heartbeat seconds.
-- `ws_send_queue_size`: WS send queue size.
-
-Factory impact:
-- `run_mode="tty"`: TTY runs on main thread; executor can be started in main or background thread.
-- `run_mode="concurrent"`: main thread runs asyncio loop; TTY runs in background thread.
-- `rpc.enabled=True` / `web.enabled=True`: services are attached during factory startup.
-- `start_executor=False`: RPC/Web/Session submit will be unavailable or raise (no executor loop).
-
-## Examples
-
-Quick start (TTY core):
-1. Define your consoles and commands (see examples in `python_tty/consoles/examples` and `python_tty/commands/examples`).
-2. Ensure console modules are imported so decorators can register them: update `DEFAULT_CONSOLE_MODULES` in `python_tty/consoles/loader.py` or call `load_consoles([...])`.
-3. Start the factory:
-```python
-from python_tty.console_factory import ConsoleFactory
-
-factory = ConsoleFactory(service=my_business_core)
-factory.start()
-```
-
-Job/Session basic usage:
-```python
-from python_tty.console_factory import ConsoleFactory
-
-factory = ConsoleFactory(service=my_service)
-factory.start_executor()
-sm = factory.session_manager
-
-sid = sm.open_session(principal="local")
-run_id = sm.submit_command(sid, "cmd:root:help")
-result = await sm.result(run_id)
-```
-
-Mode A: synchronous orchestration (outer awaits inner)
-```python
-async def outer():
-    inner_id = sm.submit_command(sid, "cmd:root:long_task", await_result=True)
-    inner_result = await sm.result(inner_id)
-    return inner_result
-```
-
-Mode B: async orchestration (callbacks)
-```python
-def on_event(evt):
-    pass
-
-def on_done(evt):
-    pass
-
-inner_id = sm.submit_command(sid, "cmd:root:long_task")
-sub_id = sm.register_callback(inner_id, on_event=on_event, on_done=on_done)
-```
-
-Table rendering:
-```python
-from python_tty.utils import Table
-
-header = ["name", "status", "detail"]
-data = [
-    ["job-1", "running", "very long text ..."],
-    ["job-2", "done", "short"],
-]
-
-table = Table(header, data, title="jobs", wrap=True)
-print(table)
-```
-
-Single row (debug):
-```python
-print(table.print_line(["job-3", "queued", "pending"]))
-```
-
-## 展望
-
-待定