fastled 1.2.33__py3-none-any.whl → 1.4.50__py3-none-any.whl

fastled/open_browser.py

@@ -1,53 +1,55 @@
-import subprocess
+import atexit
+import random
 import sys
 import time
-import webbrowser
+import weakref
 from multiprocessing import Process
 from pathlib import Path
 
-DEFAULT_PORT = 8089  # different than live version.
+from fastled.playwright.playwright_browser import open_with_playwright
+from fastled.server_flask import run_flask_in_thread
+
+# Global reference to keep Playwright browser alive
+_playwright_browser_proxy = None
+
+
+def cleanup_playwright_browser() -> None:
+    """Clean up the Playwright browser on exit."""
+    try:
+        global _playwright_browser_proxy
+        if _playwright_browser_proxy:
+            _playwright_browser_proxy.close()
+            _playwright_browser_proxy = None
+    except Exception:
+        pass
 
+
+# Register cleanup function
+atexit.register(cleanup_playwright_browser)
+
+DEFAULT_PORT = 8089  # different than live version.
 PYTHON_EXE = sys.executable
 
+# Use a weak reference set to track processes without preventing garbage collection
+_WEAK_CLEANUP_SET = weakref.WeakSet()
 
-def open_http_server_subprocess(
-    fastled_js: Path, port: int, open_browser: bool
-) -> None:
-    """Start livereload server in the fastled_js directory and return the process"""
-    import shutil
 
-    try:
-        if shutil.which("live-server") is not None:
-            cmd = [
-                "live-server",
-                f"--port={port}",
-                "--host=localhost",
-                ".",
-            ]
-            if not open_browser:
-                cmd.append("--no-browser")
-            subprocess.run(cmd, shell=True, cwd=fastled_js)
-            return
-
-        cmd = [
-            PYTHON_EXE,
-            "-m",
-            "fastled.open_browser2",
-            str(fastled_js),
-            "--port",
-            str(port),
-        ]
-        # return subprocess.Popen(cmd)  # type ignore
-        # pipe stderr and stdout to null
-        subprocess.run(
-            cmd,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )  # type ignore
-    except KeyboardInterrupt:
-        import _thread
-
-        _thread.interrupt_main()
+def add_cleanup(proc: Process) -> None:
+    """Add a process to the cleanup list using weak references"""
+    _WEAK_CLEANUP_SET.add(proc)
+
+    # Register a cleanup function that checks if the process is still alive
+    def cleanup_if_alive():
+        if proc.is_alive():
+            try:
+                proc.terminate()
+                proc.join(timeout=1.0)
+                if proc.is_alive():
+                    proc.kill()
+            except Exception:
+                pass
+
+    atexit.register(cleanup_if_alive)
 
 
 def is_port_free(port: int) -> bool:
@@ -55,16 +57,22 @@ def is_port_free(port: int) -> bool:
     import httpx
 
     try:
-        response = httpx.get(f"http://localhost:{port}", timeout=1)
-        response.raise_for_status()
-        return False
+        # Try HTTPS first, then fall back to HTTP
+        try:
+            response = httpx.get(f"https://localhost:{port}", timeout=1, verify=False)
+            response.raise_for_status()
+            return False
+        except (httpx.HTTPError, httpx.ConnectError):
+            response = httpx.get(f"http://localhost:{port}", timeout=1)
+            response.raise_for_status()
+            return False
     except (httpx.HTTPError, httpx.ConnectError):
         return True
 
 
 def find_free_port(start_port: int) -> int:
     """Find a free port starting at start_port"""
-    for port in range(start_port, start_port + 100):
+    for port in range(start_port, start_port + 100, 2):
         if is_port_free(port):
             print(f"Found free port: {port}")
             return port
@@ -73,14 +81,21 @@ def find_free_port(start_port: int) -> int:
     raise ValueError("Could not find a free port")
 
 
-def wait_for_server(port: int, timeout: int = 10) -> None:
+def wait_for_server(port: int, timeout: int = 10, enable_https: bool = True) -> None:
     """Wait for the server to start."""
     from httpx import get
 
     future_time = time.time() + timeout
