fastled 1.1.37__py2.py3-none-any.whl → 1.1.39__py2.py3-none-any.whl

fastled/__init__.py

@@ -3,11 +3,13 @@
 # context
 from contextlib import contextmanager
 from pathlib import Path
+from typing import Generator
 
 from .compile_server import CompileServer
-from .types import WebCompileResult
+from .live_client import LiveClient
+from .types import BuildMode, CompileResult, CompileServerError
 
-__version__ = "1.1.37"
+__version__ = "1.1.39"
 
 
 class Api:
@@ -29,17 +31,42 @@ class Api:
 
     @staticmethod
     def web_compile(
-        directory: Path | str, host: str | CompileServer | None = None
-    ) -> WebCompileResult:
+        directory: Path | str,
+        host: str | CompileServer | None = None,
+        build_mode: BuildMode = BuildMode.QUICK,
+        profile: bool = False,  # When true then profile information will be enabled and included in the zip.
+    ) -> CompileResult:
         from fastled.web_compile import web_compile
 
         if isinstance(host, CompileServer):
             host = host.url()
         if isinstance(directory, str):
             directory = Path(directory)
-        out: WebCompileResult = web_compile(directory, host)
+        out: CompileResult = web_compile(
+            directory, host, build_mode=build_mode, profile=profile
+        )
         return out
 
