py2max 0.2.1__py3-none-any.whl

py2max/server/__init__.py

@@ -0,0 +1,54 @@
+"""Interactive server and REPL for py2max.
+
+This subpackage provides WebSocket-based server and REPL functionality
+for real-time interactive editing of Max patches.
+
+Modules:
+- websocket: WebSocket server for bidirectional communication
+- repl: Interactive REPL using ptpython
+- client: Remote REPL client
+- inline: Inline REPL with background server
+- rpc: Remote procedure call server for REPL
+"""
+
+from .websocket import (
+    InteractivePatcherServer,
+    InteractiveWebSocketHandler,
+    get_patcher_state_json,
+    serve_interactive,
+)
+from .repl import AutoSyncWrapper, ReplCommands, start_repl, start_repl_with_refresh
+from .client import ReplClient, start_repl_client
+from .inline import (
+    BackgroundServerREPL,
+    restore_console_logging,
+    setup_file_logging,
+    start_background_server_repl,
+    start_inline_repl,
+)
+from .rpc import ReplServer, start_repl_server
+
+__all__ = [
+    # WebSocket server
+    "InteractivePatcherServer",
+    "InteractiveWebSocketHandler",
+    "get_patcher_state_json",
+    "serve_interactive",
+    # REPL
+    "AutoSyncWrapper",
+    "ReplCommands",
+    "start_repl",
+    "start_repl_with_refresh",
+    # Client
+    "ReplClient",
+    "start_repl_client",
+    # Inline
+    "BackgroundServerREPL",
+    "start_inline_repl",
+    "start_background_server_repl",
+    "setup_file_logging",
+    "restore_console_logging",
+    # RPC
+    "ReplServer",
+    "start_repl_server",
+]

py2max/server/client.py

