Add --check option (#278)

CHANGELOG.rst

@@ -2,6 +2,11 @@
 Changelog
 =========
 
+* Add a `--check` option.
+  When used, blacken-docs will not modify files but indicate when changes are necessary with a message and non-zero exit code.
+
+  Thanks to Joaquim Esteves in `PR #278 <https://github.com/adamchainz/blacken-docs/pull/278>`__.
+
 1.16.0 (2023-08-16)
 -------------------
 

README.rst

@@ -116,6 +116,7 @@ blacken-docs currently passes the following options through to Black:
 
 It also has the below extra options:
 
+* ``--check`` - Don’t modify files but indicate when changes are necessary with a message and non-zero return code.
 * ``-E`` / ``--skip-errors`` - Don’t exit non-zero for errors from Black (normally syntax errors).
 * ``--rst-literal-blocks`` - Also format literal blocks in reStructuredText files (more below).
 

src/blacken_docs/__init__.py

@@ -231,6 +231,7 @@ def format_file(
     black_mode: black.FileMode,
     skip_errors: bool,
     rst_literal_blocks: bool,
+    check_only: bool,
 ) -> int:
     with open(filename, encoding="UTF-8") as f:
         contents = f.read()
@@ -244,13 +245,15 @@ def format_file(
         print(f"{filename}:{lineno}: code block parse error {error.exc}")
     if errors and not skip_errors:
         return 2
-    if contents != new_contents:
-        print(f"{filename}: Rewriting...")
-        with open(filename, "w", encoding="UTF-8") as f:
-            f.write(new_contents)
-        return 1
-    else:
+    if contents == new_contents:
         return 0
+    if check_only:
+        print(f"{filename}: Requires a rewrite.")
+        return 1
+    print(f"{filename}: Rewriting...")
+    with open(filename, "w", encoding="UTF-8") as f:
+        f.write(new_contents)
+    return 1
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -276,6 +279,7 @@ def main(argv: Sequence[str] | None = None) -> int:
         help=f"choices: {[v.name.lower() for v in TargetVersion]}",
         dest="target_versions",
     )
+    parser.add_argument("--check", action="store_true")
     parser.add_argument("-E", "--skip-errors", action="store_true")
     parser.add_argument(
         "--rst-literal-blocks",
@@ -298,5 +302,6 @@ def main(argv: Sequence[str] | None = None) -> int:
             black_mode,
             skip_errors=args.skip_errors,
             rst_literal_blocks=args.rst_literal_blocks,
+            check_only=args.check,
         )
     return retv

tests/test_blacken_docs.py

@@ -484,6 +484,23 @@ def test_integration_line_length(tmp_path):
     )
 
 
+def test_integration_check(tmp_path):
+    f = tmp_path / "f.md"
+    text = dedent(
+        """\
+        ```python
+        x = 'a' 'b'
+        ```
+        """
+    )
+    f.write_text(text)
+
+    result = blacken_docs.main((str(f), "--check"))
+
+    assert result == 1
+    assert f.read_text() == text
+
+
 def test_integration_preview(tmp_path):
     f = tmp_path / "f.md"
     f.write_text(