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

fastled/emoji_util.py

@@ -0,0 +1,27 @@
+"""
+Emoji utility functions for handling Unicode display issues on Windows cmd.exe
+"""
+
+import sys
+
+
+def EMO(emoji: str, fallback: str) -> str:
+    """Get emoji with fallback for systems that don't support Unicode properly"""
+    try:
+        # Test if we can encode the emoji properly
+        emoji.encode(sys.stdout.encoding or "utf-8")
+        return emoji
+    except (UnicodeEncodeError, AttributeError):
+        return fallback
+
+
+def safe_print(text: str) -> None:
+    """Print text safely, handling Unicode/emoji encoding issues on Windows cmd.exe"""
+    try:
+        print(text)
+    except UnicodeEncodeError:
+        # Replace problematic characters with safe alternatives
+        safe_text = text.encode(
+            sys.stdout.encoding or "utf-8", errors="replace"
+        ).decode(sys.stdout.encoding or "utf-8")
+        print(safe_text)

fastled/filewatcher.py

@@ -1,5 +1,6 @@
 """File system watcher implementation using watchdog"""
 
+import _thread
 import hashlib
 import os
 import queue
@@ -15,10 +16,14 @@ from watchdog.events import FileSystemEvent, FileSystemEventHandler
 from watchdog.observers import Observer
 from watchdog.observers.api import BaseObserver
 
+from fastled.settings import FILE_CHANGED_DEBOUNCE_SECONDS
+
+_WATCHER_TIMEOUT = 0.1
+
 
 def file_watcher_enabled() -> bool:
-    """Check if watchdog is disabled"""
-    return os.getenv("NO_FILE_WATCHING", "0") == "1"
+    """Check if watchdog is enabled"""
+    return os.getenv("NO_FILE_WATCHING", "0") != "1"
 
 
 def file_watcher_set(enabled: bool) -> None:
@@ -68,7 +73,7 @@ class FileChangedNotifier(threading.Thread):
     def __init__(
         self,
         path: str,
-        debounce_seconds: float = 1.0,
+        debounce_seconds: float = FILE_CHANGED_DEBOUNCE_SECONDS,
         excluded_patterns: list[str] | None = None,
     ) -> None:
         """Initialize the notifier with a path to watch
@@ -117,10 +122,13 @@ class FileChangedNotifier(threading.Thread):
                 time.sleep(0.1)
         except KeyboardInterrupt:
             print("File watcher stopped by user.")
+            import _thread
+
+            _thread.interrupt_main()
         finally:
             self.stop()
 
-    def get_next_change(self, timeout: float = 0.001) -> str | None:
+    def get_next_change(self, timeout: float = _WATCHER_TIMEOUT) -> str | None:
         """Get the next file change event from the queue
 
         Args:
@@ -129,7 +137,7 @@ class FileChangedNotifier(threading.Thread):
         Returns:
             Changed filepath or None if no change within timeout
         """
-        if file_watcher_enabled():
+        if not file_watcher_enabled():
             time.sleep(timeout)
             return None
         try:
@@ -148,7 +156,7 @@ class FileChangedNotifier(threading.Thread):
         except queue.Empty:
             return None
 
-    def get_all_changes(self, timeout: float = 0.001) -> list[str]:
+    def get_all_changes(self, timeout: float = _WATCHER_TIMEOUT) -> list[str]:
         """Get all file change events from the queue
 
         Args:
@@ -185,15 +193,26 @@ def _process_wrapper(root: Path, excluded_patterns: list[str], queue: Queue):
             watcher.stop()
 
 
+class ProcessWraperTask:
+    def __init__(self, root: Path, excluded_patterns: list[str], queue: Queue) -> None:
+        self.root = root
+        self.excluded_patterns = excluded_patterns
+        self.queue = queue
+
+    def run(self):
+        _process_wrapper(self.root, self.excluded_patterns, self.queue)
+
+
 class FileWatcherProcess:
     def __init__(self, root: Path, excluded_patterns: list[str]) -> None:
         self.queue: Queue = Queue()
+        task = ProcessWraperTask(root, excluded_patterns, self.queue)
         self.process = Process(
-            target=_process_wrapper,
-            args=(root, excluded_patterns, self.queue),
+            target=task.run,
             daemon=True,
         )
         self.process.start()
+        self.global_debounce = FILE_CHANGED_DEBOUNCE_SECONDS
 
     def stop(self):
         self.process.terminate()
