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

fastled/filewatcher.py

@@ -22,8 +22,8 @@ _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:
@@ -122,6 +122,9 @@ class FileChangedNotifier(threading.Thread):
                 time.sleep(0.1)
         except KeyboardInterrupt:
             print("File watcher stopped by user.")
+            import _thread
+
+            _thread.interrupt_main()
         finally:
             self.stop()
 
@@ -134,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:

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!"
+        )

fastled/install/project_detection.py

@@ -0,0 +1,167 @@
+"""Project detection logic for FastLED installation."""
+
+import json
+import shutil
+from pathlib import Path
+
+
+def validate_vscode_project(no_interactive: bool = False) -> bool:
+    """
+    Validate if current directory has a VSCode project.
+    If not found, search parent directories, offer alternatives.
+    Returns True if a VSCode project is found or created.
+
+    Args:
+        no_interactive: If True, fail instead of prompting for input
+    """
+    current_dir = Path.cwd()
+
+    # Check current directory
+    if (current_dir / ".vscode").exists():
+        return True
+
+    # Search parent directories
+    parent_path = find_vscode_project_upward()
+    if parent_path:
+        if no_interactive:
+            print("❌ No .vscode directory found in current directory.")
+            print(f"   Found .vscode in parent: {parent_path}")
+            print("   In non-interactive mode, cannot change directory.")
+            print(f"   Please cd to {parent_path} and run the command again.")
+            return False
+        answer = (
+            input(f"Found a .vscode project in {parent_path}/\nInstall there? [y/n] ")
+            .strip()
+            .lower()
+        )
+        if answer in ["y", "yes"]:
+            import os
+
+            os.chdir(parent_path)
+            return True
+
+    # Check if IDE is available
+    if not (shutil.which("code") or shutil.which("cursor")):
+        print(
+            "No supported IDE found (VSCode or Cursor). Please install VSCode or Cursor first."
+        )
+        return False
+
+    # Offer to create new project
+    if no_interactive:
+        print(
+            "❌ No .vscode directory found in current directory or parent directories."
+        )
+        print("   In non-interactive mode, cannot create new project.")
+        print("   Please create a .vscode directory or run without --no-interactive.")
+        return False
+
+    print("No .vscode directory found in current directory or parent directories.")
+    answer = (
+        input(
+            "Would you like to generate a VSCode project with FastLED configuration? [y/n] "
+        )
+        .strip()
+        .lower()
+    )
+    if answer in ["y", "yes"]:
+        return generate_vscode_project()
+
+    return False
+
+
+def find_vscode_project_upward(max_levels: int = 5) -> Path | None:
+    """Search parent directories for .vscode folder."""
+    current = Path.cwd()
+
+    for _ in range(max_levels):
+        parent = current.parent
+        if parent == current:  # Reached root
+            break
+        current = parent
+        if (current / ".vscode").exists():
+            return current
+
+    return None
+
+
+def generate_vscode_project() -> bool:
+    """Create a new .vscode directory structure."""
+    vscode_dir = Path.cwd() / ".vscode"
+    vscode_dir.mkdir(exist_ok=True)
+    print(f"✅ Created .vscode directory at {vscode_dir}")
+    return True
+
+
+def detect_fastled_project() -> bool:
+    """Check if library.json contains FastLED."""
+    library_json = Path.cwd() / "library.json"
+    if not library_json.exists():
+        return False
+
+    try:
+        with open(library_json, "r") as f:
+            data = json.load(f)
+            return data.get("name") == "FastLED"
+    except (json.JSONDecodeError, KeyError):
+        return False
+
+
+def is_fastled_repository() -> bool:
+    """
+    🚨 CRITICAL: Detect actual FastLED repository.
+    Strict verification of multiple markers.
+    """
+    cwd = Path.cwd()
+
+    # Required files and directories for FastLED repository
+    required_markers = [
+        cwd / "src" / "FastLED.h",
+        cwd / "examples" / "Blink" / "Blink.ino",
+        cwd / "ci" / "ci-compile.py",
+        cwd / "src" / "platforms",
+        cwd / "library.json",
+    ]
+
+    # Check all markers exist
+    if not all(marker.exists() for marker in required_markers):
+        return False
+
+    # Verify library.json has correct content
+    try:
+        with open(cwd / "library.json", "r") as f:
+            data = json.load(f)
+            if data.get("name") != "FastLED":
+                return False
+            repo_url = data.get("repository", {}).get("url", "")
+            if "FastLED/FastLED" not in repo_url:
+                return False
+    except (json.JSONDecodeError, KeyError, FileNotFoundError):
+        return False
+
+    # Check for test files pattern
+    test_dir = cwd / "tests"
+    if test_dir.exists() and test_dir.is_dir():
+        test_files = list(test_dir.glob("test_*.cpp"))
+        if not test_files:
+            return False
+    else:
+        return False
+
+    return True
+
+
+def check_existing_arduino_content() -> bool:
+    """Check for .ino files OR examples/ folder."""
+    cwd = Path.cwd()
+
+    # Check for any .ino files
+    ino_files = list(cwd.rglob("*.ino"))
+    if ino_files:
+        return True
+
+    # Check for examples folder
+    if (cwd / "examples").exists():
+        return True
+
+    return False