chore: import upstream snapshot with attribution

.pre-commit-hooks/check-open-encoding.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+Pre-commit hook to enforce explicit ``encoding=`` on text-mode file I/O calls.
+
+On Windows the default encoding is the system locale (often cp1252), not UTF-8.
+Omitting ``encoding`` causes silent failures or ``UnicodeDecodeError`` when
+reading/writing UTF-8 files.  See issue #3743.
+
+Detects:
+  * Bare ``open(...)`` — second positional arg is the mode.
+  * ``<expr>.open(<mode>, ...)`` — only when the first positional arg is a
+    constant string that looks like a real file mode (avoids false positives
+    on ``tarfile.open`` / ``zipfile.open`` etc., which take a path first).
+  * ``<expr>.read_text(...)`` and ``<expr>.write_text(...)`` — these are
+    effectively pathlib-only, so any bare call without ``encoding=`` is flagged.
+"""
+
+import ast
+import sys
+from pathlib import Path
+
+_FILE_MODE_CHARS = frozenset("rwxabt+")
+
+
+def _looks_like_file_mode(value: object) -> bool:
+    """True if value is a string that plausibly is a file ``open`` mode."""
+    return (
+        isinstance(value, str)
+        and 0 < len(value) <= 3
+        and set(value) <= _FILE_MODE_CHARS
+    )
+
+
+def _has_encoding_keyword(call: ast.Call) -> bool:
+    """True if the call has an explicit ``encoding=`` kwarg.
+
+    Treats ``**kwargs`` spreads as "may contain encoding" to avoid false
+    positives — we can't statically prove the spread doesn't supply it.
+    """
+    for kw in call.keywords:
+        if kw.arg is None:  # **kwargs spread
+            return True
+        if kw.arg == "encoding":
+            return True
+    return False
+
+
+def _get_mode_arg(call: ast.Call, positional_index: int) -> ast.expr | None:
+    """Return the mode AST node, looking at both positional and ``mode=`` kwarg.
+
+    Returns None if no mode was supplied (caller defaults to text mode).
+    """
+    if len(call.args) > positional_index:
+        return call.args[positional_index]
+
+    for kw in call.keywords:
+        if kw.arg == "mode":
+            return kw.value
+
+    return None
+
+
+def _is_text_mode_at(call: ast.Call, mode_arg_index: int) -> bool | None:
+    """Return True if the mode argument is text mode.
+
+    Inspects both the positional slot and the ``mode=`` kwarg, so calls like
+    ``open(f, mode="rb")`` are correctly classified as binary even though the
+    positional slot is empty.
+
+    Returns ``None`` (falsy) when the mode can't be determined statically —
+    e.g. ``open(filepath, mode)`` where ``mode`` is a variable.
+    """
+    mode_arg = _get_mode_arg(call, mode_arg_index)
+    if mode_arg is None:
+        return True  # default mode is "r" (text)
+
+    if not isinstance(mode_arg, ast.Constant):
+        return None
+
+    return "b" not in str(mode_arg.value)
+
+
+def _violations_for_call(node: ast.Call) -> list[tuple[int, str]]:
+    func = node.func
+
+    # Bare open(...) — second positional arg is mode.
+    if isinstance(func, ast.Name) and func.id == "open":
+        if _is_text_mode_at(node, 1) and not _has_encoding_keyword(node):
+            return [(node.lineno, "open() called without explicit encoding=")]
+        return []
+
+    if not isinstance(func, ast.Attribute):
+        return []
+
+    attr = func.attr
+
+    # Path.read_text() / Path.write_text() — encoding= is the only safe option.
+    if attr in {"read_text", "write_text"}:
+        if not _has_encoding_keyword(node):
+            return [
+                (
+                    node.lineno,
+                    f".{attr}() called without explicit encoding=",
+                )
+            ]
+        return []
+
+    # <expr>.open(<mode>, ...) — first positional arg is the mode (or mode= kwarg).
+    # When the mode looks like a file mode (or is omitted entirely, defaulting
+    # to "r"), flag missing encoding. The mode-shape filter avoids false
+    # positives on tarfile.open("foo.tar") / zipfile.ZipFile.open("inner") etc.
+    # — bare ``.open()`` is the same gap that bare ``open(f)`` already catches.
+    if attr == "open":
+        mode_arg = _get_mode_arg(node, 0)
+        flag = False
+        if mode_arg is None:
+            flag = True  # defaults to "r" — same risk as bare open(f)
+        elif isinstance(mode_arg, ast.Constant) and _looks_like_file_mode(
+            mode_arg.value
+        ):
+            flag = "b" not in mode_arg.value
+        if flag and not _has_encoding_keyword(node):
+            return [
+                (
+                    node.lineno,
+                    ".open() called without explicit encoding=",
+                )
+            ]
+
+    return []
+
+
+def check_file(file_path: str) -> list[tuple[int, str]]:
+    path = Path(file_path)
+    if path.suffix != ".py":
+        return []
+
+    try:
+        source = path.read_text(encoding="utf-8")
+    except Exception:
+        return []
+
+    try:
+        tree = ast.parse(source, filename=file_path)
+    except SyntaxError:
+        return []
+
+    violations: list[tuple[int, str]] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            violations.extend(_violations_for_call(node))
+
+    return violations
+
+
+def main() -> int:
+    exit_code = 0
+
+    for file_path in sys.argv[1:]:
+        violations = check_file(file_path)
+        for lineno, message in violations:
+            print(f"{file_path}:{lineno}: {message}")
+            exit_code = 1
+
+    if exit_code:
+        print()
+        print(
+            "Hint: add encoding='utf-8' (or 'utf-8-sig' for JSON config files)"
+        )
+        print(
+            "      to all text-mode open() / Path.open() / read_text() / write_text() calls."
+        )
+        print("      See issue #3743.")
+
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())