+    protocol = "https" if enable_https else "http"
     while future_time > time.time():
         try:
-            response = get(f"http://localhost:{port}", timeout=1)
+            # Try the specified protocol (HTTPS with SSL verification disabled for self-signed certs)
+            url = f"{protocol}://localhost:{port}"
+            # print(f"Waiting for server to start at {url}")
+            verify = (
+                False if enable_https else True
+            )  # Only disable SSL verification for HTTPS
+            response = get(url, timeout=1, verify=verify)
             if response.status_code == 200:
                 return
         except Exception:
@@ -88,54 +103,85 @@ def wait_for_server(port: int, timeout: int = 10) -> None:
     raise TimeoutError("Could not connect to server")
 
 
-def _background_npm_install_live_server() -> None:
-    import shutil
-    import time
+def spawn_http_server(
+    fastled_js: Path,
+    compile_server_port: int,
+    port: int | None = None,
+    open_browser: bool = True,
+    app: bool = False,
+    enable_https: bool = True,
+) -> Process:
 
-    if shutil.which("npm") is None:
-        return
+    if port is not None and not is_port_free(port):
+        raise ValueError(f"Port {port} was specified but in use")
+    if port is None:
+        offset = random.randint(0, 100)
+        port = find_free_port(DEFAULT_PORT + offset)
 
-    if shutil.which("live-server") is not None:
-        return
+    # Get SSL certificate paths from the fastled assets directory if HTTPS is enabled
+    certfile: Path | None = None
+    keyfile: Path | None = None
 
-    time.sleep(3)
-    subprocess.run(
-        ["npm", "install", "-g", "live-server"],
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-    )
+    if enable_https:
+        import fastled
 
+        assets_dir = Path(fastled.__file__).parent / "assets"
+        certfile = assets_dir / "localhost.pem"
+        keyfile = assets_dir / "localhost-key.pem"
 
-def open_browser_process(
-    fastled_js: Path, port: int | None = None, open_browser: bool = True
-) -> Process:
-    import shutil
-
-    """Start livereload server in the fastled_js directory and return the process"""
-    if port is not None:
-        if not is_port_free(port):
-            raise ValueError(f"Port {port} was specified but in use")
-    else:
-        port = find_free_port(DEFAULT_PORT)
-    out: Process = Process(
-        target=open_http_server_subprocess,
-        args=(fastled_js, port, False),
+    # port: int,
+    # cwd: Path,
+    # compile_server_port: int,
+    # certfile: Path | None = None,
+    # keyfile: Path | None = None,
+
+    proc = Process(
+        target=run_flask_in_thread,
+        args=(port, fastled_js, compile_server_port, certfile, keyfile),
         daemon=True,
     )
-    out.start()
-    wait_for_server(port)
-    if open_browser:
-        print(f"Opening browser to http://localhost:{port}")
-        webbrowser.open(url=f"http://localhost:{port}", new=1, autoraise=True)
+    add_cleanup(proc)
+    proc.start()
+
+    # Add to cleanup set with weak reference
+    add_cleanup(proc)
 
-    # start a deamon thread to install live-server
-    if shutil.which("live-server") is None:
-        import threading
+    wait_for_server(port, enable_https=enable_https)
+    if open_browser:
+        protocol = "https" if enable_https else "http"
+        url = f"{protocol}://localhost:{port}"
+        should_use_playwright = app
+
+        if should_use_playwright:
+            if app:
+                # For --app mode, try to install browsers if needed
+                from fastled.playwright.playwright_browser import (
+                    install_playwright_browsers,
+                )
+
+                install_playwright_browsers()
+
+            print(f"Opening FastLED sketch in Playwright browser: {url}")
+            print(
+                "Auto-resize enabled: Browser window will automatically adjust to content size"
+            )
+            print(
+                "🔧 C++ DevTools Support extension will be loaded for DWARF debugging"
+            )
+            global _playwright_browser_proxy
+            _playwright_browser_proxy = open_with_playwright(
+                url, enable_extensions=True
+            )
+        else:
+            print(f"Opening browser to {url}")
+            import webbrowser
 
-        t = threading.Thread(target=_background_npm_install_live_server)
-        t.daemon = True
-        t.start()
-    return out
+            webbrowser.open(
+                url=url,
+                new=1,
+                autoraise=True,
+            )
+    return proc
 
 
 if __name__ == "__main__":
@@ -145,9 +191,7 @@ if __name__ == "__main__":
         description="Open a browser to the fastled_js directory"
     )
     parser.add_argument(
-        "fastled_js",
-        type=Path,
-        help="Path to the fastled_js directory",
+        "fastled_js", type=Path, help="Path to the fastled_js directory"
     )
     parser.add_argument(
         "--port",
@@ -157,5 +201,5 @@ if __name__ == "__main__":
     )
     args = parser.parse_args()
 