+    @staticmethod
+    def live_client(
+        sketch_directory: Path,
+        host: str | CompileServer | None = None,
+        auto_start=True,
+        open_web_browser=True,
+        keep_running=True,
+        build_mode=BuildMode.QUICK,
+        profile=False,
+    ) -> LiveClient:
+        return LiveClient(
+            sketch_directory=sketch_directory,
+            host=host,
+            auto_start=auto_start,
+            open_web_browser=open_web_browser,
+            keep_running=keep_running,
+            build_mode=build_mode,
+            profile=profile,
+        )
+
     @staticmethod
     def spawn_server(
         sketch_directory: Path | None = None,
@@ -47,7 +74,7 @@ class Api:
         auto_updates=None,
         auto_start=True,
         container_name: str | None = None,
-    ):
+    ) -> CompileServer:
         from fastled.compile_server import CompileServer
 
         out = CompileServer(
@@ -67,7 +94,7 @@ class Api:
         auto_updates=None,
         auto_start=True,
         container_name: str | None = None,
-    ):
+    ) -> Generator[CompileServer, None, None]:
         server = Api.spawn_server(
             sketch_directory=sketch_directory,
             interactive=interactive,
@@ -92,3 +119,13 @@ class Test:
             host = host.url()
 
         return test_examples(examples=examples, host=host)
+
+
+__all__ = [
+    "Api",
+    "Test",
+    "CompileServer",
+    "CompileResult",
+    "CompileServerError",
+    "BuildMode",
+]

fastled/client_server.py

@@ -1,11 +1,11 @@
 import argparse
 import shutil
 import tempfile
+import threading
 import time
 from multiprocessing import Process
 from pathlib import Path
 
-from fastled.build_mode import BuildMode, get_build_mode
 from fastled.compile_server import CompileServer
 from fastled.docker_manager import DockerManager
 from fastled.filewatcher import FileWatcherProcess
@@ -13,9 +13,7 @@ from fastled.keyboard import SpaceBarWatcher
 from fastled.open_browser import open_browser_process
 from fastled.settings import DEFAULT_URL
 from fastled.sketch import looks_like_sketch_directory
-
-# CompiledResult
-from fastled.types import CompiledResult
+from fastled.types import BuildMode, CompileResult, CompileServerError
 from fastled.web_compile import (
     SERVER_PORT,
     ConnectionResult,
@@ -30,7 +28,7 @@ def _run_web_compiler(
     build_mode: BuildMode,
     profile: bool,
     last_hash_value: str | None,
-) -> CompiledResult:
+) -> CompileResult:
     input_dir = Path(directory)
     output_dir = input_dir / "fastled_js"
     start = time.time()
@@ -42,7 +40,7 @@ def _run_web_compiler(
         print("\nWeb compilation failed:")
         print(f"Time taken: {diff:.2f} seconds")
         print(web_result.stdout)
-        return CompiledResult(success=False, fastled_js="", hash_value=None)
+        return web_result
 
     def print_results() -> None:
         hash_value = (
@@ -58,9 +56,7 @@ def _run_web_compiler(
     if last_hash_value is not None and last_hash_value == web_result.hash_value:
         print("\nSkipping redeploy: No significant changes found.")
         print_results()
-        return CompiledResult(
-            success=True, fastled_js=str(output_dir), hash_value=web_result.hash_value
-        )
+        return web_result
 
     # Extract zip contents to fastled_js directory
     output_dir.mkdir(exist_ok=True)
@@ -78,18 +74,20 @@ def _run_web_compiler(
 
     print(web_result.stdout)
     print_results()
-    return CompiledResult(
-        success=True, fastled_js=str(output_dir), hash_value=web_result.hash_value
-    )
+    return web_result
 
 
-def _try_start_server_or_get_url(args: argparse.Namespace) -> str | CompileServer:
-    auto_update = args.auto_update
-    is_local_host = "localhost" in args.web or "127.0.0.1" in args.web or args.localhost
+def _try_start_server_or_get_url(
+    auto_update: bool, args_web: str | bool, localhost: bool
+) -> tuple[str, CompileServer | None]:
+    is_local_host = localhost or (
+        isinstance(args_web, str)
+        and ("localhost" in args_web or "127.0.0.1" in args_web)
+    )
     # test to see if there is already a local host server
     local_host_needs_server = False
     if is_local_host:
-        addr = "localhost" if args.localhost else args.web
+        addr = "localhost" if localhost or not isinstance(args_web, str) else args_web
         urls = [addr]
         if ":" not in addr:
             urls.append(f"{addr}:{SERVER_PORT}")
@@ -97,16 +95,16 @@ def _try_start_server_or_get_url(args: argparse.Namespace) -> str | CompileServe
         result: ConnectionResult | None = find_good_connection(urls)
         if result is not None:
             print(f"Found local server at {result.host}")
-            return result.host
+            return (result.host, None)
         else:
             local_host_needs_server = True
 
-    if not local_host_needs_server and args.web:
-        if isinstance(args.web, str):
-            return args.web
-        if isinstance(args.web, bool):
-            return DEFAULT_URL
-        return args.web
+    if not local_host_needs_server and args_web:
+        if isinstance(args_web, str):
+            return (args_web, None)
+        if isinstance(args_web, bool):
+            return (DEFAULT_URL, None)
+        return (args_web, None)
     else:
         try:
             print("No local server found, starting one...")
@@ -114,76 +112,64 @@ def _try_start_server_or_get_url(args: argparse.Namespace) -> str | CompileServe
             print("Waiting for the local compiler to start...")
             if not compile_server.ping():
                 print("Failed to start local compiler.")
-                raise RuntimeError("Failed to start local compiler.")
-            return compile_server
+                raise CompileServerError("Failed to start local compiler.")
+            return (compile_server.url(), compile_server)
         except KeyboardInterrupt:
             raise
         except RuntimeError:
             print("Failed to start local compile server, using web compiler instead.")
-            return DEFAULT_URL
+            return (DEFAULT_URL, None)
 
 
-def run_client_server(args: argparse.Namespace) -> int:
-    compile_server: CompileServer | None = None
-    open_web_browser = not args.just_compile and not args.interactive
-    profile = args.profile
-    if not args.force_compile and not looks_like_sketch_directory(Path(args.directory)):
-        print(
-            "Error: Not a valid FastLED sketch directory, if you are sure it is, use --force-compile"
-        )
-        return 1
+def run_client(
+    directory: Path,
+    host: str | CompileServer | None,
+    open_web_browser: bool = True,
+    keep_running: bool = True,  # if false, only one compilation will be done.
+    build_mode: BuildMode = BuildMode.QUICK,
+    profile: bool = False,
+    shutdown: threading.Event | None = None,
+) -> int:
+
+    compile_server: CompileServer | None = (
+        host if isinstance(host, CompileServer) else None
+    )
+    shutdown = shutdown or threading.Event()
 
-    # If not explicitly using web compiler, check Docker installation
-    if not args.web and not DockerManager.is_docker_installed():
-        print(
-            "\nDocker is not installed on this system - switching to web compiler instead."
-        )
-        args.web = True
+    def get_url() -> str:
+        if compile_server is not None:
+            return compile_server.url()
+        if isinstance(host, str):
+            return host
+        return DEFAULT_URL
+
+    url = get_url()
 
-    url: str
     try:
-        try:
-            url_or_server: str | CompileServer = _try_start_server_or_get_url(args)
-            if isinstance(url_or_server, str):
-                print(f"Found URL: {url_or_server}")
-                url = url_or_server
-            else:
-                compile_server = url_or_server
-                print(f"Server started at {compile_server.url()}")
-                url = compile_server.url()
-        except KeyboardInterrupt:
-            print("\nExiting from first try...")
-            if compile_server:
-                compile_server.stop()
-            return 1
-        except Exception as e:
-            print(f"Error: {e}")
-            return 1
-        build_mode: BuildMode = get_build_mode(args)
 
         def compile_function(
             url: str = url,
             build_mode: BuildMode = build_mode,
             profile: bool = profile,
             last_hash_value: str | None = None,
-        ) -> CompiledResult:
+        ) -> CompileResult:
             return _run_web_compiler(
-                args.directory,
+                directory,
                 host=url,
                 build_mode=build_mode,
                 profile=profile,
                 last_hash_value=last_hash_value,
             )
 
-        result: CompiledResult = compile_function(last_hash_value=None)
-        last_compiled_result: CompiledResult = result
+        result: CompileResult = compile_function(last_hash_value=None)
+        last_compiled_result: CompileResult = result
 
         if not result.success:
             print("\nCompilation failed.")
 
         browser_proc: Process | None = None
         if open_web_browser:
-            browser_proc = open_browser_process(Path(args.directory) / "fastled_js")
+            browser_proc = open_browser_process(directory / "fastled_js")
         else:
             print("\nCompilation successful.")
             if compile_server:
@@ -191,21 +177,15 @@ def run_client_server(args: argparse.Namespace) -> int:
                 compile_server.stop()
             return 0
 
-        if args.just_compile:
-            if compile_server:
-                compile_server.stop()
+        if not keep_running or shutdown.is_set():
             if browser_proc:
                 browser_proc.kill()
             return 0 if result.success else 1
     except KeyboardInterrupt:
         print("\nExiting from main")
-        if compile_server:
-            compile_server.stop()
         return 1
 
-    sketch_filewatcher = FileWatcherProcess(
-        args.directory, excluded_patterns=["fastled_js"]
-    )
+    sketch_filewatcher = FileWatcherProcess(directory, excluded_patterns=["fastled_js"])
 
     source_code_watcher: FileWatcherProcess | None = None
     if compile_server and compile_server.using_fastled_src_dir_volume():
@@ -215,8 +195,8 @@ def run_client_server(args: argparse.Namespace) -> int:
         )
 
     def trigger_rebuild_if_sketch_changed(
-        last_compiled_result: CompiledResult,
-    ) -> tuple[bool, CompiledResult]:
+        last_compiled_result: CompileResult,
+    ) -> tuple[bool, CompileResult]:
         changed_files = sketch_filewatcher.get_all_changes()
         if changed_files:
             print(f"\nChanges detected in {changed_files}")
@@ -237,6 +217,9 @@ def run_client_server(args: argparse.Namespace) -> int:
 
     try:
         while True:
+            if shutdown.is_set():
+                print("\nStopping watch mode...")
+                return 0
             if SpaceBarWatcher.watch_space_bar_pressed(timeout=1.0):
                 print("Compiling...")
                 last_compiled_result = compile_function(last_hash_value=None)
@@ -304,3 +287,59 @@ def run_client_server(args: argparse.Namespace) -> int:
             compile_server.stop()
         if browser_proc:
             browser_proc.kill()
+
+
+def run_client_server(args: argparse.Namespace) -> int:
+    profile = bool(args.profile)
+    web: str | bool = args.web if isinstance(args.web, str) else bool(args.web)
+    auto_update = bool(args.auto_update)
+    localhost = bool(args.localhost)
+    directory = Path(args.directory)
+    just_compile = bool(args.just_compile)
+    interactive = bool(args.interactive)
+    force_compile = bool(args.force_compile)
+    open_web_browser = not just_compile and not interactive
+    build_mode: BuildMode = BuildMode.from_args(args)
+
+    if not force_compile and not looks_like_sketch_directory(directory):
+        print(
+            "Error: Not a valid FastLED sketch directory, if you are sure it is, use --force-compile"
+        )
+        return 1
+
+    # If not explicitly using web compiler, check Docker installation
+    if not web and not DockerManager.is_docker_installed():
+        print(
+            "\nDocker is not installed on this system - switching to web compiler instead."
+        )
+        web = True
+
+    url: str
+    compile_server: CompileServer | None = None
+    try:
+        url, compile_server = _try_start_server_or_get_url(auto_update, web, localhost)
+    except KeyboardInterrupt:
+        print("\nExiting from first try...")
+        if compile_server:
+            compile_server.stop()
+        return 1
+    except Exception as e:
+        print(f"Error: {e}")
+        if compile_server:
+            compile_server.stop()
+        return 1
+
+    try:
+        return run_client(
+            directory=directory,
+            host=compile_server if compile_server else url,
+            open_web_browser=open_web_browser,
+            keep_running=not just_compile,
+            build_mode=build_mode,
+            profile=profile,
+        )
+    except KeyboardInterrupt:
+        return 1
+    finally:
+        if compile_server:
+            compile_server.stop()

fastled/compile_server.py

@@ -1,10 +1,11 @@
 from pathlib import Path
 
-from fastled.build_mode import BuildMode
-from fastled.types import WebCompileResult
+from fastled.types import BuildMode, CompileResult, Platform
 
 
 class CompileServer:
+
+    # May throw CompileServerError if auto_start is True.
     def __init__(
         self,
         interactive: bool = False,
@@ -12,11 +13,14 @@ class CompileServer:
         mapped_dir: Path | None = None,
         auto_start: bool = True,
         container_name: str | None = None,
+        platform: Platform = Platform.WASM,
     ) -> None:
         from fastled.compile_server_impl import (  # avoid circular import
             CompileServerImpl,
         )
 
+        assert platform == Platform.WASM, "Only WASM platform is supported right now."
+
         self.impl = CompileServerImpl(
             container_name=container_name,
             interactive=interactive,
@@ -25,6 +29,7 @@ class CompileServer:
             auto_start=auto_start,
         )
 
+    # May throw CompileServerError if server could not be started.
     def start(self, wait_for_startup=True) -> None:
         # from fastled.compile_server_impl import CompileServerImpl  # avoid circular import
         self.impl.start(wait_for_startup=wait_for_startup)
@@ -34,7 +39,7 @@ class CompileServer:
         directory: Path | str,
         build_mode: BuildMode = BuildMode.QUICK,
         profile: bool = False,
-    ) -> WebCompileResult:
+    ) -> CompileResult:
         return self.impl.web_compile(
             directory=directory, build_mode=build_mode, profile=profile
         )