@@ -0,0 +1,295 @@
+"""Remote REPL client for py2max.
+
+This module provides a client that connects to a running py2max server
+and provides an interactive REPL in a separate terminal, keeping server
+logs separate from the REPL interface.
+
+Usage:
+    # Terminal 1: Start server
+    $ py2max serve my-patch.maxpat
+
+    # Terminal 2: Connect REPL
+    $ py2max repl localhost:9000
+
+Architecture:
+    - Server runs HTTP (8000), WebSocket (8001), and REPL (9000)
+    - REPL client connects to port 9000 via WebSocket
+    - Commands sent to server for execution
+    - Results returned and displayed in client
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Dict, Optional
+
+try:
+    from websockets.asyncio.client import ClientConnection, connect
+except ImportError:
+    raise ImportError(
+        "websockets package required for REPL client. "
+        "Install with: pip install websockets"
+    )
+
+
+class ReplClient:
+    """Remote REPL client that connects to py2max server."""
+
+    def __init__(self, host: str = "localhost", port: int = 9000):
+        self.host = host
+        self.port = port
+        self.ws: Optional[ClientConnection] = None
+        self.namespace: Dict[str, Any] = {}
+        self.connected = False
+
+    async def connect(self):
+        """Connect to remote REPL server."""
+        uri = f"ws://{self.host}:{self.port}"
+        print(f"Connecting to py2max server at {uri}...")
+
+        try:
+            self.ws = await connect(uri)
+            self.connected = True
+
+            # Get initial state from server
+            await self.ws.send(json.dumps({"type": "init"}))
+            response = await self.ws.recv()
+            data = json.loads(response)
+
+            if data.get("type") == "init_response":
+                info = data.get("info", {})
+                print()
+                print("=" * 70)
+                print("py2max Remote REPL")
+                print("=" * 70)
+                print()
+                print(f"Connected to: {self.host}:{self.port}")
+                print(f"Patcher: {info.get('patcher_path', 'Unknown')}")
+                print(f"Objects: {info.get('num_objects', 0)} boxes")
+                print(f"Connections: {info.get('num_connections', 0)} lines")
+                print()
+                print("Available commands:")
+                print("  save()         - Save patcher")
+                print("  info()         - Show patcher info")
+                print("  layout(type)   - Change layout")
+                print("  optimize()     - Optimize layout")
+                print("  clear()        - Clear all objects")
+                print("  help_obj(name) - Show Max object help")
+                print()
+                print("Use Ctrl+D to exit")
+                print("=" * 70)
+                print()
+
+        except Exception as e:
+            print(f"Error connecting to server: {e}", file=sys.stderr)
+            print()
+            print("Make sure the server is running with:")
+            print("  py2max serve <patch.maxpat>")
+            print()
+            raise
+
+    async def disconnect(self):
+        """Disconnect from server."""
+        if self.ws:
+            await self.ws.close()
+            self.connected = False
+
+    async def execute(self, code: str) -> Any:
+        """Execute code on remote server.
+
+        Args:
+            code: Python code to execute
+
+        Returns:
+            Result from server
+        """
+        if not self.connected or self.ws is None:
+            print("Not connected to server", file=sys.stderr)
+            return None
+
+        try:
+            # Send code to server
+            await self.ws.send(
+                json.dumps({"type": "eval", "code": code, "mode": "exec"})
+            )
+
+            # Get response
+            response = await self.ws.recv()
+            data = json.loads(response)
+
+            if data.get("type") == "error":
+                error = data.get("error", "Unknown error")
+                traceback = data.get("traceback", "")
+                print(f"Error: {error}", file=sys.stderr)
+                if traceback:
+                    print(traceback, file=sys.stderr)
+                return None
+
+            elif data.get("type") == "result":
+                result = data.get("result")
+                display = data.get("display")
+
+                # Print display if available
+                if display:
+                    print(display)
+
+                return result
+
+            else:
+                print(f"Unknown response type: {data.get('type')}", file=sys.stderr)
+                return None
+
+        except Exception as e:
+            print(f"Error executing code: {e}", file=sys.stderr)
+            return None
+
+    async def run_repl(self):
+        """Run interactive REPL using ptpython."""
+
+        # Create proxy functions that execute remotely
+        async def remote_eval(code: str) -> Any:
+            """Evaluate code on remote server."""
+            return await self.execute(code)
+
+        # Build namespace with remote execution (reserved for future use)
+        _namespace = {  # noqa: F841
+            "__name__": "__main__",
+            "__doc__": None,
+            "_remote_eval": remote_eval,
+        }
+
+        def configure(repl):
+            """Configure ptpython."""
+            repl.show_signature = True
+            repl.enable_auto_suggest = True
+            repl.show_docstring = True
+            repl.complete_while_typing = False  # Disable - can't complete remote
+            repl.enable_history_search = True
+            repl.vi_mode = False
+            repl.enable_syntax_highlighting = True
+            repl.highlight_matching_parenthesis = True
+            repl.enable_mouse_support = True
+
+        # Custom input handler that sends to server
+        # Note: This is a simplified version - full implementation would need
+        # to intercept ptpython's execution and route through websocket
+        print("Starting REPL...")
+        print()
+
+        try:
+            # Use ptpython with syntax highlighting and history
+            await self._ptpython_repl()
+
+        except (EOFError, KeyboardInterrupt):
+            print()
+            print("Exiting REPL...")
+
+    async def _ptpython_repl(self) -> None:
+        """Full-featured ptpython REPL with remote execution.
+
+        Uses ptpython for editing features (syntax highlighting, completion)
+        but executes code on the remote server.
+        """
+        # Create a remote execution namespace (reserved for future use)
+        _namespace = {  # noqa: F841
+            "_client": self,
+            "_execute": self.execute,
+        }
+
+        # Custom evaluator that executes remotely (reserved for future use)
+        class RemoteEvaluator:
+            def __init__(self, client: "ReplClient") -> None:
+                self.client = client
+
+            async def __call__(self, code: str) -> Optional[str]:
+                """Execute code on remote server."""
+                if not code.strip():
+                    return None
+
+                # Execute on server
+                result = await self.client.execute(code)
+                return result
+
+        _evaluator = RemoteEvaluator(self)  # noqa: F841
+
+        # Configure ptpython
+        def configure(repl: Any) -> None:
+            """Configure ptpython REPL."""
+            # Enable auto-completion
+            repl.enable_auto_suggest = True
+            repl.complete_while_typing = False  # Disable since completion is local
+
+            # Enable syntax highlighting
+            repl.enable_syntax_highlighting = True
+
+            # Show signature
+            repl.show_signature = True
+
+            # Vi mode (optional - can be toggled with F4)
+            repl.vi_mode = False
+
+        # Run ptpython REPL with remote execution
+        # Note: We use a custom event loop integration
+        while True:
+            try:
+                # Get input using ptpython
+                from prompt_toolkit import PromptSession
+                from prompt_toolkit.lexers import PygmentsLexer
+                from pygments.lexers.python import PythonLexer  # type: ignore[import-untyped]
+
+                session: PromptSession[str] = PromptSession(
+                    message="py2max[remote]>>> ",
+                    lexer=PygmentsLexer(PythonLexer),
+                    enable_history_search=True,
+                    complete_while_typing=False,
+                )
+
+                code = await session.prompt_async()
+
+                if not code.strip():
+                    continue
+
+                # Handle exit
+                if code.strip() in ("exit", "exit()", "quit", "quit()"):
+                    break
+
+                # Execute on server
+                result = await self.execute(code)
+
+                # Display result if not None
+                if result is not None:
+                    print(result)
+
+            except EOFError:
+                break
+            except KeyboardInterrupt:
+                print()
+                continue
+
+
+async def start_repl_client(host: str = "localhost", port: int = 9000):
+    """Start remote REPL client.
+
+    Args:
+        host: Server hostname
+        port: REPL server port (default: 9000)
+
+    Example:
+        >>> await start_repl_client("localhost", 9000)
+    """
+    client = ReplClient(host, port)
+
+    try:
+        await client.connect()
+        await client.run_repl()
+    except Exception as e:
+        print(f"REPL client error: {e}", file=sys.stderr)
+        return 1
+    finally:
+        await client.disconnect()
+
+    return 0
+
+
+__all__ = ["ReplClient", "start_repl_client"]

py2max/server/inline.py

@@ -0,0 +1,312 @@
+"""Inline REPL with background server and log redirection.
+
+This module provides an inline REPL mode where the server runs in the
+background with logs redirected to a file, allowing a clean single-terminal
+experience.
+
+Usage:
+    $ py2max serve my-patch.maxpat --repl --log-file server.log
+
+Features:
+    - Single terminal (no need for separate client terminal)
+    - Server logs redirected to file
+    - Clean REPL interface
+    - Can tail log file in separate terminal if needed
+
+Architecture:
+    ┌─────────────────────────────────────┐
+    │ Single Terminal                     │
+    │                                     │
+    │ ┌─────────────────────────────────┐ │
+    │ │ Server (background thread)      │ │
+    │ │ - HTTP: 8000                    │ │
+    │ │ - WebSocket: 8001               │ │
+    │ │ - Logs → server.log             │ │
+    │ └─────────────────────────────────┘ │
+    │                                     │
+    │ ┌─────────────────────────────────┐ │
+    │ │ REPL (foreground, ptpython)     │ │
+    │ │ py2max[demo.maxpat]>>>          │ │
+    │ │ [clean, no logs]                │ │
+    │ └─────────────────────────────────┘ │
+    └─────────────────────────────────────┘
+
+    Optional: $ tail -f server.log (in another terminal)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+import threading
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..core import Patcher
+    from .websocket import InteractivePatcherServer
+
+
+def setup_file_logging(log_file: Path, level: int = logging.INFO) -> logging.Handler:
+    """Setup file logging for server.
+
+    Args:
+        log_file: Path to log file
+        level: Logging level (default: INFO)
+
+    Returns:
+        File handler that was added
+    """
+    # Get root logger
+    root_logger = logging.getLogger()
+
+    # Remove existing handlers (console output)
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    # Add file handler
+    file_handler = logging.FileHandler(log_file, mode="a")
+    file_handler.setLevel(level)
+
+    # Format with timestamp
+    formatter = logging.Formatter(
+        "[%(asctime)s] - %(levelname)s - %(name)s - %(message)s",
+        datefmt="%H:%M:%S",
+    )
+    file_handler.setFormatter(formatter)
+
+    root_logger.addHandler(file_handler)
+    root_logger.setLevel(level)
+
+    return file_handler
+
+
+def restore_console_logging():
+    """Restore console logging (remove file handler)."""
+    root_logger = logging.getLogger()
+
+    # Remove file handlers
+    for handler in root_logger.handlers[:]:
+        if isinstance(handler, logging.FileHandler):
+            handler.close()
+            root_logger.removeHandler(handler)
+
+    # Add console handler back
+    console_handler = logging.StreamHandler(sys.stderr)
+    console_handler.setLevel(logging.INFO)
+    formatter = logging.Formatter(
+        "\x1b[97;20m%(asctime)s\x1b[0m - "
+        "\x1b[38;20m%(levelname)s\x1b[0m - "
+        "\x1b[97;20m%(name)s\x1b[0m - "
+        "\x1b[38;20m%(message)s\x1b[0m",
+        datefmt="%H:%M:%S",
+    )
+    console_handler.setFormatter(formatter)
+    root_logger.addHandler(console_handler)
+
+
+async def start_inline_repl(
+    patcher: "Patcher",
+    server: "InteractivePatcherServer",
+    log_file: Optional[Path] = None,
+) -> None:
+    """Start inline REPL with server running in background.
+
+    Args:
+        patcher: Patcher instance
+        server: Server instance (already started)
+        log_file: Optional log file path (default: outputs/py2max_server.log)
+
+    Example:
+        >>> p = Patcher('demo.maxpat')
+        >>> server = await p.serve(port=8000)
+        >>> await start_inline_repl(p, server, Path('server.log'))
+    """
+    from .repl import start_repl
+
+    # Setup log file
+    if log_file is None:
+        log_file = Path("outputs/py2max_server.log")
+
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Redirect logging to file
+    file_handler = setup_file_logging(log_file)
+
+    # Print info about logging
+    print()
+    print("=" * 70)
+    print("py2max Inline REPL (Single Terminal Mode)")
+    print("=" * 70)
+    print()
+    print(f"Server logs redirected to: {log_file}")
+    print(f"To monitor logs: tail -f {log_file}")
+    print()
+    print("Starting REPL...")
+    print()
+
+    try:
+        # Start REPL in foreground
+        await start_repl(patcher, server)
+
+    finally:
+        # Restore console logging
+        file_handler.close()
+        restore_console_logging()
+
+
+class BackgroundServerREPL:
+    """REPL with server running in background thread.
+
+    This class manages the server lifecycle in a background thread
+    while the REPL runs in the foreground.
+    """
+
+    def __init__(
+        self,
+        patcher: "Patcher",
+        port: int = 8000,
+        log_file: Optional[Path] = None,
+    ):
+        self.patcher = patcher
+        self.port = port
+        self.log_file = log_file or Path("outputs/py2max_server.log")
+        self.server: Optional[InteractivePatcherServer] = None
+        self.server_thread: Optional[threading.Thread] = None
+        self.loop: Optional[asyncio.AbstractEventLoop] = None
+        self.ready_event = threading.Event()
+
+    def notify_update_sync(self):
+        """Synchronously notify server (running in background thread) of updates.
+
+        This method is called from the REPL (main thread) and schedules
+        the notify_update coroutine in the server's event loop.
+        """
+        if self.loop and self.server:
+            # Schedule coroutine in the server's event loop
+            future = asyncio.run_coroutine_threadsafe(
+                self.server.notify_update(), self.loop
+            )
+            # Wait for completion (with timeout to avoid hanging)
+            try:
+                future.result(timeout=2.0)
+            except Exception as e:
+                print(f"Warning: Failed to notify server: {e}", file=sys.stderr)
+
+    def _run_server(self):
+        """Run server in background thread."""
+        # Create new event loop for this thread
+        self.loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(self.loop)
+
+        async def run():
+            # Start server
+            self.server = await self.patcher.serve(
+                port=self.port,
+                auto_open=True,
+            )
+
+            # Signal that server is ready
+            self.ready_event.set()
+
+            # Keep running
+            try:
+                while True:
+                    await asyncio.sleep(1)
+            except asyncio.CancelledError:
+                # Shutdown requested
+                await self.server.stop()
+
+        # Run server
+        try:
+            self.loop.run_until_complete(run())
+        except Exception as e:
+            print(f"Server error: {e}", file=sys.stderr)
+        finally:
+            self.loop.close()
+
+    async def start(self):
+        """Start server in background and REPL in foreground."""
+        # Setup logging
+        self.log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = setup_file_logging(self.log_file)
+
+        # Start server in background thread
+        self.server_thread = threading.Thread(
+            target=self._run_server,
+            daemon=True,
+        )
+        self.server_thread.start()
+
+        # Wait for server to be ready
+        self.ready_event.wait(timeout=10)
+
+        if not self.ready_event.is_set():
+            raise RuntimeError("Server failed to start")
+
+        print()
+        print("=" * 70)
+        print("py2max Inline REPL (Single Terminal Mode)")
+        print("=" * 70)
+        print()
+        print("Server running:")
+        print(f"  HTTP: http://localhost:{self.port}")
+        print(f"  WebSocket: ws://localhost:{self.port + 1}")
+        print()
+        print(f"Server logs: {self.log_file}")
+        print(f"To monitor: tail -f {self.log_file}")
+        print()
+        print("Starting REPL...")
+        print()
+
+        try:
+            # Start REPL in foreground with refresh() function
+            from .repl import start_repl_with_refresh
+
+            assert self.server is not None, "Server failed to start"
+            await start_repl_with_refresh(
+                self.patcher, self.server, self.notify_update_sync
+            )
+
+        finally:
+            # Cleanup
+            self.stop()
+            file_handler.close()
+            restore_console_logging()
+
+    def stop(self):
+        """Stop background server."""
+        if self.loop and self.server:
+            # Cancel the server loop
+            for task in asyncio.all_tasks(self.loop):
+                task.cancel()
+
+
+async def start_background_server_repl(
+    patcher: "Patcher",
+    port: int = 8000,
+    log_file: Optional[Path] = None,
+) -> None:
+    """Start REPL with server in background (single terminal mode).
+
+    Args:
+        patcher: Patcher instance
+        port: Server port (default: 8000)
+        log_file: Log file path (default: outputs/py2max_server.log)
+
+    Example:
+        >>> p = Patcher('demo.maxpat')
+        >>> await start_background_server_repl(p, port=8000)
+    """
+    repl = BackgroundServerREPL(patcher, port, log_file)
+    await repl.start()
+
+
+__all__ = [
+    "start_inline_repl",
+    "start_background_server_repl",
+    "BackgroundServerREPL",
+    "setup_file_logging",
+    "restore_console_logging",
+]