Fix Windows UnicodeEncodeError during build logging and post-render.

Set PYTHONUTF8 for Quarto subprocesses, reconfigure post-render stdio to UTF-8, and fall back to UTF-8 buffer writes when the build log hits narrow console encodings.

Fixes #200

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: chriscarrollsmith

great_docs/_build_log.py

@@ -125,6 +125,26 @@ def _should_use_color() -> bool:
         return False
 
 
+def _safe_stream_write(stream, text: str, *, flush: bool = True) -> None:
+    """Write *text* to *stream*, falling back to UTF-8 bytes on encode errors."""
+    try:
+        stream.write(text)
+        if flush:
+            stream.flush()
+    except UnicodeEncodeError:
+        buffer = getattr(stream, "buffer", None)
+        if buffer is None:
+            return
+        try:
+            buffer.write(text.encode("utf-8", errors="replace"))
+            if flush:
+                buffer.flush()
+        except (BrokenPipeError, OSError):
+            pass
+    except (BrokenPipeError, OSError):
+        pass
+
+
 # ---------------------------------------------------------------------------
 # Time formatting
 # ---------------------------------------------------------------------------
@@ -282,15 +302,13 @@ def update(self, current: int) -> None:
                     return  # throttle to 1 Hz
                 self._last_draw_time = now
                 line = self._render_bar(current)