fastled/compile_server_impl.py

@@ -6,7 +6,6 @@ from pathlib import Path
 
 import httpx
 
-from fastled.build_mode import BuildMode
 from fastled.docker_manager import (
     DISK_CACHE,
     Container,
@@ -15,13 +14,27 @@ from fastled.docker_manager import (
 )
 from fastled.settings import SERVER_PORT
 from fastled.sketch import looks_like_fastled_repo
-from fastled.types import WebCompileResult
+from fastled.types import BuildMode, CompileResult, CompileServerError
 
 _IMAGE_NAME = "niteris/fastled-wasm"
 _DEFAULT_CONTAINER_NAME = "fastled-wasm-compiler"
 
 
-SERVER_OPTIONS = ["--allow-shutdown", "--no-auto-update"]
+SERVER_OPTIONS = [
+    "--allow-shutdown",  # Allow the server to be shut down without a force kill.
+    "--no-auto-update",  # Don't auto live updates from the git repo.
+]
+
+
+def _try_get_fastled_src(path: Path) -> Path | None:
+    fastled_src_dir: Path | None = None
+    if looks_like_fastled_repo(path):
+        print(
+            "Looks like a FastLED repo, using it as the source directory and mapping it into the server."
+        )
+        fastled_src_dir = path / "src"
+        return fastled_src_dir
+    return None
 
 
 class CompileServerImpl:
@@ -40,52 +53,46 @@ class CompileServerImpl:
             )
         if not interactive and mapped_dir:
             raise ValueError("Mapped directory is only used in interactive mode")
