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

python_tty/__init__.py

@@ -1,15 +1,25 @@
 from python_tty.config import Config
 from python_tty.console_factory import ConsoleFactory
-from python_tty.ui.events import UIEvent, UIEventLevel, UIEventListener, UIEventSpeaker
-from python_tty.ui.output import proxy_print
+from python_tty.runtime.events import (
+    EventBase,
+    RuntimeEvent,
+    RuntimeEventKind,
+    UIEvent,
+    UIEventLevel,
+    UIEventListener,
+    UIEventSpeaker,
+)
+from python_tty.runtime.router import proxy_print
 
 __all__ = [
     "UIEvent",
     "UIEventLevel",
+    "EventBase",
+    "RuntimeEvent",
+    "RuntimeEventKind",
     "UIEventListener",
     "UIEventSpeaker",
     "ConsoleFactory",
     "Config",
     "proxy_print",
 ]
-

python_tty/audit/__init__.py

@@ -0,0 +1,7 @@
+from python_tty.audit.sink import AuditSink
+from python_tty.audit.ui_logger import ConsoleHandler
+
+__all__ = [
+    "AuditSink",
+    "ConsoleHandler",
+]

python_tty/audit/sink.py

@@ -0,0 +1,141 @@
+import json
+import queue
+import threading
+import time
+from dataclasses import asdict, is_dataclass
+from enum import Enum
+from typing import Any, Iterable, Optional, TextIO
+
+
+class AuditSink:
+    def __init__(self, file_path: Optional[str] = None, stream: Optional[TextIO] = None,
+                 keep_in_memory: bool = False, async_mode: bool = False,
+                 flush_interval: float = 1.0):
+        if file_path is not None and stream is not None:
+            raise ValueError("Only one of file_path or stream can be set")
+        self._path = file_path
+        self._stream = stream
+        self._owns_stream = False
+        if self._stream is None and self._path is not None:
+            self._stream = open(self._path, "a", encoding="utf-8")
+            self._owns_stream = True
+        self._buffer = [] if keep_in_memory else None
+        self._async_mode = async_mode and self._stream is not None
+        self._flush_interval = max(0.1, float(flush_interval))
+        self._lock = threading.Lock()
+        self._queue = None
+        self._stop_event = threading.Event()
+        self._worker = None
+        if self._async_mode:
+            self._queue = queue.Queue()
+            self._worker = threading.Thread(
+                target=self._worker_loop,
+                name="AuditSinkWriter",
+                daemon=True,
+            )
+            self._worker.start()
+
+    @property
+    def buffer(self):
+        return self._buffer
+
+    def record_invocation(self, invocation):
+        self._write("invocation", invocation)
+
+    def record_run_state(self, run_state):
+        self._write("run_state", run_state)
+
+    def record_event(self, event):
+        self._write("event", event)
+
+    def record_bundle(self, invocation=None, run_state=None, events: Optional[Iterable[Any]] = None):
+        if invocation is not None:
+            self.record_invocation(invocation)
+        if run_state is not None:
+            self.record_run_state(run_state)
+        if events:
+            for event in events:
+                self.record_event(event)
+
+    def close(self):
+        if self._async_mode and self._worker is not None:
+            self._stop_event.set()
+            self._worker.join()
+        if self._owns_stream and self._stream is not None:
+            self._stream.close()
+        self._stream = None
+        self._owns_stream = False
+
+    def _write(self, record_type: str, data):
+        record = {
+            "type": record_type,
+            "ts": time.time(),
+            "data": self._materialize(data),
+        }
+        if self._buffer is not None:
+            self._buffer.append(record)
+        if self._stream is None:
+            return
+        if self._async_mode and self._queue is not None:
+            self._queue.put(record)
+            return
+        self._write_record(record)
+
+    def _write_record(self, record):
+        payload = json.dumps(record, default=self._json_default)
+        with self._lock:
+            if self._stream is None:
+                return
+            self._stream.write(payload + "\n")
+            self._stream.flush()
+
+    def _write_batch(self, records):
+        payload = "\n".join(json.dumps(record, default=self._json_default) for record in records) + "\n"
+        with self._lock:
+            if self._stream is None:
+                return
+            self._stream.write(payload)
+            self._stream.flush()
+
+    def _worker_loop(self):
+        pending = []
+        while not self._stop_event.is_set() or (self._queue is not None and not self._queue.empty()):
+            try:
+                record = self._queue.get(timeout=self._flush_interval)
+                pending.append(record)
+                while True:
+                    try:
+                        pending.append(self._queue.get_nowait())
+                    except queue.Empty:
+                        break
+            except queue.Empty:
+                pass
+            if pending:
+                self._write_batch(pending)
+                pending.clear()
+
+    @staticmethod
+    def _materialize(value):
+        if is_dataclass(value):
+            return asdict(value)
+        if isinstance(value, Enum):
+            return value.value
+        if isinstance(value, BaseException):
+            return str(value)
+        if hasattr(value, "__dict__"):
+            return dict(value.__dict__)
+        return value
+
+    @staticmethod
+    def _json_default(value):
+        if is_dataclass(value):
+            return asdict(value)
+        if isinstance(value, Enum):
+            return value.value
+        if isinstance(value, BaseException):
+            return str(value)
+        if isinstance(value, bytes):
+            return value.decode("utf-8", errors="replace")
+        if hasattr(value, "__dict__"):
+            return dict(value.__dict__)
+        return str(value)