@@ -212,3 +231,76 @@ class FileWatcherProcess:
             except Empty:
                 break
         return changed_files
+
+
+class DebouncedFileWatcherProcess(threading.Thread):
+    """
+    Wraps a FileWatcherProcess to batch rapid-fire change events
+    and only emit them once the debounce interval has passed.
+    Runs in its own thread, polling every 0.1 s.
+    """
+
+    def __init__(
+        self,
+        watcher: FileWatcherProcess,
+        debounce_seconds: float = FILE_CHANGED_DEBOUNCE_SECONDS,
+    ) -> None:
+        super().__init__(daemon=True)
+        self.watcher = watcher
+        self.debounce_seconds = debounce_seconds
+
+        # internal buffer & timing
+        self._buffer: list[str] = []
+        self._last_time: float = 0.0
+
+        # queue of flushed batches
+        self._out_queue: queue.Queue[list[str]] = queue.Queue()
+        self._stop_event = threading.Event()
+
+        # record timestamp of last event for external inspection
+        self.last_event_time: float | None = None
+
+        self.start()
+
+    def run(self) -> None:
+        try:
+            while not self._stop_event.is_set():
+                now = time.time()
+                # non-blocking poll of raw watcher events
+                new = self.watcher.get_all_changes(timeout=0)
+                if new:
+                    self._buffer.extend(new)
+                    self._last_time = now
+                    self.last_event_time = now
+
+                # if buffer exists and debounce interval elapsed, flush it
+                if self._buffer and (now - self._last_time) > self.debounce_seconds:
+                    batch = sorted(set(self._buffer))
+                    self._buffer.clear()
+                    self._last_time = now
+                    self._out_queue.put(batch)
+
+                time.sleep(0.1)
+        except KeyboardInterrupt:
+            _thread.interrupt_main()
+            raise
+
+    def get_all_changes(self, timeout: float | None = None) -> list[str]:
+        """
+        Return the next debounced batch of paths, or [] if none arrives
+        within `timeout` seconds.
+        """
+        try:
+            if timeout is None:
+                # non-blocking
+                return self._out_queue.get_nowait()
+            else:
+                return self._out_queue.get(timeout=timeout)
+        except queue.Empty:
+            return []
+
+    def stop(self) -> None:
+        """Stop the polling thread and tear down the underlying watcher."""
+        self._stop_event.set()
+        self.join()
+        self.watcher.stop()

fastled/find_good_connection.py

@@ -0,0 +1,105 @@
+import _thread
+import time
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from typing import Dict, Tuple
+
+import httpx
+
+_TIMEOUT = 30.0
+
+_EXECUTOR = ThreadPoolExecutor(max_workers=8)
+
+# In-memory cache for connection results
+# Key: (tuple of urls, filter_out_bad, use_ipv6)
+# Value: (ConnectionResult | None, timestamp)
+_CONNECTION_CACHE: Dict[
+    Tuple[tuple, bool, bool], Tuple["ConnectionResult | None", float]
+] = {}
+_CACHE_TTL = 60.0 * 60.0  # Cache results for 1 hour
+
+
+@dataclass
+class ConnectionResult:
+    host: str
+    success: bool
+    ipv4: bool
+
+
+def _sanitize_host(host: str) -> str:
+    if host.startswith("http"):
+        return host
+    is_local_host = "localhost" in host or "127.0.0.1" in host or "0.0.0.0" in host
+    use_https = not is_local_host
+    if use_https:
+        return host if host.startswith("https://") else f"https://{host}"
+    return host if host.startswith("http://") else f"http://{host}"
+
+
+def _test_connection(host: str, use_ipv4: bool) -> ConnectionResult:
+    # Function static cache
+    host = _sanitize_host(host)
+    transport = httpx.HTTPTransport(local_address="0.0.0.0") if use_ipv4 else None
+    result: ConnectionResult | None = None
+    try:
+        with httpx.Client(
+            timeout=_TIMEOUT,
+            transport=transport,
+        ) as test_client:
+            test_response = test_client.get(
+                f"{host}/healthz", timeout=3, follow_redirects=True
+            )
+            result = ConnectionResult(host, test_response.status_code == 200, use_ipv4)
+    except KeyboardInterrupt:
+        _thread.interrupt_main()
+        result = ConnectionResult(host, False, use_ipv4)
+    except TimeoutError:
+        result = ConnectionResult(host, False, use_ipv4)
+    except Exception:
+        result = ConnectionResult(host, False, use_ipv4)
+    return result
+
+
+def find_good_connection(
+    urls: list[str], filter_out_bad=True, use_ipv6: bool = True
+) -> ConnectionResult | None:
+    # Create cache key from parameters
+    cache_key = (tuple(sorted(urls)), filter_out_bad, use_ipv6)
+    current_time = time.time()
+
+    # Check if we have a cached result
+    if cache_key in _CONNECTION_CACHE:
+        cached_result, cached_time = _CONNECTION_CACHE[cache_key]
+        if current_time - cached_time < _CACHE_TTL:
+            return cached_result
+        else:
+            # Remove expired cache entry
+            del _CONNECTION_CACHE[cache_key]
+
+    # No valid cache entry, perform the actual connection test
+    futures: list[Future] = []
+    for url in urls:
+
+        f = _EXECUTOR.submit(_test_connection, url, use_ipv4=True)
+        futures.append(f)
+        if use_ipv6 and "localhost" not in url:
+            f_v6 = _EXECUTOR.submit(_test_connection, url, use_ipv4=False)
+            futures.append(f_v6)
+
+    result = None
+    try:
+        # Return first successful result
+        for future in as_completed(futures):
+            connection_result: ConnectionResult = future.result()
+            if connection_result.success or not filter_out_bad:
+                result = connection_result
+                break
+    finally:
+        # Cancel any remaining futures
+        for future in futures:
+            future.cancel()
+
+    # Cache the result (even if None)
+    _CONNECTION_CACHE[cache_key] = (result, current_time)
+
+    return result

