python-tty 0.1.0__py3-none-any.whl → 0.1.6__py3-none-any.whl

python_tty/executor/executor.py

@@ -6,9 +6,10 @@ from dataclasses import dataclass
 from typing import Callable, Dict, Optional
 
 from python_tty.config import ExecutorConfig
-from python_tty.ui.events import UIEvent, UIEventLevel
-from python_tty.ui.output import get_output_router
+from python_tty.runtime.events import RuntimeEvent, RuntimeEventKind, UIEventLevel
+from python_tty.runtime.provider import get_router
 from python_tty.executor.models import Invocation, RunState, RunStatus
+from python_tty.exceptions.console_exception import ConsoleExit, SubConsoleExit
 
 
 @dataclass
@@ -29,16 +30,26 @@ class CommandExecutor:
         self._locks: Dict[str, asyncio.Lock] = {}
         self._runs: Dict[str, RunState] = {}
         self._event_queues: Dict[str, asyncio.Queue] = {}
+        self._event_seq: Dict[str, int] = {}
         self._run_futures: Dict[str, asyncio.Future] = {}
         self._retain_last_n = config.retain_last_n
         self._ttl_seconds = config.ttl_seconds
         self._pop_on_wait = config.pop_on_wait
-        self._output_router = get_output_router()
+        self._emit_run_events = config.emit_run_events
+        if config.exempt_exceptions is None:
+            self._exempt_exceptions = (ConsoleExit, SubConsoleExit)
+        else:
+            self._exempt_exceptions = tuple(config.exempt_exceptions)
+        self._audit_sink = self._init_audit_sink(config)
 
     @property
     def runs(self):
         return self._runs
 
+    @property
+    def audit_sink(self):
+        return self._audit_sink
+
     def start(self, loop=None):
         if loop is not None:
             self._loop = loop
@@ -61,6 +72,8 @@ class CommandExecutor:
             handler = self._missing_handler
         run_id = invocation.run_id
         self._runs[run_id] = RunState(run_id=run_id)
+        self._audit_invocation(invocation)
+        self._audit_run_state(self._runs[run_id])
         if self._loop is None:
             try:
                 self._loop = asyncio.get_running_loop()
@@ -124,11 +137,20 @@ class CommandExecutor:
     def publish_event(self, run_id: str, event):
         if getattr(event, "run_id", None) is None:
             event.run_id = run_id
+        if run_id is not None and getattr(event, "seq", None) is None:
+            event.seq = self._next_event_seq(run_id)
         if self._loop is not None and self._loop.is_running():
             queue = self._ensure_event_queue(run_id)
             self._queue_event(queue, event)
-        if self._output_router is not None:
-            self._output_router.emit(event)
+        output_router = get_router()
+        if output_router is not None:
+            output_router.emit(event)
+        if self._audit_sink is not None:
+            output_audit = None
+            if output_router is not None:
+                output_audit = getattr(output_router, "audit_sink", None)
+            if output_audit is None or output_audit is not self._audit_sink:
+                self._audit_sink.record_event(event)
 
     async def shutdown(self, wait: bool = True):
         workers = list(self._workers)
@@ -137,6 +159,7 @@ class CommandExecutor:
             task.cancel()
         if wait and workers:
             await asyncio.gather(*workers, return_exceptions=True)
+        self._close_audit_sink()
 
     def shutdown_threadsafe(self, wait: bool = True, timeout: Optional[float] = None):
         loop = self._loop
@@ -144,6 +167,7 @@ class CommandExecutor:
             for task in list(self._workers):
                 task.cancel()
             self._workers.clear()
+            self._close_audit_sink()
             return None
         future = asyncio.run_coroutine_threadsafe(self.shutdown(wait=wait), loop)
         return future.result(timeout)
@@ -164,6 +188,8 @@ class CommandExecutor:
             running_loop = None
         if running_loop == self._loop:
             return self.submit(invocation, handler=handler)
+        self._audit_invocation(invocation)
+        self._audit_run_state(self._runs[run_id])
 
         async def _enqueue():
             self.start()
