python-tty 0.2.0__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/executor/__init__.py

@@ -1,5 +1,8 @@
-from python_tty.executor.executor import CommandExecutor
-from python_tty.executor.models import Invocation, RunState, RunStatus
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from python_tty.executor.executor import CommandExecutor
+    from python_tty.executor.models import Invocation, RunState, RunStatus
 
 __all__ = [
     "CommandExecutor",
@@ -7,4 +10,20 @@ __all__ = [
     "RunState",
     "RunStatus",
 ]
+
+
+def __getattr__(name):
+    if name == "CommandExecutor":
+        from python_tty.executor.executor import CommandExecutor
+        return CommandExecutor
+    if name == "Invocation":
+        from python_tty.executor.models import Invocation
+        return Invocation
+    if name == "RunState":
+        from python_tty.executor.models import RunState
+        return RunState
+    if name == "RunStatus":
+        from python_tty.executor.models import RunStatus
+        return RunStatus
+    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}"