fastled/header_dump.py

@@ -0,0 +1,63 @@
+"""Header dump functionality for EMSDK headers export."""
+
+import sys
+from pathlib import Path
+
+
+def dump_emsdk_headers(output_path: Path | str, server_url: str | None = None) -> None:
+    """
+    Dump EMSDK headers to a specified path.
+
+    Args:
+        output_path: Path where to save the headers ZIP file
+        server_url: URL of the server. If None, tries to create local server first,
+                   then falls back to remote server if local fails.
+    """
+    from fastled import Api
+    from fastled.settings import DEFAULT_URL
+    from fastled.util import download_emsdk_headers
+
+    # Convert to Path if string
+    if isinstance(output_path, str):
+        output_path = Path(output_path)
+
+    ends_with_zip = output_path.suffix == ".zip"
+    if not ends_with_zip:
+        raise ValueError(f"{output_path} must end with .zip")
+
+    try:
+        if server_url is not None:
+            # Use the provided server URL
+            download_emsdk_headers(server_url, output_path)
+            print(f"SUCCESS: EMSDK headers exported to {output_path}")
+        else:
+            # Try to create local server first
+            try:
+                with Api.server() as server:
+                    base_url = server.url()
+                    download_emsdk_headers(base_url, output_path)
+                    print(
+                        f"SUCCESS: EMSDK headers exported to {output_path} (using local server)"
+                    )
+            except Exception as local_error:
+                print(
+                    f"WARNING: Local server failed ({local_error}), falling back to remote server"
+                )
+                # Fall back to remote server
+                download_emsdk_headers(DEFAULT_URL, output_path)
+                print(
+                    f"SUCCESS: EMSDK headers exported to {output_path} (using remote server)"
+                )
+
+    except Exception as e:
+        print(f"ERROR: Exception during header dump: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python -m fastled.header_dump <output_path>")
+        sys.exit(1)
+
+    output_path = sys.argv[1]
+    dump_emsdk_headers(output_path)

fastled/install/__init__.py

@@ -0,0 +1 @@
+"""FastLED install module."""

fastled/install/examples_manager.py