@@ -187,25 +213,38 @@ class CommandExecutor:
             return
         run_state.status = RunStatus.RUNNING
         run_state.started_at = time.time()
-        self.publish_event(run_state.run_id, self._build_run_event("start", UIEventLevel.INFO))
+        self._audit_run_state(run_state)
+        self._emit_run_event(run_state.run_id, "start", UIEventLevel.INFO, source=work_item.invocation.source)
         try:
             result = work_item.handler(work_item.invocation)
             if inspect.isawaitable(result):
                 result = await result
             run_state.result = result
             run_state.status = RunStatus.SUCCEEDED
-            self.publish_event(run_state.run_id, self._build_run_event("success", UIEventLevel.SUCCESS))
+            self._emit_run_event(run_state.run_id, "success", UIEventLevel.SUCCESS,
+                                 source=work_item.invocation.source)
             self._resolve_future(run_state, result=result)
+        except self._exempt_exceptions as exc:
+            run_state.error = exc
+            run_state.status = RunStatus.CANCELLED
+            self._emit_run_event(run_state.run_id, "cancelled", UIEventLevel.INFO,
+                                 source=work_item.invocation.source)
+            self._resolve_future(run_state, error=exc)
         except Exception as exc:
             run_state.error = exc
             run_state.status = RunStatus.FAILED