-    proc = open_browser_process(args.fastled_js, args.port, open_browser=True)
+    proc = spawn_http_server(args.fastled_js, args.port, open_browser=True)
     proc.join()

fastled/parse_args.py

@@ -3,19 +3,66 @@ import os
 import sys
 from pathlib import Path
 
-from fastled import __version__
+from fastled.args import Args
 from fastled.project_init import project_init
 from fastled.select_sketch_directory import select_sketch_directory
 from fastled.settings import DEFAULT_URL, IMAGE_NAME
 from fastled.sketch import (
+    find_sketch_by_partial_name,
     find_sketch_directories,
     looks_like_fastled_repo,
     looks_like_sketch_directory,
 )
 
 
-def parse_args() -> argparse.Namespace:
+def _find_fastled_repo(start: Path) -> Path | None:
+    """Find the FastLED repo directory by searching upwards from the current directory."""
+    current = start
+    while current != current.parent:
+        if looks_like_fastled_repo(current):
+            return current
+        current = current.parent
+    return None
+
+
+_DEFAULT_HELP_TEXT = """
+FastLED WASM Compiler - Useful options:
+  <directory>           Directory containing the FastLED sketch to compile
+  --init [example]      Initialize one of the top tier WASM examples
+  --web [url]           Use web compiler
+  --server              Run the compiler server
+  --no-platformio       Bypass PlatformIO constraints using local Docker compilation
+  --quick               Build in quick mode (default)
+  --profile             Enable profiling the C++ build system
+  --update              Update the docker image for the wasm compiler
+  --background-update   Update the docker image in the background after compilation
+  --purge               Remove all FastLED containers and images
+  --emsdk-headers <path> Export EMSDK headers ZIP to specified path
+  --version             Show version information
+  --help                Show detailed help
+Examples:
+  fastled (will auto detect the sketch directory and prompt you)
+  fastled my_sketch
+  fastled my_sketch --web (compiles using the web compiler only)
+  fastled my_sketch --background-update (compiles and updates docker image in background)
+  fastled --init Blink (initializes a new sketch directory with the Blink example)
+  fastled --server (runs the compiler server in the current directory)
+
+For those using Docker:
+  --debug               Build with debug symbols for dev-tools debugging
+
+  --release             Build in optimized release mode
+"""
+
+
+def parse_args() -> Args:
     """Parse command-line arguments."""
+    from fastled import __version__
+
+    # Check if no arguments were provided
+    if len(sys.argv) == 1:
+        print(_DEFAULT_HELP_TEXT)
+
     parser = argparse.ArgumentParser(description=f"FastLED WASM Compiler {__version__}")
     parser.add_argument("--version", action="version", version=f"{__version__}")
     parser.add_argument(
@@ -36,6 +83,12 @@ def parse_args() -> argparse.Namespace:
         action="store_true",
         help="Just compile, skip opening the browser and watching for changes.",
     )