python_tty/{utils → audit}/ui_logger.py

@@ -1,7 +1,7 @@
 import logging
 
-from python_tty.ui.events import UIEventLevel
-from python_tty.ui.output import proxy_print
+from python_tty.runtime.events import UIEventLevel
+from python_tty.runtime.router import proxy_print
 
 
 class ConsoleHandler(logging.Handler):
@@ -11,7 +11,6 @@ class ConsoleHandler(logging.Handler):
     def emit(self, record):
         try:
             log = self.format(record)
-            proxy_print(log, UIEventLevel.DEBUG)
+            proxy_print(log, UIEventLevel.DEBUG, source="tty")
         except Exception:
             self.handleError(record)
-

python_tty/commands/examples/root_commands.py

@@ -2,8 +2,8 @@ from python_tty.commands import BaseCommands
 from python_tty.commands.decorators import register_command
 from python_tty.commands.general import GeneralValidator
 from python_tty.commands.mixins import HelpMixin, QuitMixin
-from python_tty.ui.events import UIEventLevel
-from python_tty.ui.output import proxy_print
+from python_tty.runtime.events import UIEventLevel
+from python_tty.runtime.router import proxy_print
 
 
 class RootCommands(BaseCommands, HelpMixin, QuitMixin):
@@ -30,4 +30,3 @@ class RootCommands(BaseCommands, HelpMixin, QuitMixin):
 
 if __name__ == '__main__':
     pass
-

python_tty/commands/mixins.py

@@ -1,6 +1,6 @@
 import inspect
 
-from python_tty.ui.output import proxy_print
+from python_tty.runtime.router import proxy_print
 from python_tty.commands import BaseCommands
 from python_tty.commands.decorators import register_command
 from python_tty.commands.general import GeneralValidator
@@ -34,7 +34,7 @@ class HelpMixin(CommandMixin):
         for cls in self.__class__.mro():
             if cls is CommandMixin:
                 continue
-            if issubclass(cls, CommandMixin):
+            if issubclass(cls, CommandMixin) and not issubclass(cls, BaseCommands):
                 base_commands_funcs.extend([member[1] for member in inspect.getmembers(cls, inspect.isfunction)])
         for name, func in self.command_funcs.items():
             row = [name, func.info.func_description]
@@ -43,10 +43,9 @@ class HelpMixin(CommandMixin):
             else:
                 custom_funcs.append(row)
         if base_funcs:
-            proxy_print(Table(header, base_funcs, "Core Commands"))
+            proxy_print(Table(header, base_funcs, "Core Commands"), source="tty")
         if custom_funcs:
-            proxy_print(Table(header, custom_funcs, "Custom Commands"))
+            proxy_print(Table(header, custom_funcs, "Custom Commands"), source="tty")
 
 class DefaultCommands(BaseCommands, HelpMixin, QuitMixin):
     pass
-

python_tty/config/__init__.py

@@ -1,7 +1,14 @@
-from python_tty.config.config import Config, ConsoleFactoryConfig, ConsoleManagerConfig, ExecutorConfig
+from python_tty.config.config import (
+    AuditConfig,
+    Config,
+    ConsoleFactoryConfig,
+    ConsoleManagerConfig,
+    ExecutorConfig,
+)
 
 __all__ = [
     "Config",
+    "AuditConfig",
     "ConsoleFactoryConfig",
     "ConsoleManagerConfig",
     "ExecutorConfig",

python_tty/config/config.py

@@ -1,35 +1,92 @@
 from dataclasses import dataclass, field
-from typing import Optional, TYPE_CHECKING
+from typing import Optional, TYPE_CHECKING, TextIO, Tuple, Type
 
 if TYPE_CHECKING:
-    from python_tty.ui.output import OutputRouter
+    from python_tty.audit.sink import AuditSink
+    from python_tty.runtime.router import OutputRouter
+
+
+@dataclass
+class AuditConfig:
+    """Audit sink configuration.
+
+    Attributes:
+        enabled: Toggle audit recording.
+        file_path: File path to append JSONL audit records.
+        stream: File-like stream to write audit records.
+        async_mode: Enable async background writer when stream is set.
+        flush_interval: Flush interval (seconds) for async writer.
+        keep_in_memory: Keep records in memory buffer for testing.
+        sink: Custom AuditSink instance to use instead of file/stream.
+    """
+    enabled: bool = False
+    file_path: Optional[str] = None
+    stream: Optional[TextIO] = None
+    async_mode: bool = False
+    flush_interval: float = 1.0
+    keep_in_memory: bool = False
+    sink: Optional["AuditSink"] = None
 
 
 @dataclass
 class ExecutorConfig:
+    """Executor runtime configuration.
+
+    Attributes:
+        workers: Number of worker tasks to consume invocations.
+        retain_last_n: Keep only the last N completed runs in memory.
+        ttl_seconds: Time-to-live for completed runs.
+        pop_on_wait: Drop run state after wait_result completion.
+        exempt_exceptions: Exceptions treated as cancellations.
+        emit_run_events: Emit start/success/failure RuntimeEvent state.
+        audit: Audit sink configuration.
+    """
     workers: int = 1
     retain_last_n: Optional[int] = None
     ttl_seconds: Optional[float] = None
     pop_on_wait: bool = False
+    exempt_exceptions: Optional[Tuple[Type[BaseException], ...]] = None
+    emit_run_events: bool = False
+    audit: AuditConfig = field(default_factory=AuditConfig)
 
 
 @dataclass
 class ConsoleManagerConfig:
+    """Console manager configuration.
+
+    Attributes:
+        use_patch_stdout: Patch stdout for prompt_toolkit rendering.
+        output_router: Output router instance for UI events.
+    """
     use_patch_stdout: bool = True
     output_router: Optional["OutputRouter"] = None
 
 
 @dataclass
 class ConsoleFactoryConfig:
+    """Console factory bootstrap configuration.
+
+    Attributes:
+        run_mode: "tty" for single-thread TTY mode, "concurrent" for
+            main-thread asyncio loop with TTY in a background thread.
+        start_executor: Auto-start the executor when the factory starts.
+        executor_in_thread: Start executor in a background thread (tty mode).
+        executor_thread_name: Thread name for the executor loop thread.
+        tty_thread_name: Thread name for the TTY loop (concurrent mode).
+        shutdown_executor: Shutdown executor when the factory stops.
+    """
+    run_mode: str = "tty"
     start_executor: bool = True
     executor_in_thread: bool = True
     executor_thread_name: str = "ExecutorLoop"
+    tty_thread_name: str = "TTYLoop"
     shutdown_executor: bool = True
 
 
 @dataclass
 class Config:
+    """Top-level configuration for python-tty."""
     console_manager: ConsoleManagerConfig = field(default_factory=ConsoleManagerConfig)
     executor: ExecutorConfig = field(default_factory=ExecutorConfig)
     console_factory: ConsoleFactoryConfig = field(default_factory=ConsoleFactoryConfig)
-
+

python_tty/console_factory.py

@@ -6,6 +6,8 @@ from python_tty.consoles.loader import load_consoles
 from python_tty.consoles.manager import ConsoleManager
 from python_tty.consoles.registry import REGISTRY
 from python_tty.executor import CommandExecutor
+from python_tty.runtime.provider import set_default_router
+from python_tty.runtime.router import OutputRouter
 
 
 class ConsoleFactory:
@@ -27,6 +29,9 @@ class ConsoleFactory:
         if config is None:
             config = Config()
         self.config = config
+        if self.config.console_manager.output_router is None:
+            self.config.console_manager.output_router = OutputRouter()
+        set_default_router(self.config.console_manager.output_router)
         self.executor = CommandExecutor(config=config.executor)
         self._executor_loop = None
         self._executor_thread = None
@@ -36,13 +41,50 @@ class ConsoleFactory:
             on_shutdown=self.shutdown,
             config=config.console_manager,
         )