@@ -0,0 +1,62 @@
+"""Examples installation manager using FastLED's built-in --project-init command."""
+
+import subprocess
+
+
+def install_fastled_examples_via_project_init(
+    force: bool = False, no_interactive: bool = False
+) -> bool:
+    """
+    Install FastLED examples using built-in --project-init command.
+
+    Args:
+        force: If True, install without prompting
+        no_interactive: If True, skip prompting and return False
+
+    Returns:
+        True if installation successful, False otherwise
+    """
+    if not force:
+        if no_interactive:
+            print("⚠️  No existing Arduino content found.")
+            print("    In non-interactive mode, skipping examples installation.")
+            print("    Run 'fastled --project-init' manually to install examples.")
+            return False
+
+        print("No existing Arduino content found.")
+        answer = (
+            input("Would you like to install FastLED examples? [y/n] ").strip().lower()
+        )
+        if answer not in ["y", "yes"]:
+            print("Skipping FastLED examples installation.")
+            return False
+
+    print("📦 Installing FastLED examples using project initialization...")
+
+    try:
+        # Use FastLED's built-in project initialization
+        subprocess.run(
+            ["fastled", "--project-init"],
+            check=True,
+            capture_output=True,
+            text=True,
+            cwd=".",
+        )
+
+        print("✅ FastLED project initialized successfully!")
+        print("📁 Examples and project structure created")
+        print("🚀 Quick start: Check for generated .ino files and press F5 to debug")
+
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"⚠️  Warning: Failed to initialize FastLED project: {e}")
+        if e.stderr:
+            print(f"Error details: {e.stderr}")
+        print("You can manually run: fastled --project-init")
+        return False
+    except FileNotFoundError:
+        print("⚠️  Warning: FastLED package not found. Please install it first:")
+        print("    pip install fastled")
+        print("Then run: fastled --project-init")
+        return False

fastled/install/extension_manager.py