-        cwd = Path(".").resolve()
-        fastled_src_dir: Path | None = None
-        if looks_like_fastled_repo(cwd):
-            print(
-                "Looks like a FastLED repo, using it as the source directory and mapping it into the server."
-            )
-            fastled_src_dir = cwd / "src"
-
         self.container_name = container_name
         self.mapped_dir = mapped_dir
         self.docker = DockerManager()
-        self.fastled_src_dir: Path | None = fastled_src_dir
+        self.fastled_src_dir: Path | None = _try_get_fastled_src(Path(".").resolve())
         self.interactive = interactive
         self.running_container: RunningContainer | None = None
         self.auto_updates = auto_updates
-        # self._port = self._start()
         self._port = 0  # 0 until compile server is started
-        # fancy print
-        if not interactive:
-            msg = f"# FastLED Compile Server started at {self.url()} #"
-            print("\n" + "#" * len(msg))
-            print(msg)
-            print("#" * len(msg) + "\n")
         if auto_start:
             self.start()
 
     def start(self, wait_for_startup=True) -> None:
+        if not DockerManager.is_docker_installed():
+            raise CompileServerError("Docker is not installed")
         if self._port != 0:
             warnings.warn("Server has already been started")
         self._port = self._start()
         if wait_for_startup:
-            self.wait_for_startup()
+            ok = self.wait_for_startup()
+            if not ok:
+                raise CompileServerError("Server did not start")
+        if not self.interactive:
+            msg = f"# FastLED Compile Server started at {self.url()} #"
+            print("\n" + "#" * len(msg))
+            print(msg)
+            print("#" * len(msg) + "\n")
 
     def web_compile(
         self,
         directory: Path | str,
         build_mode: BuildMode = BuildMode.QUICK,
         profile: bool = False,
-    ) -> WebCompileResult:
+    ) -> CompileResult:
         from fastled.web_compile import web_compile  # avoid circular import
 
         if not self._port:
             raise RuntimeError("Server has not been started yet")
         if not self.ping():
             raise RuntimeError("Server is not running")