-                self.stream.write(f"\r{line}")
-                self.stream.flush()
+                _safe_stream_write(self.stream, f"\r{line}")
             else:
                 # CI mode: emit at every 10 % boundary
                 bucket = min(current * 100 // self.total, 100) // 10
                 if bucket > self._last_pct_bucket:
                     self._last_pct_bucket = bucket
-                    self.stream.write(self._render_bar_plain(current) + "\n")
-                    self.stream.flush()
+                    _safe_stream_write(self.stream, self._render_bar_plain(current) + "\n")
         except (BrokenPipeError, OSError):
             pass
 
@@ -307,8 +325,7 @@ def finish(self, summary: str | None = None) -> None:  # noqa: ARG002
             # Clear the in-place line
             try:
                 width = shutil.get_terminal_size((80, 24)).columns
-                self.stream.write("\r" + " " * width + "\r")
-                self.stream.flush()
+                _safe_stream_write(self.stream, "\r" + " " * width + "\r")
             except (BrokenPipeError, OSError):
                 pass
 
@@ -391,8 +408,7 @@ def update(self, idx: int, current: int) -> None:
             if bucket > self._ci_buckets[idx]:
                 self._ci_buckets[idx] = bucket
                 pct = bucket * 10
-                self.stream.write(f"   [..] {self._labels[idx]}  {pct:>3d}%\n")
-                self.stream.flush()
+                _safe_stream_write(self.stream, f"   [..] {self._labels[idx]}  {pct:>3d}%\n")
 
     def finish(self) -> None:
         """Clear all progress lines. Safe to call more than once."""
@@ -403,12 +419,11 @@ def finish(self) -> None:
             try:
                 width = shutil.get_terminal_size((80, 24)).columns
                 # Move up N lines and clear each
-                self.stream.write(f"\033[{self._n}A")
+                _safe_stream_write(self.stream, f"\033[{self._n}A", flush=False)
                 for _ in range(self._n):
-                    self.stream.write(" " * width + "\n")
+                    _safe_stream_write(self.stream, " " * width + "\n", flush=False)
                 # Move back up to start
-                self.stream.write(f"\033[{self._n}A\r")
-                self.stream.flush()
+                _safe_stream_write(self.stream, f"\033[{self._n}A\r")
             except (BrokenPipeError, OSError):
                 pass
 
@@ -417,7 +432,7 @@ def _redraw(self) -> None:
         try:
             if self._drawn:
                 # Move cursor up to first slot line
-                self.stream.write(f"\033[{self._n}A")
+                _safe_stream_write(self.stream, f"\033[{self._n}A", flush=False)
 
             lines = []
             width = shutil.get_terminal_size((80, 24)).columns
@@ -427,8 +442,7 @@ def _redraw(self) -> None:
                 padding = max(0, width - _display_width(line))
                 lines.append(line + " " * padding)
 
-            self.stream.write("\n".join(lines) + "\n")
-            self.stream.flush()
+            _safe_stream_write(self.stream, "\n".join(lines) + "\n")
             self._drawn = True
         except (BrokenPipeError, OSError):
             pass
@@ -505,11 +519,7 @@ def __init__(
     # -- internal helpers ---------------------------------------------------
 
     def _write(self, text: str) -> None:
-        try:
-            self.stream.write(text + "\n")
-            self.stream.flush()
-        except (BrokenPipeError, OSError):
-            pass  # never crash the build for a logging failure
+        _safe_stream_write(self.stream, text + "\n")
 
     def _pad_rail(self, inner: str, inner_plain_len: int) -> str:
         """Pad a step header *inner* string with ``━`` to fill the width."""

great_docs/assets/post-render.py

@@ -5,6 +5,25 @@
 import json
 import os
 import re
+import sys
+
+
+def _configure_stdio_for_unicode() -> None:
+    """Use UTF-8 for console output when the platform default is narrow (e.g. cp1252)."""
+    for name in ("stdout", "stderr"):
+        stream = getattr(sys, name, None)
+        if stream is None:
+            continue
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None:
+            continue
+        try:
+            reconfigure(encoding="utf-8", errors="replace")
+        except (OSError, ValueError):
+            pass
+
+
+_configure_stdio_for_unicode()
 
 # Skip post-render processing during freeze-only renders
 if os.environ.get("GD_FREEZE_ONLY"):

great_docs/core.py

@@ -1309,6 +1309,9 @@ def _get_quarto_env(self) -> dict[str, str]:
         else:
             env["PYTHONPATH"] = new_pythonpath
 
+        # Ensure Python subprocesses (e.g. post-render.py via Quarto) use UTF-8 on Windows.
+        env.setdefault("PYTHONUTF8", "1")
+
         return env
 
     def _get_package_metadata(self) -> dict:

tests/test_build_log.py

@@ -1712,6 +1712,35 @@ def flush(self):
         log = BuildLog(stream=ErrorStream(), force_color=False, width=80)
         log._write("test")  # should not raise
 
+    def test_substep_survives_cp1252_stdout(self):
+        """Issue #200: box-drawing substeps must not crash on cp1252 stdout."""
+        buffer = io.BytesIO()
+        stream = io.TextIOWrapper(buffer, encoding="cp1252", errors="strict")
+        log = BuildLog(stream=stream, force_color=False, width=80)
+        log.substep("SEO enhancements applied")
+        output = buffer.getvalue().decode("utf-8", errors="replace")
+        assert "SEO enhancements applied" in output
+
+    def test_footer_survives_cp1252_stdout(self):
+        """Issue #200: celebration emoji in footer must not crash on cp1252 stdout."""
+        buffer = io.BytesIO()
+        stream = io.TextIOWrapper(buffer, encoding="cp1252", errors="strict")
+        log = BuildLog(stream=stream, force_color=False, width=80)
+        log.footer(site_path="out/index.html")
+        output = buffer.getvalue().decode("utf-8", errors="replace")
+        assert "Site ready" in output
+        assert "Build complete" in output
+
+    def test_post_render_stdio_reconfigure_allows_emoji(self):
+        """Issue #200: post-render status prints must survive cp1252 stdout."""
+        buffer = io.BytesIO()
+        wrapper = io.TextIOWrapper(buffer, encoding="cp1252", errors="strict")
+        wrapper.reconfigure(encoding="utf-8", errors="replace")
+        print("\n🔍 Applying SEO enhancements to HTML files...", file=wrapper)
+        wrapper.flush()
+        output = buffer.getvalue().decode("utf-8", errors="replace")
+        assert "SEO enhancements" in output
+
     def test_progress_bar_survives_broken_pipe(self):
         class BrokenStream:
             def write(self, _s):

tests/test_great_docs.py

@@ -2213,6 +2213,23 @@ def test_get_quarto_env_preserves_existing_env():
         assert env["PATH"] == os.environ.get("PATH")
 
 
+def test_get_quarto_env_sets_pythonutf8():
+    """Issue #200: Quarto subprocess env enables UTF-8 mode on Windows."""
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        docs = GreatDocs(project_path=tmp_dir)
+        env = docs._get_quarto_env()
+        assert env.get("PYTHONUTF8") == "1"
+
+
+def test_get_quarto_env_preserves_existing_pythonutf8(monkeypatch):
+    """Issue #200: do not override an explicit PYTHONUTF8 value."""
+    monkeypatch.setenv("PYTHONUTF8", "0")
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        docs = GreatDocs(project_path=tmp_dir)
+        env = docs._get_quarto_env()
+        assert env["PYTHONUTF8"] == "0"
+
+
 def test_detect_dynamic_mode_returns_true_for_simple_package():
     """Test that _detect_dynamic_mode returns True for packages without cyclic aliases."""