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

fastled/client_server.py

@@ -1,4 +1,5 @@
 import shutil
+import sys
 import tempfile
 import threading
 import time
@@ -9,7 +10,9 @@ from pathlib import Path
 
 from fastled.compile_server import CompileServer
 from fastled.docker_manager import DockerManager
+from fastled.emoji_util import EMO
 from fastled.filewatcher import DebouncedFileWatcherProcess, FileWatcherProcess
+from fastled.find_good_connection import ConnectionResult
 from fastled.keyboard import SpaceBarWatcher
 from fastled.open_browser import spawn_http_server
 from fastled.parse_args import Args
@@ -18,7 +21,6 @@ from fastled.sketch import looks_like_sketch_directory
 from fastled.types import BuildMode, CompileResult, CompileServerError
 from fastled.web_compile import (
     SERVER_PORT,
-    ConnectionResult,
     find_good_connection,
     web_compile,
 )
@@ -67,7 +69,20 @@ def TEST_BEFORE_COMPILE(url) -> None:
 def _chunked_print(stdout: str) -> None:
     lines = stdout.splitlines()
     for line in lines:
-        print(line)
+        try:
+            print(line)
+        except UnicodeEncodeError:
+            # On Windows, the console may not support Unicode characters
+            # Try to encode the line with the console's encoding and replace problematic characters
+            try:
+                console_encoding = sys.stdout.encoding or "utf-8"
+                encoded_line = line.encode(console_encoding, errors="replace").decode(
+                    console_encoding
+                )
+                print(encoded_line)
+            except Exception:
+                # If all else fails, just print the line without problematic characters
+                print(line.encode("ascii", errors="replace").decode("ascii"))
 
 
 def _run_web_compiler(
@@ -76,12 +91,26 @@ def _run_web_compiler(
     build_mode: BuildMode,
     profile: bool,
     last_hash_value: str | None,
+    no_platformio: bool = False,
+    allow_libcompile: bool = False,
 ) -> CompileResult:
+    # Remove the import and libcompile detection logic from here
+    # since it will now be passed as a parameter
     input_dir = Path(directory)
     output_dir = input_dir / "fastled_js"
+
+    # Guard: libfastled compilation requires volume source mapping
+    if not allow_libcompile:
+        print(f"{EMO('⚠️', 'WARNING:')}  libfastled compilation disabled.")
+
     start = time.time()
     web_result = web_compile(
-        directory=input_dir, host=host, build_mode=build_mode, profile=profile
+        directory=input_dir,
+        host=host,
+        build_mode=build_mode,
+        profile=profile,
+        no_platformio=no_platformio,
+        allow_libcompile=allow_libcompile,
     )
     diff = time.time() - start
     if not web_result.success:
@@ -94,14 +123,59 @@ def _run_web_compiler(
         (output_dir / "index.html").write_text(error_html, encoding="utf-8")
         return web_result
 
+    # Extract zip contents to fastled_js directory
+    extraction_start_time = time.time()
+    output_dir.mkdir(exist_ok=True)
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+        temp_zip = temp_path / "result.zip"
+        temp_zip.write_bytes(web_result.zip_bytes)
+
+        # Clear existing contents
+        shutil.rmtree(output_dir, ignore_errors=True)
+        output_dir.mkdir(exist_ok=True)
+
+        # Extract zip contents
+        shutil.unpack_archive(temp_zip, output_dir, "zip")
+    extraction_time = time.time() - extraction_start_time
+
     def print_results() -> None:
         hash_value = (
             web_result.hash_value
             if web_result.hash_value is not None
             else "NO HASH VALUE"
         )
+
+        # Build timing breakdown
+        timing_breakdown = f"  Time: {diff:.2f} (seconds)"
+        if hasattr(web_result, "zip_time"):
+            timing_breakdown += f"\n     zip creation: {web_result.zip_time:.2f}"
+            if web_result.libfastled_time > 0:
+                timing_breakdown += (
+                    f"\n     libfastled: {web_result.libfastled_time:.2f}"
+                )
+            timing_breakdown += (
+                f"\n     sketch compile + link: {web_result.sketch_time:.2f}"
+            )
+            if hasattr(web_result, "response_processing_time"):
+                timing_breakdown += f"\n     response processing: {web_result.response_processing_time:.2f}"
+
+            # Calculate any unaccounted time
+            accounted_time = (
+                web_result.zip_time
+                + web_result.libfastled_time
+                + web_result.sketch_time
+                + web_result.response_processing_time
+                + extraction_time
+            )
+            unaccounted_time = diff - accounted_time
+            if extraction_time > 0.01:
+                timing_breakdown += f"\n     extraction: {extraction_time:.2f}"
+            if unaccounted_time > 0.01:
+                timing_breakdown += f"\n     other overhead: {unaccounted_time:.2f}"
+
         print(
-            f"\nWeb compilation successful\n  Time: {diff:.2f}\n  output: {output_dir}\n  hash: {hash_value}\n  zip size: {len(web_result.zip_bytes)} bytes"
+            f"\nWeb compilation successful\n{timing_breakdown}\n  output: {output_dir}\n  hash: {hash_value}\n  zip size: {len(web_result.zip_bytes)} bytes"
         )
 
     # now check to see if the hash value is the same as the last hash value
@@ -110,27 +184,17 @@ def _run_web_compiler(
         print_results()
         return web_result
 
-    # Extract zip contents to fastled_js directory
-    output_dir.mkdir(exist_ok=True)
-    with tempfile.TemporaryDirectory() as temp_dir:
-        temp_path = Path(temp_dir)
-        temp_zip = temp_path / "result.zip"
-        temp_zip.write_bytes(web_result.zip_bytes)
-
-        # Clear existing contents
-        shutil.rmtree(output_dir, ignore_errors=True)
-        output_dir.mkdir(exist_ok=True)
-
-        # Extract zip contents
-        shutil.unpack_archive(temp_zip, output_dir, "zip")
-
     _chunked_print(web_result.stdout)
     print_results()
     return web_result
 
 
 def _try_start_server_or_get_url(
-    auto_update: bool, args_web: str | bool, localhost: bool, clear: bool
+    auto_update: bool,
+    args_web: str | bool,
+    localhost: bool,
+    clear: bool,
+    no_platformio: bool = False,
 ) -> tuple[str, CompileServer | None]:
     is_local_host = localhost or (
         isinstance(args_web, str)
@@ -140,9 +204,9 @@ def _try_start_server_or_get_url(
     local_host_needs_server = False
     if is_local_host:
         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}")
+            addr = f"{addr}:{SERVER_PORT}"
+        urls = [addr]
 
         result: ConnectionResult | None = find_good_connection(urls)
         if result is not None:
@@ -161,7 +225,9 @@ def _try_start_server_or_get_url(
         try:
             print("No local server found, starting one...")
             compile_server = CompileServer(
-                auto_updates=auto_update, remove_previous=clear
+                auto_updates=auto_update,
+                remove_previous=clear,
+                no_platformio=no_platformio,
             )
             print("Waiting for the local compiler to start...")
             if not compile_server.ping():
@@ -177,7 +243,9 @@ def _try_start_server_or_get_url(
             return (DEFAULT_URL, None)
 
 
-def _try_make_compile_server(clear: bool = False) -> CompileServer | None:
+def _try_make_compile_server(
+    clear: bool = False, no_platformio: bool = False
+) -> CompileServer | None:
     if not DockerManager.is_docker_installed():
         return None
     try:
@@ -189,7 +257,9 @@ def _try_make_compile_server(clear: bool = False) -> CompileServer | None:
         free_port = find_free_port(start_port=9723, end_port=9743)
         if free_port is None:
             return None
-        compile_server = CompileServer(auto_updates=False, remove_previous=clear)
+        compile_server = CompileServer(
+            auto_updates=False, remove_previous=clear, no_platformio=no_platformio
+        )
         print("Waiting for the local compiler to start...")
         if not compile_server.ping():
             print("Failed to start local compiler.")
@@ -205,14 +275,41 @@ def _try_make_compile_server(clear: bool = False) -> CompileServer | None:
         return None
 
 
-def _is_local_host(host: str) -> bool:
+def _background_update_docker_image() -> None:
+    """Perform docker image update in the background silently."""
+    try:
+        # Only attempt update if Docker is installed and running
+        if not DockerManager.is_docker_installed():
+            return
+
+        docker_manager = DockerManager()
+        docker_running, _ = docker_manager.is_running()
+        if not docker_running:
+            return
+
+        # Silently update the docker image
+        docker_manager.validate_or_download_image(
+            image_name=IMAGE_NAME, tag="latest", upgrade=True
+        )
+    except KeyboardInterrupt:
+        import _thread
+
+        _thread.interrupt_main()
+    except Exception as e:
+        # Log warning but don't disrupt user experience
+        import warnings
+
+        warnings.warn(f"Background docker image update failed: {e}")
+
+
+def _is_local_host(url: str) -> bool:
     return (
-        host.startswith("http://localhost")
-        or host.startswith("http://127.0.0.1")
-        or host.startswith("http://0.0.0.0")
-        or host.startswith("http://[::]")
-        or host.startswith("http://[::1]")
-        or host.startswith("http://[::ffff:127.0.0.1]")
+        url.startswith("http://localhost")
+        or url.startswith("http://127.0.0.1")
+        or url.startswith("http://0.0.0.0")
+        or url.startswith("http://[::]")
+        or url.startswith("http://[::1]")
+        or url.startswith("http://[::ffff:127.0.0.1]")
     )
 
 
@@ -228,13 +325,19 @@ def run_client(
         int | None
     ) = None,  # None means auto select a free port, http_port < 0 means no server.
     clear: bool = False,
+    no_platformio: bool = False,
+    app: bool = False,  # Use app-like browser experience
+    background_update: bool = False,
+    enable_https: bool = True,  # Enable HTTPS for the local server
 ) -> int:
     has_checked_newer_version_yet = False
     compile_server: CompileServer | None = None
 
     if host is None:
         # attempt to start a compile server if docker is installed.
-        compile_server = _try_make_compile_server(clear=clear)
+        compile_server = _try_make_compile_server(
+            clear=clear, no_platformio=no_platformio
+        )
         if compile_server is None:
             host = DEFAULT_URL
     elif isinstance(host, CompileServer):
@@ -267,6 +370,11 @@ def run_client(
         # Assume default port for www
         port = 80
 
+    # Auto-detect libcompile capability on first call
+    from fastled.sketch import looks_like_fastled_repo
+
+    allow_libcompile = is_local_host and looks_like_fastled_repo(Path(".").resolve())
+
     try:
 
         def compile_function(
@@ -274,6 +382,8 @@ def run_client(
             build_mode: BuildMode = build_mode,
             profile: bool = profile,
             last_hash_value: str | None = None,
+            no_platformio: bool = no_platformio,
+            allow_libcompile: bool = allow_libcompile,
         ) -> CompileResult:
             TEST_BEFORE_COMPILE(url)
             return _run_web_compiler(
@@ -282,6 +392,8 @@ def run_client(
                 build_mode=build_mode,
                 profile=profile,
                 last_hash_value=last_hash_value,
+                no_platformio=no_platformio,
+                allow_libcompile=allow_libcompile,
             )
 
         result: CompileResult = compile_function(last_hash_value=None)
@@ -304,13 +416,18 @@ def run_client(
                 port=http_port,
                 compile_server_port=port,
                 open_browser=open_web_browser,
+                app=app,
+                enable_https=enable_https,
             )
         else:
-            print("\nCompilation successful.")
+            if result.success:
+                print("\nCompilation successful.")
+            else:
+                print("\nCompilation failed.")
             if compile_server:
                 print("Shutting down compile server...")
                 compile_server.stop()
-            return 0
+            return 0 if result.success else 1
 
         if not keep_running or shutdown.is_set():
             if http_proc:
@@ -337,7 +454,15 @@ def run_client(
     ) -> tuple[bool, CompileResult]:
         changed_files = debounced_sketch_watcher.get_all_changes()
         if changed_files:
-            print(f"\nChanges detected in {changed_files}")
+            # Filter out any fastled_js changes that slipped through
+            sketch_changes = [
+                f for f in changed_files if "fastled_js" not in Path(f).parts
+            ]
+            if not sketch_changes:
+                # All changes were in fastled_js, ignore them
+                return False, last_compiled_result
+            print(f"\nChanges detected in {sketch_changes}")
+            print("Compiling...")
             last_hash_value = last_compiled_result.hash_value
             out = compile_function(last_hash_value=last_hash_value)
             if not out.success:
@@ -374,9 +499,20 @@ def run_client(
                     )
                     if has_update:
                         print(f"\n🔄 {message}")
-                        print(
-                            "Run with `fastled -u` to update the docker image to the latest version."
-                        )
+                        if background_update:
+                            # Start background update in a separate thread
+                            update_thread = threading.Thread(
+                                target=_background_update_docker_image, daemon=True
+                            )
+                            update_thread.start()
+                            background_update = False
+                        else:
+                            print(
+                                "Run with `fastled -u` to update the docker image to the latest version."
+                            )
+                            print(
+                                "Or use `--background-update` to update automatically in the background after compilation."
+                            )
                 except Exception as e:
                     # Don't let Docker check failures interrupt the main flow
                     warnings.warn(f"Failed to check for Docker image updates: {e}")
@@ -408,6 +544,7 @@ def run_client(
                 if changed_files:
                     print(f"\nChanges detected in FastLED source code: {changed_files}")
                     print("Press space bar to trigger compile.")
+
                     while True:
                         space_bar_pressed = SpaceBarWatcher.watch_space_bar_pressed(
                             timeout=1.0
@@ -421,6 +558,8 @@ def run_client(
                             print(
                                 f"Changes detected in {file_changes}\nHit the space bar to trigger compile."
                             )
+                            # Re-evaluate libcompile capability when source code changes
+                            allow_libcompile = True
 
                         if space_bar_pressed or sketch_files_changed:
                             if space_bar_pressed:
@@ -430,7 +569,10 @@ def run_client(
                                     f"Changes detected in {','.join(sketch_files_changed)}, triggering recompile..."
                                 )
                             last_compiled_result = compile_function(
-                                last_hash_value=None
+                                last_hash_value=None, allow_libcompile=allow_libcompile
+                            )
+                            allow_libcompile = (
+                                allow_libcompile and not last_compiled_result.success
                             )
                             print("Finished recompile.")
                             # Drain the space bar queue
@@ -456,6 +598,7 @@ def run_client_server(args: Args) -> 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)
+    background_update = bool(args.background_update)
     localhost = bool(args.localhost)
     directory = args.directory if args.directory else Path(".")
     just_compile = bool(args.just_compile)
@@ -463,6 +606,8 @@ def run_client_server(args: Args) -> int:
     force_compile = bool(args.force_compile)
     open_web_browser = not just_compile and not interactive
     build_mode: BuildMode = BuildMode.from_args(args)
+    no_platformio = bool(args.no_platformio)
+    app = bool(args.app)
 
     if not force_compile and not looks_like_sketch_directory(directory):
         # if there is only one directory in the sketch directory, use that
@@ -492,7 +637,7 @@ def run_client_server(args: Args) -> int:
     compile_server: CompileServer | None = None
     try:
         url, compile_server = _try_start_server_or_get_url(
-            auto_update, web, localhost, args.clear
+            auto_update, web, localhost, args.clear, no_platformio
         )
     except KeyboardInterrupt:
         print("\nExiting from first try...")
@@ -524,6 +669,9 @@ def run_client_server(args: Args) -> int:
             build_mode=build_mode,
             profile=profile,
             clear=args.clear,
+            no_platformio=no_platformio,
+            app=app,
+            background_update=background_update,
         )
     except KeyboardInterrupt:
         return 1

fastled/compile_server.py

@@ -15,6 +15,8 @@ class CompileServer:
         container_name: str | None = None,
         platform: Platform = Platform.WASM,
         remove_previous: bool = False,
+        no_platformio: bool = False,
+        allow_libcompile: bool = True,
     ) -> None:
         from fastled.compile_server_impl import (  # avoid circular import
             CompileServerImpl,
@@ -29,6 +31,8 @@ class CompileServer:
             mapped_dir=mapped_dir,
             auto_start=auto_start,
             remove_previous=remove_previous,
+            no_platformio=no_platformio,
+            allow_libcompile=allow_libcompile,
         )
 
     # May throw CompileServerError if server could not be started.
@@ -97,3 +101,9 @@ class CompileServer:
 
     def process_running(self) -> bool:
         return self.impl.process_running()
+
+    def get_emsdk_headers(self, filepath: Path) -> None:
+        """Get EMSDK headers ZIP data from the server and save to filepath."""
+        if not str(filepath).endswith(".zip"):
+            raise ValueError("Filepath must end with .zip")
+        return self.impl.get_emsdk_headers(filepath)

fastled/compile_server_impl.py

@@ -15,6 +15,7 @@ from fastled.docker_manager import (
     RunningContainer,
     Volume,
 )
+from fastled.emoji_util import EMO
 from fastled.settings import DEFAULT_CONTAINER_NAME, IMAGE_NAME, SERVER_PORT
 from fastled.sketch import looks_like_fastled_repo
 from fastled.types import BuildMode, CompileResult, CompileServerError
@@ -50,6 +51,8 @@ class CompileServerImpl:
         auto_start: bool = True,
         container_name: str | None = None,
         remove_previous: bool = False,
+        no_platformio: bool = False,
+        allow_libcompile: bool = True,
     ) -> None:
         container_name = container_name or DEFAULT_CONTAINER_NAME
         if interactive and not mapped_dir:
@@ -68,6 +71,18 @@ class CompileServerImpl:
         self.running_container: RunningContainer | None = None
         self.auto_updates = auto_updates
         self.remove_previous = remove_previous
+        self.no_platformio = no_platformio
+
+        # Guard: libfastled compilation requires volume source mapping
+        # If we don't have fastled_src_dir (not in FastLED repo), disable libcompile
+        if allow_libcompile and self.fastled_src_dir is None:
+            print(
+                f"{EMO('⚠️', 'WARNING:')}  libfastled compilation disabled: volume source mapping not available"
+            )
+            print("   (not running in FastLED repository)")
+            allow_libcompile = False
+
+        self.allow_libcompile = allow_libcompile
         self._port = 0  # 0 until compile server is started
         if auto_start:
             self.start()
@@ -105,7 +120,12 @@ class CompileServerImpl:
         if not self.ping():
             raise RuntimeError("Server is not running")
         out: CompileResult = web_compile(
-            directory, host=self.url(), build_mode=build_mode, profile=profile
+            directory,
+            host=self.url(),
+            build_mode=build_mode,
+            profile=profile,
+            no_platformio=self.no_platformio,
+            allow_libcompile=self.allow_libcompile,
         )
         return out
 
@@ -217,6 +237,8 @@ class CompileServerImpl:
             server_command = ["/bin/bash"]
         else:
             server_command = ["python", "/js/run.py", "server"] + SERVER_OPTIONS
+            if self.no_platformio:
+                server_command.append("--no-platformio")
         if self.interactive:
             print("Disabling port forwarding in interactive mode")
             ports = {}
@@ -316,3 +338,14 @@ class CompileServerImpl:
         self.docker.suspend_container(self.container_name)
         self._port = 0
         print("Compile server stopped")
+
+    def get_emsdk_headers(self, filepath: Path) -> None:
+        """Get EMSDK headers ZIP data from the server and save to filepath."""
+        from fastled.util import download_emsdk_headers
+
+        if not self._port:
+            raise RuntimeError("Server has not been started yet")
+        if not self.ping():
+            raise RuntimeError("Server is not running")
+
+        download_emsdk_headers(self.url(), filepath)

fastled/docker_manager.py

@@ -26,7 +26,6 @@ from docker.models.images import Image
 from filelock import FileLock
 
 from fastled.print_filter import PrintFilter, PrintFilterDefault
-from fastled.spinner import Spinner
 
 CONFIG_DIR = Path(user_data_dir("fastled", "fastled"))
 CONFIG_DIR.mkdir(parents=True, exist_ok=True)
@@ -252,7 +251,34 @@ class DockerManager:
     @property
     def client(self) -> DockerClient:
         if self._client is None:
-            self._client = docker.from_env()
+            # Retry logic for WSL startup on Windows
+            max_retries = 10
+            retry_delay = 2  # seconds
+            last_error = None
+
+            for attempt in range(max_retries):
+                try:
+                    self._client = docker.from_env()
+                    if attempt > 0:
+                        print(
+                            f"Successfully connected to Docker after {attempt + 1} attempts"
+                        )
+                    return self._client
+                except DockerException as e:
+                    last_error = e
+                    if attempt < max_retries - 1:
+                        if attempt == 0:
+                            print("Waiting for Docker/WSL to be ready...")
+                        print(
+                            f"Attempt {attempt + 1}/{max_retries} failed, retrying in {retry_delay}s..."
+                        )
+                        time.sleep(retry_delay)
+                    else:
+                        print(
+                            f"Failed to connect to Docker after {max_retries} attempts"
+                        )
+                        raise last_error
+        assert self._client is not None
         return self._client
 
     @staticmethod
@@ -507,11 +533,9 @@ class DockerManager:
                         return False
 
                     # Quick check for latest version
-                    with Spinner(f"Pulling newer version of {image_name}:{tag}..."):
-                        cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
-                        cmd_str = subprocess.list2cmdline(cmd_list)
-                        print(f"Running command: {cmd_str}")
-                        subprocess.run(cmd_list, check=True)
+                    print(f"Pulling newer version of {image_name}:{tag}...")
+                    cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
+                    subprocess.run(cmd_list, check=True)
                     print(f"Updated to newer version of {image_name}:{tag}")
                     local_image_hash = self.client.images.get(f"{image_name}:{tag}").id
                     assert local_image_hash is not None
@@ -521,12 +545,10 @@ class DockerManager:
 
             except ImageNotFound:
                 print(f"Image {image_name}:{tag} not found.")
-                with Spinner("Loading "):
-                    # We use docker cli here because it shows the download.
-                    cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
-                    cmd_str = subprocess.list2cmdline(cmd_list)
-                    print(f"Running command: {cmd_str}")
-                    subprocess.run(cmd_list, check=True)
+                print("Loading...")
+                # We use docker cli here because it shows the download.
+                cmd_list = ["docker", "pull", f"{image_name}:{tag}"]
+                subprocess.run(cmd_list, check=True)
                 try:
                     local_image = self.client.images.get(f"{image_name}:{tag}")
                     local_image_hash = local_image.id
@@ -980,6 +1002,7 @@ class DockerManager:
     def purge(self, image_name: str) -> None:
         """
         Remove all containers and images associated with the given image name.
+        Also removes FastLED containers by name pattern (including test containers).
 
         Args:
             image_name: The name of the image to purge (without tag)
@@ -990,8 +1013,27 @@ class DockerManager:
         try:
             containers = self.client.containers.list(all=True)
             for container in containers:
+                should_remove = False
+
+                # Check if container uses the specified image
                 if any(image_name in tag for tag in container.image.tags):
-                    print(f"Removing container {container.name}")
+                    should_remove = True
+                    print(
+                        f"Removing container {container.name} (uses image {image_name})"
+                    )
+
+                # Also check for FastLED container name patterns (including test containers)
+                elif any(
+                    pattern in container.name
+                    for pattern in [
+                        "fastled-wasm-container",
+                        "fastled-wasm-container-test",
+                    ]
+                ):
+                    should_remove = True
+                    print(f"Removing FastLED container {container.name}")
+
+                if should_remove:
                     container.remove(force=True)
 
         except Exception as e:

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)