-        out: WebCompileResult = web_compile(
+        out: CompileResult = web_compile(
             directory, host=self.url(), build_mode=build_mode, profile=profile
         )
         return out

fastled/live_client.py

@@ -0,0 +1,69 @@
+import threading
+from pathlib import Path
+
+from fastled.compile_server import CompileServer
+from fastled.types import BuildMode
+
+
+class LiveClient:
+    """LiveClient class watches for changes and auto-triggeres rebuild."""
+
+    def __init__(
+        self,
+        sketch_directory: Path,
+        host: str | CompileServer | None = None,
+        auto_start: bool = True,
+        open_web_browser: bool = True,
+        keep_running: bool = True,
+        build_mode: BuildMode = BuildMode.QUICK,
+        profile: bool = False,
+    ) -> None:
+        self.sketch_directory = sketch_directory
+        self.host = host
+        self.open_web_browser = open_web_browser
+        self.keep_running = keep_running
+        self.build_mode = build_mode
+        self.profile = profile
+        self.auto_start = auto_start
+        self.shutdown = threading.Event()
+        self.thread: threading.Thread | None = None
+        if auto_start:
+            self.start()
+
+    def run(self) -> int:
+        """Run the client."""
+        from fastled.client_server import run_client  # avoid circular import
+
+        rtn = run_client(
+            directory=self.sketch_directory,
+            host=self.host,
+            open_web_browser=self.open_web_browser,
+            keep_running=self.keep_running,
+            build_mode=self.build_mode,
+            profile=self.profile,
+            shutdown=self.shutdown,
+        )
+        return rtn
+
+    @property
+    def running(self) -> bool:
+        return self.thread is not None and self.thread.is_alive()
+
+    def start(self) -> None:
+        """Start the client."""
+        assert not self.running, "LiveClient is already running"
+        self.shutdown.clear()
+        self.thread = threading.Thread(target=self.run, daemon=True)
+        self.thread.start()
+
+    def stop(self) -> None:
+        """Stop the client."""
+        self.shutdown.set()
+        if self.thread:
+            self.thread.join()
+            self.thread = None
+
+    def finalize(self) -> None:
+        """Finalize the client."""
+        self.stop()
+        self.thread = None

fastled/types.py

@@ -1,18 +1,11 @@
+import argparse
 from dataclasses import dataclass
+from enum import Enum
 from typing import Any
 
 
 @dataclass
-class CompiledResult:
-    """Dataclass to hold the result of the compilation."""
-
-    success: bool
-    fastled_js: str
-    hash_value: str | None
-
-
-@dataclass
-class WebCompileResult:
+class CompileResult:
     success: bool
     stdout: str
     hash_value: str | None
@@ -23,3 +16,46 @@ class WebCompileResult:
 
     def to_dict(self) -> dict[str, Any]:
         return self.__dict__.copy()
+
+
+class CompileServerError(Exception):
+    """Error class for failing to instantiate CompileServer."""
+
+    pass
+
+
+class BuildMode(Enum):
+    DEBUG = "DEBUG"
+    QUICK = "QUICK"
+    RELEASE = "RELEASE"
+
+    @classmethod
+    def from_string(cls, mode_str: str) -> "BuildMode":
+        try:
+            return cls[mode_str.upper()]
+        except KeyError:
+            valid_modes = [mode.name for mode in cls]
+            raise ValueError(f"BUILD_MODE must be one of {valid_modes}, got {mode_str}")
+
+    @staticmethod
+    def from_args(args: argparse.Namespace) -> "BuildMode":
+        if args.debug:
+            return BuildMode.DEBUG
+        elif args.release:
+            return BuildMode.RELEASE
+        else:
+            return BuildMode.QUICK
+
+
+class Platform(Enum):
+    WASM = "WASM"
+
+    @classmethod
+    def from_string(cls, platform_str: str) -> "Platform":
+        try:
+            return cls[platform_str.upper()]
+        except KeyError:
+            valid_modes = [mode.name for mode in cls]
+            raise ValueError(
+                f"Platform must be one of {valid_modes}, got {platform_str}"
+            )

fastled/web_compile.py

@@ -11,10 +11,9 @@ from pathlib import Path
 
 import httpx
 
-from fastled.build_mode import BuildMode
 from fastled.settings import SERVER_PORT
 from fastled.sketch import get_sketch_files
-from fastled.types import WebCompileResult
+from fastled.types import BuildMode, CompileResult
 from fastled.util import hash_file
 
 DEFAULT_HOST = "https://fastled.onrender.com"
@@ -160,7 +159,7 @@ def web_compile(
     auth_token: str | None = None,
     build_mode: BuildMode | None = None,
     profile: bool = False,
-) -> WebCompileResult:
+) -> CompileResult:
     if isinstance(directory, str):
         directory = Path(directory)
     host = _sanitize_host(host or DEFAULT_HOST)