+        self._attach_audit_sink()
         load_consoles()
         REGISTRY.register_all(self.manager)
 
     def start(self):
         """Start the console loop with the registered root console."""
-        self._start_executor_if_needed()
-        self.manager.run()
+        run_mode = self.config.console_factory.run_mode
+        if run_mode == "tty":
+            self._start_executor_if_needed()
+            self.manager.run()
+            return
+        if run_mode == "concurrent":
+            self.start_concurrent()
+            return
+        raise ValueError(f"Unsupported run_mode: {run_mode}")
+
+    def start_concurrent(self):
+        """Start executor on the main loop and run TTY in a background thread."""
+        loop = asyncio.new_event_loop()
+        self._executor_loop = loop
+        asyncio.set_event_loop(loop)
+        if self.config.console_factory.start_executor:
+            self.start_executor(loop=loop)
+
+        def _run_tty():
+            try:
+                self.manager.run()
+            finally:
+                if loop.is_running():
+                    loop.call_soon_threadsafe(loop.stop)
+
+        tty_thread = threading.Thread(
+            target=_run_tty,
+            name=self.config.console_factory.tty_thread_name,
+            daemon=True,
+        )
+        tty_thread.start()
+        loop.run_forever()
+        pending = asyncio.all_tasks(loop)
+        if pending:
+            for task in pending:
+                task.cancel()
+            loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+        loop.close()
 
     def start_executor(self, loop=None):
         """Start executor workers on the provided asyncio loop."""
@@ -97,4 +139,11 @@ class ConsoleFactory:
             daemon=True,
         )
         self._executor_thread.start()
-
+
+    def _attach_audit_sink(self):
+        audit_sink = getattr(self.executor, "audit_sink", None)
+        if audit_sink is None:
+            return
+        default_router = self.config.console_manager.output_router
+        if default_router is not None:
+            default_router.attach_audit_sink(audit_sink)

python_tty/consoles/core.py

@@ -3,10 +3,10 @@ from abc import ABC
 
 from prompt_toolkit import PromptSession
 
-from python_tty.ui.events import UIEventListener, UIEventSpeaker
+from python_tty.runtime.events import UIEventListener, UIEventSpeaker
 from python_tty.executor import Invocation
 from python_tty.exceptions.console_exception import ConsoleExit, ConsoleInitException, SubConsoleExit
-from python_tty.ui.output import proxy_print
+from python_tty.runtime.router import proxy_print
 from python_tty.utils import split_cmd
 
 