@@ -0,0 +1,113 @@
+"""Auto Debug extension installation manager."""
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from urllib.request import urlretrieve
+
+
+def download_auto_debug_extension() -> Path | None:
+    """
+    Download the Auto Debug extension .vsix file from GitHub.
+
+    Returns:
+        Path to downloaded .vsix file, or None if download fails
+    """
+    # URL for the Auto Debug extension
+    extension_url = "https://github.com/zackees/vscode-auto-debug/releases/latest/download/auto-debug.vsix"
+
+    try:
+        # Create temporary directory
+        temp_dir = Path(tempfile.mkdtemp())
+        vsix_path = temp_dir / "auto-debug.vsix"
+
+        print("📥 Downloading Auto Debug extension...")
+
+        # Download the file
+        urlretrieve(extension_url, vsix_path)
+
+        if vsix_path.exists() and vsix_path.stat().st_size > 0:
+            print("✅ Extension downloaded successfully")
+            return vsix_path
+        else:
+            print("❌ Failed to download extension")
+            return None
+
+    except Exception as e:
+        print(f"❌ Error downloading extension: {e}")
+        return None
+
+
+def install_vscode_extensions(extension_path: Path) -> bool:
+    """
+    Install extension in VSCode or Cursor.
+
+    Args:
+        extension_path: Path to .vsix file
+
+    Returns:
+        True if installation successful, False otherwise
+    """
+    # Try VSCode first
+    if shutil.which("code"):
+        ide_command = "code"
+        ide_name = "VSCode"
+    elif shutil.which("cursor"):
+        ide_command = "cursor"
+        ide_name = "Cursor"
+    else:
+        print("❌ No supported IDE found (VSCode or Cursor)")
+        return False
+
+    try:
+        print(f"📦 Installing extension in {ide_name}...")
+
+        # Install the extension
+        subprocess.run(
+            [ide_command, "--install-extension", str(extension_path)],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+
+        print(f"✅ Auto Debug extension installed in {ide_name}")
+        return True
+
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Failed to install extension: {e}")
+        if e.stderr:
+            print(f"Error details: {e.stderr}")
+        return False
+    finally:
+        # Clean up temporary file
+        if extension_path.exists():
+            try:
+                extension_path.unlink()
+                extension_path.parent.rmdir()
+            except Exception:
+                pass
+
+
+def install_auto_debug_extension(dry_run: bool = False) -> bool:
+    """
+    Main function to download and install Auto Debug extension.
+
+    Args:
+        dry_run: If True, simulate installation without actually installing
+
+    Returns:
+        True if installation successful, False otherwise
+    """
+    if dry_run:
+        print("[DRY-RUN]: Would download and install Auto Debug extension")
+        print("[DRY-RUN]: NO PLUGIN INSTALLED")
+        return True
+
+    # Download extension
+    vsix_path = download_auto_debug_extension()
+    if not vsix_path:
+        return False
+
+    # Install extension
+    return install_vscode_extensions(vsix_path)

fastled/install/main.py

@@ -0,0 +1,156 @@
+"""Main installation orchestrator for FastLED --install feature."""
+
+import sys
+
+from .examples_manager import install_fastled_examples_via_project_init
+from .extension_manager import install_auto_debug_extension
+from .project_detection import (
+    check_existing_arduino_content,
+    detect_fastled_project,
+    is_fastled_repository,
+    validate_vscode_project,
+)
+from .vscode_config import (
+    generate_fastled_tasks,
+    update_launch_json_for_arduino,
+    update_vscode_settings_for_fastled,
+)
+
+
+def fastled_install(dry_run: bool = False, no_interactive: bool = False) -> bool:
+    """
+    Main installation function with dry-run support.
+
+    Args:
+        dry_run: If True, simulate installation without making changes
+        no_interactive: If True, fail instead of prompting for input
+
+    Returns:
+        True if installation successful, False otherwise
+    """
+    try:
+        print("🚀 Starting FastLED installation...")
+
+        # 1. Validate VSCode project or offer alternatives
+        if not validate_vscode_project(no_interactive):
+            return False
+
+        # 2. Detect project type
+        is_fastled_project = detect_fastled_project()
+        is_repository = is_fastled_repository()
+
+        if is_fastled_project:
+            if is_repository:
+                print(
+                    "✅ Detected FastLED repository - will configure full development environment"
+                )
+            else:
+                print(
+                    "✅ Detected external FastLED project - will configure Arduino environment"
+                )
+        else:
+            print(
+                "✅ Detected standard project - will configure basic Arduino environment"
+            )
+
+        # 3. Auto Debug extension (with prompt)
+        if not dry_run and not no_interactive:
+            answer = (
+                input(
+                    "\nWould you like to install the plugin for FastLED (auto-debug)? [y/n] "
+                )
+                .strip()
+                .lower()
+            )
+        elif no_interactive:
+            print(
+                "\n⚠️  Skipping Auto Debug extension installation in non-interactive mode"
+            )
+            answer = "no"
+        else:
+            answer = "yes"
+            print("\n[DRY-RUN]: Simulating Auto Debug extension installation...")
+
+        if answer in ["y", "yes"]:
+            if not install_auto_debug_extension(dry_run):
+                print(
+                    "⚠️  Warning: Auto Debug extension installation failed, continuing..."
+                )
+
+        # 4. Configure VSCode files
+        print("\n📝 Configuring VSCode files...")
+        update_launch_json_for_arduino()
+        generate_fastled_tasks()
+
+        # 5. Examples installation (conditional)
+        if not check_existing_arduino_content():
+            if no_interactive:
+                print(
+                    "⚠️  No Arduino content found. In non-interactive mode, skipping examples installation."
+                )
+                print("    Run 'fastled --project-init' manually to install examples.")
+            else:
+                install_fastled_examples_via_project_init(no_interactive=no_interactive)
+        else:
+            print(
+                "✅ Existing Arduino content detected, skipping examples installation"
+            )
+
+        # 6. Full development setup (repository only)
+        if is_fastled_project:
+            if is_repository:
+                print("\n🔧 Setting up FastLED development environment...")
+                update_vscode_settings_for_fastled()
+            else:
+                print(
+                    "\n⚠️  Skipping clangd settings - not in FastLED repository (protects your environment)"
+                )
+
+        # 7. Post-installation auto-execution
+        if not dry_run:
+            auto_execute_fastled()
+        else:
+            print("\n[DRY-RUN]: Skipping auto-execution")
+
+        print("\n✅ FastLED installation completed successfully!")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ Installation failed: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return False
+
+
+def auto_execute_fastled() -> None:
+    """Auto-launch fastled after successful installation."""
+    if check_existing_arduino_content():
+        print("\n🚀 Auto-launching FastLED...")
+
+        # Import the main function to avoid circular imports
+        from fastled.app import main
+
+        # Filter out --install and --dry-run from sys.argv
+        original_argv = sys.argv.copy()
+        filtered_argv = [
+            arg for arg in sys.argv if arg not in ["--install", "--dry-run"]
+        ]
+
+        # If no directory specified, add current directory
+        if len(filtered_argv) == 1:  # Only the command name
+            filtered_argv.append(".")
+
+        # Replace sys.argv temporarily
+        sys.argv = filtered_argv
+
+        try:
+            # Call main directly
+            main()
+        finally:
+            # Restore original argv
+            sys.argv = original_argv
+    else:
+        print(
+            "\n💡 No Arduino content found. Create some .ino files and run 'fastled' to compile!"
+        )