huggingface_hub v2.3.0 week: how I fixed a Windows crash in hf cache verify

说明与用途

在 Windows 上，hf cache verify 在将输出重定向到管道或文件时因 ❌ 表情符号无法在 cp1252 编码中表示而崩溃。通过 _ascii_safe 将其替换为 [FAIL]，修复了此问题，恢复了正确的输出和退出代码。

问题

On Windows, the hf cache verify command crashed when its output contained the ❌ emoji and was redirected to a pipe or file, because the terminal encoding (UTF‑8) differed from the pipe encoding (cp1252) which cannot represent the emoji.

结果

The patch replaces the ❌ emoji with [FAIL] when stdout cannot encode it, restoring correct output to pipes and CI logs on Windows while keeping the same exit behavior.

工作流

• 1. Reproduce the crash by running hf cache verify with output piped on Windows.
• 2. Identify that the crash is due to cp1252 encoding lacking the ❌ emoji.
• 3. Locate the _ascii_safe helper in cli/_output.py and understand its fallback mechanism.
• 4. Add a call to _ascii_safe("❌", "[FAIL]") in cli/cache.py to replace the emoji with a safe fallback.
• 5. Run regression tests with CliRunner(charset="cp1252") to confirm the bug is fixed.
• 6. Submit a PR (#5255) with the change and regression test.
• 7. Review and merge the PR on October 27, 2026.
• 8. Verify that the command now outputs [FAIL] and the list of bad files when piped.
• 9. Optionally set PYTHONUTF8=1 to force UTF‑8 stdout if using an older release.

证据

On Windows, Python writes to a terminal in UTF-8 but to a pipe, a file or a CI log in the old ANSI code page, cp1252.

来源

The fix prints [FAIL] when the stream cannot encode the emoji.

来源

After #5255 the command asks _ascii_safe whether stdout can encode ❌ before printing.

来源

The same pipe now prints the report, and the exit code is still 1:

来源