+    parser.add_argument(
+        "--ram-disk-size",
+        type=str,
+        default="1gb",
+        help="Size of the RAM disk for compilation (e.g., '1gb', '512mb')",
+    )
     parser.add_argument(
         "--web",
         "-w",
@@ -54,7 +107,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--profile",
         action="store_true",
-        help="Enable profiling for web compilation",
+        help="Enable profiling of the C++ build system used for wasm compilation.",
     )
     parser.add_argument(
         "--force-compile",
@@ -64,20 +117,36 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--no-auto-updates",
         action="store_true",
-        help="Disable automatic updates of the wasm compiler image when using docker.",
+        help="Disable automatic updates of the wasm compiler image when using docker. (Default: False)",
+    )
+    parser.add_argument(
+        "--no-platformio",
+        action="store_true",
+        help="Bypass PlatformIO constraints by using local Docker compilation with custom build environment",
+    )
+    parser.add_argument(
+        "--app",
+        action="store_true",
+        help="Use Playwright app-like browser experience (will download browsers if needed)",
     )
     parser.add_argument(
+        "-u",
         "--update",
         "--upgrade",
         action="store_true",
         help="Update the wasm compiler (if necessary) before running",
     )
+    parser.add_argument(
+        "--background-update",
+        action="store_true",
+        help="Update the docker image in the background after compilation (user doesn't have to wait)",
+    )
     parser.add_argument(
         "--localhost",
         "--local",
         "-l",
         action="store_true",
-        help="Use localhost for web compilation from an instance of fastled --server, creating it if necessary",
+        help="(Default): Use localhost for web compilation from an instance of fastled --server, creating it if necessary",
     )
     parser.add_argument(
         "--build",
@@ -97,12 +166,41 @@ def parse_args() -> argparse.Namespace:
         help="Remove all FastLED containers and images",
     )
 