@@ -47,7 +47,7 @@ class BaseConsole(ABC, UIEventListener):
 
     def handler_event(self, event):
         if BaseConsole.forward_console is not None and BaseConsole.forward_console == self:
-            proxy_print(event.msg, event.level)
+            proxy_print(event.msg, event.level, source=event.source or "tty")
 
     def run(self, invocation: Invocation):
         command_def = self.commands.get_command_def_by_id(invocation.command_id)
@@ -70,7 +70,8 @@ class BaseConsole(ABC, UIEventListener):
             if executor is None:
                 self.run(invocation)
                 return
-            executor.submit_threadsafe(invocation, handler=self.run)
+            run_id = executor.submit_threadsafe(invocation, handler=self.run)
+            executor.wait_result_sync(run_id)
         except ValueError:
             return
 
@@ -137,4 +138,3 @@ class SubConsole(BaseConsole):
         if parent is None:
             raise ConsoleInitException("SubConsole parent is None")
         super().__init__(console_message, console_style, parent=parent, manager=manager)
-

python_tty/consoles/manager.py

@@ -2,8 +2,9 @@ from prompt_toolkit.patch_stdout import patch_stdout
 
 from python_tty.config import ConsoleManagerConfig
 from python_tty.exceptions.console_exception import ConsoleExit, ConsoleInitException, SubConsoleExit
-from python_tty.ui.events import UIEventLevel, UIEventSpeaker
-from python_tty.ui.output import get_output_router, proxy_print
+from python_tty.runtime.events import UIEventLevel, UIEventSpeaker
+from python_tty.runtime.provider import get_router
+from python_tty.runtime.router import proxy_print
 
 
 class ConsoleEntry:
@@ -23,7 +24,7 @@ class ConsoleManager:
         self._on_shutdown = on_shutdown
         self._shutdown_called = False
         self._config = config if config is not None else ConsoleManagerConfig()
-        self._output_router = self._config.output_router or get_output_router()
+        self._output_router = self._config.output_router or get_router()
         self._use_patch_stdout = self._config.use_patch_stdout
         self._warn_service_if_needed(service)
 
@@ -64,7 +65,7 @@ class ConsoleManager:
         if service is not None and not isinstance(service, UIEventSpeaker):
             msg = f"The Service core[{service.__class__}] doesn't extend the [UIEventSpeaker],"\
                   " which may affect the output of the Service core on the UI!"
-            proxy_print(msg, UIEventLevel.WARNING)
+            proxy_print(msg, UIEventLevel.WARNING, source="tty")
 
     @property
     def current(self):
@@ -143,4 +144,3 @@ class ConsoleManager:
             self._output_router.clear_session()
             return
         self._output_router.bind_session(current.session)
-

python_tty/consoles/registry.py

@@ -58,6 +58,39 @@ class ConsoleRegistry:
                 raise ConsoleInitException(f"Console name duplicate [{resolved_name}]")
             self._subs[resolved_name] = SubConsoleEntry(console_cls, parent_name, resolved_name)
 
+    def get_root(self):
+        if self._root_cls is None:
+            return None, None
+        root_name = self._root_name or _get_console_name(self._root_cls)
+        return self._root_cls, root_name
+
+    def get_subs(self):
+        return dict(self._subs)
+
+    def iter_consoles(self):
+        root_cls, root_name = self.get_root()
+        if root_cls is not None and root_name is not None:
+            yield root_name, root_cls, None
+        for name, entry in self._subs.items():
+            yield name, entry.console_cls, entry.parent_name
+
+    def get_console_tree(self):
+        _, root_name = self.get_root()
+        if not root_name:
+            return None
+        return _build_console_tree(root_name, self._subs)
+
+    def get_console_map(self):
+        console_map = {}
+        for name, console_cls, parent in self.iter_consoles():
+            console_map[name] = {
+                "name": name,
+                "parent": parent,
+                "type": console_cls.__name__,
+                "module": console_cls.__module__,
+            }
+        return console_map
+
     def register_all(self, manager):
         if self._root_cls is None:
             raise ConsoleInitException("Root console not set")