-            self.publish_event(
+            self._emit_run_event(
                 run_state.run_id,
-                self._build_run_event("failure", UIEventLevel.ERROR, payload={"error": str(exc)}),
+                "failure",
+                UIEventLevel.ERROR,
+                payload={"error": str(exc)},
+                source=work_item.invocation.source,
+                force=True,
             )
             self._resolve_future(run_state, error=exc)
         finally:
             run_state.finished_at = time.time()
+            self._audit_run_state(run_state)
             self._cleanup_runs()
 
     def _resolve_future(self, run_state: RunState, result=None, error: Optional[BaseException] = None):
@@ -223,28 +262,52 @@ class CommandExecutor:
             return
         run_state.status = RunStatus.RUNNING
         run_state.started_at = time.time()
-        self.publish_event(run_state.run_id, self._build_run_event("start", UIEventLevel.INFO))
+        self._audit_run_state(run_state)
+        self._emit_run_event(run_state.run_id, "start", UIEventLevel.INFO, source=invocation.source)
         try:
             result = handler(invocation)
             if inspect.isawaitable(result):
                 result = self._run_awaitable_inline(result)
             run_state.result = result
             run_state.status = RunStatus.SUCCEEDED
-            self.publish_event(run_state.run_id, self._build_run_event("success", UIEventLevel.SUCCESS))
+            self._emit_run_event(run_state.run_id, "success", UIEventLevel.SUCCESS,
+                                 source=invocation.source)
+        except self._exempt_exceptions as exc:
+            run_state.error = exc
+            run_state.status = RunStatus.CANCELLED
+            self._emit_run_event(run_state.run_id, "cancelled", UIEventLevel.INFO,
+                                 source=invocation.source)
         except Exception as exc:
             run_state.error = exc
             run_state.status = RunStatus.FAILED
-            self.publish_event(
+            self._emit_run_event(
                 run_state.run_id,
-                self._build_run_event("failure", UIEventLevel.ERROR, payload={"error": str(exc)}),
+                "failure",
+                UIEventLevel.ERROR,
+                payload={"error": str(exc)},
+                source=invocation.source,
+                force=True,
             )
         finally:
             run_state.finished_at = time.time()
+            self._audit_run_state(run_state)
             self._cleanup_runs()
 
     @staticmethod
-    def _build_run_event(event_type: str, level: UIEventLevel, payload=None):
-        return UIEvent(msg=event_type, level=level, event_type=event_type, payload=payload)
+    def _build_run_event(event_type: str, level: UIEventLevel, payload=None, source=None):
+        return RuntimeEvent(
+            kind=RuntimeEventKind.STATE,
+            msg=event_type,
+            level=level,
+            event_type=event_type,
+            payload=payload,
+            source=source,
+        )
+
+    def _emit_run_event(self, run_id: str, event_type: str, level: UIEventLevel,
+                        payload=None, source=None, force: bool = False):
+        if force or self._emit_run_events:
+            self.publish_event(run_id, self._build_run_event(event_type, level, payload=payload, source=source))
 
     @staticmethod
     def _missing_handler(invocation: Invocation):
@@ -275,6 +338,41 @@ class CommandExecutor:
         else:
             self._loop.call_soon_threadsafe(queue.put_nowait, event)
 
+    def _init_audit_sink(self, config: ExecutorConfig):
+        audit_config = getattr(config, "audit", None)
+        if audit_config is None or not audit_config.enabled:
+            return None
+        if audit_config.sink is not None:
+            return audit_config.sink
+        from python_tty.audit import AuditSink
+        return AuditSink(
+            file_path=audit_config.file_path,
+            stream=audit_config.stream,
+            keep_in_memory=audit_config.keep_in_memory,
+            async_mode=audit_config.async_mode,
+            flush_interval=audit_config.flush_interval,
+        )
+
+    def _audit_invocation(self, invocation: Invocation):
+        if self._audit_sink is None:
+            return
+        self._audit_sink.record_invocation(invocation)
+
+    def _audit_run_state(self, run_state: RunState):
+        if self._audit_sink is None:
+            return
+        self._audit_sink.record_run_state(run_state)
+
+    def _close_audit_sink(self):
+        if self._audit_sink is None:
+            return
+        self._audit_sink.close()
+
+    def _next_event_seq(self, run_id: str) -> int:
+        next_seq = self._event_seq.get(run_id, 0) + 1
+        self._event_seq[run_id] = next_seq
+        return next_seq
+
     def _run_awaitable_inline(self, awaitable):
         try:
             running_loop = asyncio.get_running_loop()
@@ -308,6 +406,7 @@ class CommandExecutor:
         if future is not None and not future.done():
             future.cancel()
         self._event_queues.pop(run_id, None)
+        self._event_seq.pop(run_id, None)
         return run_state
 
     def _cleanup_runs(self):
@@ -332,4 +431,4 @@ class CommandExecutor:
                 remove_ids.add(run_id)
         for run_id in remove_ids:
             self.pop_run(run_id)
-
+

python_tty/meta/__init__.py

@@ -0,0 +1,96 @@
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import List, Optional
+
+from python_tty.commands.mixins import DefaultCommands
+from python_tty.commands.registry import ArgSpec, COMMAND_REGISTRY
+from python_tty.consoles.registry import REGISTRY
+
+
+@dataclass
+class _ConsoleEntry:
+    name: str
+    console_cls: type
+    parent: Optional[str]
+
+
+def export_meta(console_registry=REGISTRY, command_registry=COMMAND_REGISTRY,
+                include_default_commands: bool = True):
+    """Export console/command metadata as a dict with a revision hash."""
+    consoles = []
+    entries = _collect_console_entries(console_registry)
+    for entry in entries:
+        command_defs = command_registry.get_command_defs_for_console(entry.console_cls)
+        if not command_defs and include_default_commands:
+            command_defs = command_registry.collect_from_commands_cls(DefaultCommands)
+        commands = _export_commands(entry.name, command_defs)
+        consoles.append({
+            "name": entry.name,
+            "parent": entry.parent,
+            "type": entry.console_cls.__name__,
+            "module": entry.console_cls.__module__,
+            "commands": commands,
+        })
+    consoles.sort(key=lambda item: item["name"])
+    meta = {
+        "version": 1,
+        "consoles": consoles,
+    }
+    tree = None
+    if hasattr(console_registry, "get_console_tree"):
+        tree = console_registry.get_console_tree()
+    if tree is not None:
+        meta["tree"] = tree
+    console_map = None
+    if hasattr(console_registry, "get_console_map"):
+        console_map = console_registry.get_console_map()
+    if console_map is not None:
+        meta["console_map"] = console_map
+    meta["revision"] = _compute_revision(meta)
+    return meta
+
+
+def _collect_console_entries(console_registry):
+    entries: List[_ConsoleEntry] = []
+    iter_consoles = getattr(console_registry, "iter_consoles", None)
+    if not callable(iter_consoles):
+        raise RuntimeError("Console registry must implement iter_consoles()")
+    for name, console_cls, parent in iter_consoles():
+        entries.append(_ConsoleEntry(name=name, console_cls=console_cls, parent=parent))
+    return entries
+
+
+def _export_commands(console_name: str, command_defs):
+    commands = []
+    for command_def in command_defs or []:
+        arg_spec = command_def.arg_spec or ArgSpec.from_signature(command_def.func)
+        commands.append({
+            "id": _build_command_id(console_name, command_def.func_name),
+            "name": command_def.func_name,
+            "aliases": list(command_def.alias or []),
+            "description": command_def.func_description,
+            "argspec": {
+                "min": arg_spec.min_args,
+                "max": arg_spec.max_args,
+                "variadic": arg_spec.variadic,
+            },
+        })
+    commands.sort(key=lambda item: item["id"])
+    return commands
+
+
+def _build_command_id(console_name: str, command_name: str):
+    return f"cmd:{console_name}:{command_name}"
+
+
+def _compute_revision(meta):
+    payload = dict(meta)
+    payload.pop("revision", None)
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+__all__ = [
+    "export_meta",
+]

python_tty/runtime/__init__.py

@@ -0,0 +1,29 @@
+from python_tty.runtime.events import (
+    EventBase,
+    RuntimeEvent,
+    RuntimeEventKind,
+    UIEvent,
+    UIEventLevel,
+    UIEventListener,
+    UIEventSpeaker,
+)
+from python_tty.runtime.provider import get_default_router, get_router, set_default_router, use_router
+from python_tty.runtime.router import BaseRouter, OutputRouter, get_output_router, proxy_print
+
+__all__ = [
+    "UIEvent",
+    "UIEventLevel",
+    "EventBase",
+    "RuntimeEvent",
+    "RuntimeEventKind",
+    "UIEventListener",
+    "UIEventSpeaker",
+    "BaseRouter",
+    "OutputRouter",
+    "get_default_router",
+    "get_router",
+    "get_output_router",
+    "set_default_router",
+    "proxy_print",
+    "use_router",
+]

python_tty/runtime/events.py

@@ -0,0 +1,147 @@
+import enum
+import time
+
+
+class UIEventLevel(enum.Enum):
+    TEXT = -1
+    INFO = 0
+    WARNING = 1
+    ERROR = 2
+    SUCCESS = 3
+    FAILURE = 4
+    DEBUG = 5
+
+    @staticmethod
+    def map_level(code):
+        if code == 0:
+            return UIEventLevel.INFO
+        elif code == 1:
+            return UIEventLevel.WARNING
+        elif code == 2:
+            return UIEventLevel.ERROR
+        elif code == 3:
+            return UIEventLevel.SUCCESS
+        elif code == 4:
+            return UIEventLevel.FAILURE
+        elif code == 5:
+            return UIEventLevel.DEBUG
+
+
+class RuntimeEventKind(enum.Enum):
+    STATE = "state"
+    STDOUT = "stdout"
+    LOG = "log"
+
+
+def _normalize_runtime_kind(kind):
+    if isinstance(kind, RuntimeEventKind):
+        return kind
+    if kind is None:
+        return None
+    try:
+        return RuntimeEventKind(kind)
+    except ValueError:
+        return None
+
+
+class EventBase:
+    """Common event fields shared by RuntimeEvent and UIEvent."""
+    def __init__(self, msg, level=UIEventLevel.TEXT, run_id=None, event_type=None,
+                 payload=None, source=None, ts=None, seq=None):
+        self.msg = msg
+        self.level = level
+        self.run_id = run_id
+        self.event_type = event_type
+        self.payload = payload
+        self.source = source
+        self.ts = time.time() if ts is None else ts
+        self.seq = seq
+
+
+class UIEvent(EventBase):
+    """UI event payload for rendering.
+
+    Fields:
+        msg: Display text or structured data for the event.
+        level: UIEventLevel (or int) that drives rendering style.
+        run_id: Run identifier when the event is tied to a command invocation.
+        event_type: A short event type label (e.g., "start", "success").
+        payload: Structured payload for downstream consumers.
+        source: Event origin (framework should pass "tty"/"rpc" explicitly;
+            external callers via proxy_print default to "custom").
+        ts: Unix timestamp (seconds) when the event was created.
+        seq: Per-run sequence number when emitted by the executor.
+    """
+    def __init__(self, msg, level=UIEventLevel.TEXT, run_id=None, event_type=None,
+                 payload=None, source=None, ts=None, seq=None):
+        super().__init__(
+            msg=msg,
+            level=level,
+            run_id=run_id,
+            event_type=event_type,
+            payload=payload,
+            source=source,
+            ts=ts,
+            seq=seq,
+        )
+
+
+class RuntimeEvent(EventBase):
+    """Runtime event payload for executor/audit pipelines.
+
+    Fields:
+        kind: RuntimeEventKind (state/stdout/log).
+        msg: Text or payload for stdout/log events.
+        level: UIEventLevel or int for log/stdout severity.
+        run_id: Run identifier for correlation.
+        event_type: State label for state events (e.g., "start", "success").
+        payload: Structured payload for downstream consumers.
+        source: Event origin (framework should pass "tty"/"rpc").
+        ts: Unix timestamp (seconds) when the event was created.
+        seq: Per-run sequence number assigned by the executor.
+    """
+    def __init__(self, kind, msg=None, level=UIEventLevel.TEXT, run_id=None, event_type=None,
+                 payload=None, source=None, ts=None, seq=None):
+        self.kind = _normalize_runtime_kind(kind)
+        super().__init__(
+            msg=msg,
+            level=level,
+            run_id=run_id,
+            event_type=event_type,
+            payload=payload,
+            source=source,
+            ts=ts,
+            seq=seq,
+        )
+
+    def to_ui_event(self):
+        return UIEvent(
+            msg=self.msg,
+            level=self.level,
+            run_id=self.run_id,
+            event_type=self.event_type,
+            payload=self.payload,
+            source=self.source,
+            ts=self.ts,
+            seq=self.seq,
+        )
+
+
+class UIEventListener:
+    def handler_event(self, event: UIEvent):
+        pass
+
+
+class UIEventSpeaker:
+    def __init__(self):
+        self._event_listener = []
+
+    def add_event_listener(self, listener: UIEventListener):
+        self._event_listener.append(listener)
+
+    def remove_event_listener(self, listener: UIEventListener):
+        self._event_listener.remove(listener)
+
+    def notify_event_listeners(self, event: UIEvent):
+        for listener in self._event_listener:
+            listener.handler_event(event)

python_tty/runtime/provider.py

@@ -0,0 +1,62 @@
+import contextvars
+import threading
+from contextlib import contextmanager
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from python_tty.runtime.router import BaseRouter
+
+
+class RouterProvider:
+    def __init__(self):
+        self._default_router: Optional["BaseRouter"] = None
+        self._lock = threading.Lock()
+        self._current_router = contextvars.ContextVar("python_tty_current_router", default=None)
+
+    def set_default_router(self, router: Optional["BaseRouter"]):
+        with self._lock:
+            self._default_router = router
+        return router
+
+    def get_default_router(self) -> Optional["BaseRouter"]:
+        with self._lock:
+            return self._default_router
+
+    def get_router(self) -> Optional["BaseRouter"]:
+        current = self._current_router.get()
+        if current is not None:
+            return current
+        return self.get_default_router()
+
+    def set_current_router(self, router: Optional["BaseRouter"]):
+        return self._current_router.set(router)
+
+    def reset_current_router(self, token):
+        self._current_router.reset(token)
+
+    @contextmanager
+    def use_router(self, router: Optional["BaseRouter"]):
+        token = self._current_router.set(router)
+        try:
+            yield router
+        finally:
+            self._current_router.reset(token)
+
+
+_PROVIDER = RouterProvider()
+
+
+def set_default_router(router):
+    return _PROVIDER.set_default_router(router)
+
+
+def get_default_router():
+    return _PROVIDER.get_default_router()
+
+
+def get_router():
+    return _PROVIDER.get_router()
+
+
+def use_router(router):
+    return _PROVIDER.use_router(router)

python_tty/{ui/output.py → runtime/router.py}

@@ -1,10 +1,13 @@
 import threading
+from abc import ABC, abstractmethod
+from typing import Optional
 
 from prompt_toolkit import print_formatted_text
 from prompt_toolkit.formatted_text import FormattedText
 from prompt_toolkit.styles import Style
 
-from python_tty.ui.events import UIEvent, UIEventLevel
+from python_tty.runtime.events import RuntimeEvent, RuntimeEventKind, UIEvent, UIEventLevel
+from python_tty.runtime.provider import get_router
 
 
 MSG_LEVEL_SYMBOL = {
@@ -26,11 +29,18 @@ MSG_LEVEL_SYMBOL_STYLE = {
 }
 
 
-class OutputRouter:
+class BaseRouter(ABC):
+    @abstractmethod
+    def emit(self, event):
+        raise NotImplementedError
+
+
+class OutputRouter(BaseRouter):
     def __init__(self):
         self._lock = threading.Lock()
         self._app = None
         self._output = None
+        self._audit_sink = None
 
     def bind_session(self, session):
         if session is None:
@@ -45,10 +55,34 @@ class OutputRouter:
                 self._app = None
                 self._output = None
 
-    def emit(self, event: UIEvent):
+    def attach_audit_sink(self, audit_sink):
+        with self._lock:
+            self._audit_sink = audit_sink
+
+    def clear_audit_sink(self, audit_sink=None):
+        with self._lock:
+            if audit_sink is None or audit_sink == self._audit_sink:
+                self._audit_sink = None
+
+    @property
+    def audit_sink(self):
+        with self._lock:
+            return self._audit_sink
+
+    def emit(self, event):
+        audit_event = event
+        if isinstance(event, RuntimeEvent):
+            if event.kind in (RuntimeEventKind.STDOUT, RuntimeEventKind.STATE, RuntimeEventKind.LOG):
+                event = event.to_ui_event()
+            else:
+                return
         with self._lock:
             app = self._app
             output = self._output
+            audit_sink = self._audit_sink
+
+        if audit_sink is not None:
+            audit_sink.record_event(audit_event)
 
         def _render():
             text, style = _format_event(event)
@@ -89,14 +123,22 @@ def _format_event(event: UIEvent):
     return formatted_text, style
 
 
-_OUTPUT_ROUTER = OutputRouter()
-
+def get_output_router() -> Optional[BaseRouter]:
+    return get_router()
 
-def get_output_router() -> OutputRouter:
-    return _OUTPUT_ROUTER
 
+def proxy_print(text="", text_type=UIEventLevel.TEXT, source="custom", run_id=None):
+    """Emit a UIEvent for display.
 
-def proxy_print(text="", text_type=UIEventLevel.TEXT):
-    event = UIEvent(msg=text, level=_normalize_level(text_type))
-    get_output_router().emit(event)
-
+    Args:
+        text: Display text or object to render.
+        text_type: UIEventLevel or int.
+        source: Event source. Use "tty"/"rpc" for framework events.
+            External callers can rely on the default "custom".
+        run_id: Optional run identifier to correlate output with an invocation.
+    """
+    event = UIEvent(msg=text, level=_normalize_level(text_type), source=source, run_id=run_id)
+    router = get_router()
+    if router is None:
+        return
+    router.emit(event)