Fix panic on modules declaring their encoding as e.g. latin-1

[pylaterreur]

Fixes #321.

Since 3.10, build_graph panics with TypeError('function takes exactly 5 arguments (1 given)') on:

• modules that declare their encoding with a name Python accepts but that isn't a WHATWG label, such as latin-1, latin_1, utf_8, utf-8-sig, euc_jp or iso8859_15;
• modules that can't be decoded at all.

Changes:

• RealBasicFileSystem::read normalizes the declared name like Python does (_get_normal_name in Lib/tokenize.py, and _ vs -) when encoding_rs doesn't recognize it as is. Names that encoding_rs already knows are looked up as before.
• Decoding failures are raised as UnicodeError, with the existing messages that name the file, e.g. Failed to decode file /path/to/pkg/broken.py as UTF-8: invalid utf-8 sequence of 1 bytes from index 5. Before, they were created as UnicodeDecodeError, which can't be created from a message alone.
• FileSystem::read returns Rust errors (new GrimpError::FileNotFound and GrimpError::UndecodableFile variants), which are converted to FileNotFoundError and UnicodeError where they reach Python, like the other GrimpError variants. scan_for_imports propagates them instead of unwrapping.

The new functional tests use tmp_path, as each case needs its own package: one test per encoding name above, and one per kind of decoding failure (invalid UTF-8, invalid for the declared encoding, unknown encoding).

This isn't on a hot path: names that encoding_rs knows take the same route as before, and only the error handling changed otherwise.

Encoding names that Python accepts but that still aren't WHATWG labels after normalizing, such as cp932 or mac_roman, now raise a clear UnicodeError rather than panicking. Supporting them would need a fallback to Python's codecs.

• Add tests for the change. In general, aim for full test coverage at the Python level. Rust tests are optional.
• Add any appropriate documentation. (None needed.)
• Add a summary of changes to the latest section at the top of CHANGELOG.rst. (If it's not there, add it.)
• Add your name to AUTHORS.rst.
• Run just full-check. (I ran the lint (Python, plus Rust with the pinned 1.97.0 toolchain), the docs build, cargo test, and the Python tests on 3.10 to 3.14. I didn't run them on 3.14t, 3.15 or 3.15t.)

🤖 Generated with Claude Code

https://claude.ai/code/session_01GwUvhmzgfkiZ6vo4uGyesN

[codspeed]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 23 skipped benchmarks¹

---

_{Comparing pylaterreur:fix-encoding-declarations (06db270) with main (676e490)}

Footnotes

1. 23 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[Copilot]

🟡 Changes recommended

Latin-1 aliases are incorrectly decoded as Windows-1252, producing source text that differs from Python.

1 open finding

• Use true Latin-1 decoding instead of WHATWG Windows-1252 mapping · New

What changed in this PR

Fixes import-scanning panics caused by Python encoding aliases and undecodable source files.

Changes:

• Normalizes declared encoding names and propagates decoding failures.
• Maps filesystem errors to appropriate Python exceptions.
• Adds functional coverage and release documentation.

File	Description
rust/​src/​filesystem.rs	Adds encoding normalization and structured read errors.
rust/​src/​errors.rs	Maps new errors to Python exceptions.
rust/​src/​import_scanning.rs	Propagates filesystem read failures.
tests/​functional/​test_encoding_handling.py	Tests Python-specific encoding names.
tests/​functional/​test_error_handling.py	Tests decoding failure behavior.
CHANGELOG.rst	Documents the fix.
AUTHORS.rst	Adds the contributor.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[seddonym]

Thanks for your contribution! I merged this into a different branch to make a couple of tweaks, but it's now on main.