@@ -171,7 +170,7 @@ def web_compile(
         raise FileNotFoundError(f"Directory not found: {directory}")
     zip_result = zip_files(directory, build_mode=build_mode)
     if isinstance(zip_result, Exception):
-        return WebCompileResult(
+        return CompileResult(
             success=False, stdout=str(zip_result), hash_value=None, zip_bytes=b""
         )
     zip_bytes = zip_result.zip_bytes
@@ -187,7 +186,7 @@ def web_compile(
         connection_result = find_good_connection(urls)
         if connection_result is None:
             print("Connection failed to all endpoints")
-            return WebCompileResult(
+            return CompileResult(
                 success=False,
                 stdout="Connection failed",
                 hash_value=None,
@@ -229,7 +228,7 @@ def web_compile(
             if response.status_code != 200:
                 json_response = response.json()
                 detail = json_response.get("detail", "Could not compile")
-                return WebCompileResult(
+                return CompileResult(
                     success=False, stdout=detail, hash_value=None, zip_bytes=b""
                 )
 
@@ -270,7 +269,7 @@ def web_compile(
                             relative_path = file_path.relative_to(extract_path)
                             out_zip.write(file_path, relative_path)
 
-                return WebCompileResult(
+                return CompileResult(
                     success=True,
                     stdout=stdout,
                     hash_value=hash_value,
@@ -281,6 +280,6 @@ def web_compile(
         raise
     except httpx.HTTPError as e:
         print(f"Error: {e}")
-        return WebCompileResult(
+        return CompileResult(
             success=False, stdout=str(e), hash_value=None, zip_bytes=b""
         )

{fastled-1.1.37.dist-info → fastled-1.1.39.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fastled
-Version: 1.1.37
+Version: 1.1.39
 Summary: FastLED Wasm Compiler
 Home-page: https://github.com/zackees/fastled-wasm
 Maintainer: Zachary Vorhies
@@ -61,60 +61,155 @@ pip install fastled
 
 **Note that you may need to install x86 docker emulation on Mac-m1 and later, as this is an x86 only image at the prsent.**
 
-# Use
+# Command Line Use
 
 Change to the directory where the sketch lives and run, will run the compilation
 on the web compiler.
 
 ```bash
+# This will use the web-compiler, unless you have docker installed in which case a local
+# server will be instantiated automatically.
 cd <SKETCH-DIRECTORY>
 fastled
 ```
 
-Or if you have docker you can run a server automatically.
+Forces the local server to to spawn in order to run to do the compile.
 
 ```bash
 cd <SKETCH-DIRECTORY>
-fastled --local
+fastled --local  # if server doesn't already exist, one is created.
 ```
 
 You can also spawn a server in one process and then access it in another, like this:
 
 ```bash
-fastled --server
+fastled --server  # server will now run in the background.
 # now launch the client
-fastled examples/wasm --local
+fastled examples/wasm --local  # local will find the local server use it do the compile.
 ```
 
 After compilation a web browser windows will pop up. Changes to the sketch will automatically trigger a recompilation.
 
-# Hot reload by default
+# Python Api
+
+**Compiling through the api**
+```python
+
+from fastapi import Api, CompileResult
+
+out: CompileResult = Api.web_compile("path/to/sketch")
+print(out.success)
+print(out.stdout)
+
+```
+
+**Launching a compile server**
+```python
+
+from fastapi import Api, CompileServer
+
+server: CompileServer = Api.spawn_server()
+print(f"Local server running at {server.url()}")
+server.web_compile("path/to/sketch")  # output will be "path/to/sketch/fastled_js"
+server.stop()
+```
+
+**Launching a server in a scope**
+```python
+
+from fastapi import Api
+
+# Launching a server in a scope
+with Api.server() as server:
+    server.web_compile("path/to/sketch")
+
+```
+
+**Initializing a project example from the web compiler**
+```python
+
+from fastapi import Api
+
+examples = Api.get_examples()
+print(f"Print available examples: {examples}")
+Api.project_init(examples[0])
+
+
+```
+
+**Initializing a project example from the CompileServer**
+```python
+
+from fastapi import Api
+
+with Api.server() as server:
+    examples = server.get_examples()
+    server.project_init(examples[0])
+
+```
+
+**LiveClient will auto-trigger a build on code changes, just like the cli does**
+```python
+
+# Live Client will compile against the web-compiler
+from fastapi import Api, LiveClient
+client: LiveClient = Api.live_client(
+    "path/to/sketch_directory",
+)
+# Now user can start editing their sketch and it will auto-compile
+# ... after a while stop it like this.
+client.stop()
+```
+
+**LiveClient with local CompileServer**
+```python
+
+# Live Client will compile against a local server.
+from fastapi import Api, LiveClient
+
+with Api.server() as server:
+    client: LiveClient = Api.live_client(
+        "path/to/sketch_directory",
+        host=server
+    )
+    # Now user can start editing their sketch and it will auto-compile
+    # ... after a while stop it like this.
+    client.stop()
+```
+
+# Features
+
+## Hot reload by default
 
 Once launched, the compiler will remain open, listening to changes and recompiling as necessary and hot-reloading the sketch into the current browser.
 
 This style of development should be familiar to those doing web development.
 
-# Hot Reload for working with the FastLED repo
+## Hot Reload fastled/src when working in the FastLED repo
 
 If you launch `fastled` in the FastLED repo then this tool will automatically detect this and map the src directory into the
 host container. Whenever there are changes in the source code from the mapped directory, then these will be re-compiled
 on the next change or if you hit the space bar when prompted. Unlike a sketch folder, a re-compile on the FastLED src
 can be much longer, for example if you modify a header file.
 
-# Data
+## Big Data in `/data` directory won't be round-tripped
 
 Huge blobs of data like video will absolutely kill the compile performance as these blobs would normally have to be shuffled
 back and forth. Therefore a special directory `data/` is implicitly used to hold this blob data. Any data in this directory
 will be replaced with a stub containing the size and hash of the file during upload. On download these stubs are swapped back
-with their originals.
+with their originals during decompression.
 
 The wasm compiler will recognize all files in the `data/` directory and generate a `files.json` manifest and can be used
 in your wasm sketch using an emulated SD card system mounted at `/data/` on the SD Card. In order to increase load speed, these
-files will be asynchroniously streamed into the running sketch instance during runtime. The only caveat here is that although these files will be available during the setup() phase of the sketch, they will not be fully hydrated, so if you do a seek(end) of these files the results are undefined.
+files will be asynchroniously streamed into the running sketch instance during runtime. Files named with *.json, *.csv, *.txt will be
+immediately injected in the app before setup() is called and can be used immediatly in setup() in their entirety.
+
+All other files will be streamed in. The `Video` element in FastLED is designed to gracefully handle missing data streamed in through
+the file system.
 
 For an example of how to use this see `examples/SdCard` which is fully wasm compatible.
 
-# Compile Speed
+## Compile Speed
 
 The compile speeds for this compiler have been optimized pretty much to the max. There are three compile settings available to the user. The default is `--quick`. Aggressive optimizations are done with `--release` which will aggressively optimize for size. The speed difference between `--release` and `--quick` seems negligable. But `--release` will produce a ~1/3 smaller binary. There is also `--debug`, which will include symbols necessary for debugging and getting the C++ function symbols working correctly in the browser during step through debugging. It works better than expected, but don't expect to have gdb or msvc debugger level of debugging experience.
 
@@ -122,24 +217,22 @@ We use `ccache` to cache object files. This seems actually help a lot and is bet
 
 The compilation to wasm will happen under a lock. Removing this lock requires removing the platformio toolchain as the compiler backend which enforces it's own internal lock preventing parallel use.
 
-Simple syntax errors will be caught by the pre-processing step. This happens without a lock to reduce the single lock bottleneck.
-
-# Sketch Cache
+## Sketch Cache
 
-Sketchs are aggresively finger-printed and stored in a cache. White space, comments, and other superficial data will be stripped out during pre-processing and minimization for fingerprinting. This source file decimation is only used for finger
+Sketchs are aggressively finger-printed and stored in a cache. White space, comments, and other superficial data will be stripped out during pre-processing and minimization for fingerprinting. This source file decimation is only used for finger
 printing while the actual source files are sent to compiler to preserve line numbers and file names.
 
 This pre-processing done is done via gcc and special regex's and will happen without a lock. This will allow you to have extremely quick recompiles for whitespace and changes in comments even if the compiler is executing under it's lock.
 
-# Local compiles
+## Local compiles
 
 If the web-compiler get's congested then it's recommend that you run the compiler locally. This requires docker and will be invoked whenever you pass in `--local`. This will first pull the most recent Docker image of the Fastled compiler, launching a webserver and then connecting to it with the client once it's been up.
 
-# Auto updates
+## Auto updates
 
 In server mode the git repository will be cloned as a side repo and then periodically updated and rsync'd to the src directory. This allows a long running instance to stay updated.
 
-### Wasm compatibility with Arduino sketchs
+## Compatibility with Arduino sketchs
 
 The compatibility is actually pretty good. Most simple sketchs should compile out of the box. Even some of the avr platform includes are stubbed out to make it work. The familiar `digitalWrite()`, `Serial.println()` and other common functions work. Although `digitalRead()` will always return 0 and `analogRead()` will return random numbers.
 
@@ -163,6 +256,8 @@ A: A big chunk of space is being used by unnecessary javascript `emscripten` is
 
 # Revisions
   
+  * 1.1.39 - Added `LiveClient`, `fastled.Api.live_server()` will spawn it. Allows user to have a live compiling client that re-triggers a compile on file changes.
+  * 1.1.38 - Cleanup the `fastled.Api` object and streamline for general use.
   * 1.1.37 - `Test.test_examples()` is now unit tested to work correctly.
   * 1.1.36 - We now have an api. `from fastled import Api` and `from fastled import Test` for testing.
   * 1.1.35 - When searching for files cap the limit at a high amount to prevent hang.

{fastled-1.1.37.dist-info → fastled-1.1.39.dist-info}/RECORD

@@ -1,13 +1,13 @@
-fastled/__init__.py,sha256=PWN2ftSaLElmfJkYyv0gmGKZgBTljVv8D58Di0JGmeY,2539
+fastled/__init__.py,sha256=SQF8-PpioJm6DAQn5vCcc-muwXHBfs0loIofSRoWK8g,3613
 fastled/app.py,sha256=3xg7oVD-UYnKPU8SAY-Cs5UnAYdwpdpuEFRR2N8P1Tg,1787
-fastled/build_mode.py,sha256=joMwsV4K1y_LijT4gEAcjx69RZBoe_KmFmHZdPYbL_4,631
 fastled/cli.py,sha256=CNR_pQR0sNVPNuv8e_nmm-0PI8sU-eUBUgnWgWkzW9c,237
-fastled/client_server.py,sha256=rre250O1uCx6JFi_nn6fhKUncgKOw3F7BgN9O9wbCEM,11440
-fastled/compile_server.py,sha256=QxkXLpj9q7BWhPbS2NPeFF4WRne-358o-8fg4VEDH1o,2427
-fastled/compile_server_impl.py,sha256=cB5WZ9znNhCFe2HKl-p1ZonfYKeaJOUyV3uHfkQtTZk,8481
+fastled/client_server.py,sha256=KQsBKjHfkhgF5EOCHSbJcqu0dPKlOCsbXA2V035VCH0,12403
+fastled/compile_server.py,sha256=Z7rHFs3M6QPbSCsbgHAQDk6GTVAJMMPCXtD4Y0mu8RM,2659
+fastled/compile_server_impl.py,sha256=ClBLtFHB0ucaT8tAJfI6o3bJ-LRnXc4Pxy7bVKnFiww,8803
 fastled/docker_manager.py,sha256=zBCFGk2P3_bS7_SUQ5j2lpsOS3RvIzXYkrJXC6xP69k,25383
 fastled/filewatcher.py,sha256=LwEQJkqADsArZyY499RLAer6JjJyDwaQBcAvT7xmp3c,6708
 fastled/keyboard.py,sha256=Zz_ggxOUTX2XQEy6K6kAoorVlUev4wEk9Awpvv9aStA,3241
+fastled/live_client.py,sha256=_KvqmyUyyGpoYET1Z9CdeUVoIbFjIUWwPcTp5XCQuxY,2075
 fastled/open_browser.py,sha256=vzMBcpDNY0f-Bx9KmEILKDANZ6gvsywCVwn1FRhPXh4,1770
 fastled/parse_args.py,sha256=37WsELphNEqGQgmjppZx6uMWE2E-dZ58zCKUl-3mr3Q,6150
 fastled/paths.py,sha256=VsPmgu0lNSCFOoEC0BsTYzDygXqy15AHUfN-tTuzDZA,99
@@ -17,14 +17,14 @@ fastled/settings.py,sha256=3eMKv0tLXgIQ0CFDboIp_l5_71rzIIyWg353YjnYJnc,323
 fastled/sketch.py,sha256=483TrrIdZJfo1MIu5FkD-V5OGmOfHmsZ2f6VvNsJBJM,3299
 fastled/spinner.py,sha256=VHxmvB92P0Z_zYxRajb5HiNmkHHvZ5dG7hKtZltzpcs,867
 fastled/string_diff.py,sha256=UR1oRhg9lsPzAG4bn_MwJMCn0evP5AigkBiwLiI9fgA,1354
-fastled/types.py,sha256=4uSSuOUhZptTreor6CXXGSk-FIMOdwHfdvFI-4Yx6AY,475
+fastled/types.py,sha256=PpSEtzFCkWtSIEMC0QXGl966R97vLoryVl3yFW0YhTs,1475
 fastled/util.py,sha256=t4M3NFMhnCzfYbLvIyJi0RdFssZqbTN_vVIaej1WV-U,265
-fastled/web_compile.py,sha256=0jXFeej-YhOxcjIau8Ru8qEu-ULlsFjaufbqKYUUXjQ,10312
+fastled/web_compile.py,sha256=05PeLJ77QQC6PUKjDhsntBmyBola6QQIfF2k-zjYNE4,10261
 fastled/assets/example.txt,sha256=lTBovRjiz0_TgtAtbA1C5hNi2ffbqnNPqkKg6UiKCT8,54
 fastled/test/examples.py,sha256=EDXb6KastKOOWzew99zrpmcNcXTcAtYi8eud6F1pnWA,980
-fastled-1.1.37.dist-info/LICENSE,sha256=b6pOoifSXiUaz_lDS84vWlG3fr4yUKwB8fzkrH9R8bQ,1064
-fastled-1.1.37.dist-info/METADATA,sha256=2_Eusq7JNju_ZOcwRSWmACJv6vY69A48T2hFs3kbSLE,15329
-fastled-1.1.37.dist-info/WHEEL,sha256=0VNUDWQJzfRahYI3neAhz2UVbRCtztpN5dPHAGvmGXc,109
-fastled-1.1.37.dist-info/entry_points.txt,sha256=RCwmzCSOS4-C2i9EziANq7Z2Zb4KFnEMR1FQC0bBwAw,101
-fastled-1.1.37.dist-info/top_level.txt,sha256=Bbv5kpJpZhWNCvDF4K0VcvtBSDMa8B7PTOrZa9CezHY,8
-fastled-1.1.37.dist-info/RECORD,,
+fastled-1.1.39.dist-info/LICENSE,sha256=b6pOoifSXiUaz_lDS84vWlG3fr4yUKwB8fzkrH9R8bQ,1064
+fastled-1.1.39.dist-info/METADATA,sha256=a-iU6xg5tbGNPN-2l0Bydnk3Xax9-jfWAFV7ltioC6U,17889
+fastled-1.1.39.dist-info/WHEEL,sha256=0VNUDWQJzfRahYI3neAhz2UVbRCtztpN5dPHAGvmGXc,109
+fastled-1.1.39.dist-info/entry_points.txt,sha256=RCwmzCSOS4-C2i9EziANq7Z2Zb4KFnEMR1FQC0bBwAw,101
+fastled-1.1.39.dist-info/top_level.txt,sha256=Bbv5kpJpZhWNCvDF4K0VcvtBSDMa8B7PTOrZa9CezHY,8
+fastled-1.1.39.dist-info/RECORD,,

fastled/build_mode.py

@@ -1,25 +0,0 @@
-import argparse
-from enum import Enum
-
-
-class BuildMode(Enum):
-    DEBUG = "DEBUG"
-    QUICK = "QUICK"
-    RELEASE = "RELEASE"
-
-    @classmethod
-    def from_string(cls, mode_str: str) -> "BuildMode":
-        try:
-            return cls[mode_str.upper()]
-        except KeyError:
-            valid_modes = [mode.name for mode in cls]
-            raise ValueError(f"BUILD_MODE must be one of {valid_modes}, got {mode_str}")
-
-
-def get_build_mode(args: argparse.Namespace) -> BuildMode:
-    if args.debug:
-        return BuildMode.DEBUG
-    elif args.release:
-        return BuildMode.RELEASE
-    else:
-        return BuildMode.QUICK