+    parser.add_argument(
+        "--clear",
+        action="store_true",
+        help="Remove all FastLED containers and images",
+    )
+
+    parser.add_argument(
+        "--install",
+        action="store_true",
+        help="Install FastLED development environment with VSCode configuration and Auto Debug extension",
+    )
+
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Run in dry-run mode (simulate actions without making changes)",
+    )
+
+    parser.add_argument(
+        "--no-interactive",
+        action="store_true",
+        help="Run in non-interactive mode (fail instead of prompting for input)",
+    )
+    parser.add_argument(
+        "--emsdk-headers",
+        type=str,
+        default=None,
+        help="Export EMSDK headers ZIP to specified path",
+    )
+
     build_mode = parser.add_mutually_exclusive_group()
     build_mode.add_argument("--debug", action="store_true", help="Build in debug mode")
     build_mode.add_argument(
         "--quick",
         action="store_true",
-        default=True,
         help="Build in quick mode (default)",
     )
     build_mode.add_argument(
@@ -113,6 +211,62 @@ def parse_args() -> argparse.Namespace:
 
     args = parser.parse_args()
 
+    # Handle --emsdk-headers early before other processing
+    if args.emsdk_headers:
+        from fastled.header_dump import dump_emsdk_headers
+
+        out_path = args.emsdk_headers
+        dump_emsdk_headers(out_path)
+        sys.exit(0)
+
+    # Auto-enable app mode if debug is used and Playwright cache exists
+    if args.debug and not args.app:
+        playwright_dir = Path.home() / ".fastled" / "playwright"
+        if playwright_dir.exists() and any(playwright_dir.iterdir()):
+            from fastled.emoji_util import EMO
+
+            print(
+                f"{EMO('⚠️', 'WARNING:')} Debug mode detected with Playwright installed - automatically enabling app mode"
+            )
+            args.app = True
+        elif not args.no_interactive:
+            # Prompt user to install Playwright only if not in no-interactive mode
+            answer = (
+                input("Would you like to install the FastLED debugger? [y/n] ")
+                .strip()
+                .lower()
+            )
+            if answer in ["y", "yes"]:
+                print(
+                    "📦 To install Playwright, run: pip install playwright && python -m playwright install"
+                )
+                print("Then run your command again with --app flag")
+                sys.exit(0)
+
+    # TODO: propagate the library.
+    # from fastled.docker_manager import force_remove_previous
+
+    # if force_remove_previous():
+    #     print("Removing previous containers...")
+    # do itinfront he camer
+    # nonw invoke via the
+    #
+    # Work in progress.
+    # set_ramdisk_size("50mb")
+
+    # if args.ram_disk_size != "0":
+    #     from fastled.docker_manager import set_ramdisk_size
+    #     from fastled.util import banner_string
+
+    #     msg = banner_string(f"Setting tmpfs size to {args.ram_disk_size}")
+    #     print(msg)
+    #     set_ramdisk_size(args.ram_disk_size)
+
+    # Handle --install early before other processing
+    if args.install:
+        # Don't process other arguments when --install is used
+        return Args.from_namespace(args)
+
     if args.purge:
         from fastled.docker_manager import DockerManager
 
@@ -131,8 +285,38 @@ def parse_args() -> argparse.Namespace:
         print(f"Use 'fastled {args.directory}' to compile the project.")
         sys.exit(0)
 
-    if args.build:
-        return args
+    cwd: Path = Path(os.getcwd())
+    fastled_dir: Path | None = _find_fastled_repo(cwd)
+    is_fastled_dir: bool = fastled_dir is not None
+
+    if not (args.debug or args.quick or args.release):
+        if is_fastled_dir:
+            # if --quick, --debug, --release are not specified then default to --debug
+            args.quick = True
+            print("Defaulting to --quick mode in fastled repo")
+        else:
+            args.quick = True
+            print("Defaulting to --quick mode")
+
+    if args.build or args.interactive:
+        if args.directory is not None:
+            args.directory = str(Path(args.directory).absolute())
+        if not is_fastled_dir:
+            print("This command must be run from within the FastLED repo. Exiting...")
+            sys.exit(1)
+        if cwd != fastled_dir and fastled_dir is not None:
+            print(f"Switching to FastLED repo at {fastled_dir}")
+            os.chdir(fastled_dir)
+        if args.directory is None:
+            args.directory = str(Path("examples/wasm").absolute())
+        if args.interactive:
+            if not args.build:
+                print("Adding --build flag when using --interactive")
+                args.build = True
+        user_wants_update = args.update
+        if user_wants_update is not True:
+            args.no_auto_updates = True
+        return Args.from_namespace(args)
 
     if not args.update:
         if args.no_auto_updates:
@@ -165,6 +349,12 @@ def parse_args() -> argparse.Namespace:
         if cwd_is_fastled and not args.web and not args.server:
             print("Forcing --local mode because we are in the FastLED repo")
             args.localhost = True
+        if args.no_platformio:
+            print(
+                "--no-platformio mode enabled: forcing local Docker compilation to bypass PlatformIO constraints"
+            )
+            args.localhost = True
+            args.web = None  # Clear web flag to ensure local compilation
         if args.localhost:
             args.web = "localhost"
         if args.interactive and not args.server:
@@ -179,7 +369,7 @@ def parse_args() -> argparse.Namespace:
                 print("Searching for sketch directories...")
                 sketch_directories = find_sketch_directories(maybe_sketch_dir)
                 selected_dir = select_sketch_directory(
-                    sketch_directories, cwd_is_fastled
+                    sketch_directories, cwd_is_fastled, is_followup=True
                 )
                 if selected_dir:
                     print(f"Using sketch directory: {selected_dir}")
@@ -189,10 +379,24 @@ def parse_args() -> argparse.Namespace:
                         "\nYou either need to specify a sketch directory or run in --server mode."
                     )
                     sys.exit(1)
-        elif args.directory is not None and os.path.isfile(args.directory):
-            dir_path = Path(args.directory).parent
-            if looks_like_sketch_directory(dir_path):
-                print(f"Using sketch directory: {dir_path}")
-                args.directory = str(dir_path)
+        elif args.directory is not None:
+            # Check if directory is a file path
+            if os.path.isfile(args.directory):
+                dir_path = Path(args.directory).parent
+                if looks_like_sketch_directory(dir_path):
+                    print(f"Using sketch directory: {dir_path}")
+                    args.directory = str(dir_path)
+            # Check if directory exists as a path
+            elif not os.path.exists(args.directory):
+                # Directory doesn't exist - try partial name matching
+                try:
+                    matched_dir = find_sketch_by_partial_name(args.directory)
+                    print(
+                        f"Matched '{args.directory}' to sketch directory: {matched_dir}"
+                    )
+                    args.directory = str(matched_dir)
+                except ValueError as e:
+                    print(f"Error: {e}")
+                    sys.exit(1)
 
-    return args
+    return Args.from_namespace(args)