Add a --check flag that reports formatting without writing (#361)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

Author: 3 people

README.md

@@ -20,11 +20,11 @@ See [pre-commit](https://github.com/pre-commit/pre-commit) for instructions
 Sample `.pre-commit-config.yaml`:
 
 ```yaml
-- repo: https://github.com/tox-dev/tox-ini-fmt
-  rev: "1.3.1"
-  hooks:
-    - id: tox-ini-fmt
-      args: ["-p", "fix_lint,type"]
+  - repo: https://github.com/tox-dev/tox-ini-fmt
+    rev: 1.3.1
+    hooks:
+      - id: tox-ini-fmt
+        args: [-p, 'fix_lint,type']
 ```
 
 ## cli
@@ -33,14 +33,15 @@ Consult the help for the latest usage:
 
 ```console
 $ tox-ini-fmt --help
-usage: tox-ini-fmt [-h] [-s] [-p toxenv] tox_ini
+usage: tox-ini-fmt [-h] [-s | --check] [-p toxenv] tox_ini [tox_ini ...]
 
 positional arguments:
-  tox_ini       tox ini file to format
+  tox_ini       tox ini files to format
 
-optional arguments:
+options:
   -h, --help    show this help message and exit
   -s, --stdout  print the formatted text to the stdout (instead of update in-place)
+  --check       check files are formatted without writing them back (exit code 1 on change)
   -p toxenv     tox environments that pin to the start of the envlist (comma separated)
 ```
 

pyproject.toml

@@ -64,6 +64,7 @@ test = [
   "covdefaults>=2.3",
   "pytest>=8.4.2",
   "pytest-cov>=7",
+  "pytest-mock>=3.15.1",
 ]
 type = [
   "ty>=0.0.17",
@@ -99,23 +100,23 @@ lint.select = [
   "ALL",
 ]
 lint.ignore = [
-  "COM812", # Conflict with formatter
-  "CPY",    # No copyright statements
-  "D203",   # `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible
-  "D212",   # `multi-line-summary-first-line` (D212) and `multi-line-summary-second-line` (D213) are incompatible
-  "DOC",    # no support for sphinx
-  "ISC001", # Conflict with formatter
-  "RUF067", # `__init__` module should only contain docstrings and re-exports
+  "CPY",                                       # No copyright statements
+  "DOC",                                       # no support for sphinx
+  "incorrect-blank-line-before-class",         # `one-blank-line-before-class` (D203) and `no-blank-line-before-class` (D211) are incompatible
+  "missing-trailing-comma",                    # Conflict with formatter
+  "multi-line-summary-first-line",             # `multi-line-summary-first-line` (D212) and `multi-line-summary-second-line` (D213) are incompatible
+  "non-empty-init-module",                     # `__init__` module should only contain docstrings and re-exports
+  "single-line-implicit-string-concatenation", # Conflict with formatter
 ]
 lint.per-file-ignores."tests/**/*.py" = [
-  "D",       # don't care about documentation in tests
-  "FBT",     # don't care about booleans as positional arguments in tests
-  "INP001",  # no implicit namespace
-  "PLC2701", # private import is fine
-  "PLR0917", # Too many positional argument
-  "PLR2004", # Magic value used in comparison, consider replacing with a constant variable
-  "S",       # no safety concerns
-  "S101",    # asserts allowed in tests
+  "assert",                        # asserts allowed in tests
+  "D",                             # don't care about documentation in tests
+  "FBT",                           # don't care about booleans as positional arguments in tests
+  "implicit-namespace-package",    # no implicit namespace
+  "import-private-name",           # private import is fine
+  "magic-value-comparison",        # Magic value used in comparison, consider replacing with a constant variable
+  "S",                             # no safety concerns
+  "too-many-positional-arguments", # Too many positional argument
 ]
 lint.isort = { known-first-party = [
   "tox_uv",

src/tox_ini_fmt/__main__.py

@@ -53,7 +53,7 @@ def run(args: Sequence[str] | None = None) -> int:
         if opts.stdout:  # stdout just prints new format to stdout
             print(formatted, end="")  # ruff:ignore[print]
         else:
-            if before != formatted:
+            if before != formatted and not opts.check:
                 with tox_ini.open("wt", encoding="utf-8", newline=original_newlines) as file:
                     file.write(formatted)
             try:

src/tox_ini_fmt/cli.py

@@ -16,6 +16,7 @@ class ToxIniFmtNamespace(Namespace):
 
     tox_ini: list[Path]
     stdout: bool
+    check: bool
     pin_toxenvs: list[str]
 
 
@@ -50,12 +51,18 @@ def cli_args(args: Sequence[str]) -> ToxIniFmtNamespace:
     :return: the parsed options
     """
     parser = ArgumentParser()
-    parser.add_argument(
+    output_mode = parser.add_mutually_exclusive_group()
+    output_mode.add_argument(
         "-s",
         "--stdout",
         action="store_true",
         help="print the formatted text to the stdout (instead of update in-place)",
     )
+    output_mode.add_argument(
+        "--check",
+        action="store_true",
+        help="check files are formatted without writing them back (exit code 1 on change)",
+    )
 
     class CommaSeparatedStr(Action):
         def __call__(

tests/test_cli.py

@@ -79,3 +79,27 @@ def test_tox_ini_resolved(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> No
     path.write_text("")
     result = cli_args(["tox.ini"])
     assert result.tox_ini[0] == path
+
+
+@pytest.mark.parametrize(
+    ("args", "check"),
+    [
+        pytest.param([], False, id="off"),
+        pytest.param(["--check"], True, id="on"),
+    ],
+)
+def test_cli_check(tmp_path: Path, args: list[str], check: bool) -> None:
+    path = tmp_path / "tox.ini"
+    path.write_text("")
+    assert cli_args([str(path), *args]).check is check
+
+
+def test_cli_check_and_stdout_are_exclusive(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    path = tmp_path / "tox.ini"
+    path.write_text("")
+    with pytest.raises(SystemExit) as context:
+        cli_args([str(path), "--check", "--stdout"])
+    assert context.value.code != 0
+    out, err = capsys.readouterr()
+    assert not out
+    assert "not allowed with argument" in err

tests/test_main.py

@@ -7,12 +7,13 @@
 
 import pytest
 
-import tox_ini_fmt.__main__
 from tox_ini_fmt.__main__ import GREEN, RED, RESET, color_diff, run
 
 if TYPE_CHECKING:
     from pathlib import Path
 
+    from pytest_mock import MockerFixture
+
 
 def test_color_diff() -> None:
     # Arrange
@@ -96,8 +97,9 @@ def test_main(  # ruff:ignore[too-many-arguments]
     outcome: str,
     output: str,
     monkeypatch: pytest.MonkeyPatch,
+    mocker: MockerFixture,
 ) -> None:
-    monkeypatch.setattr(tox_ini_fmt.__main__, "color_diff", no_color)
+    mocker.patch("tox_ini_fmt.__main__.color_diff", no_color)
     if cwd:
         monkeypatch.chdir(tmp_path)
     tox_ini = tmp_path / "tox.ini"
@@ -150,3 +152,43 @@ def test_non_ascii_ignores_locale_encoding(tmp_path: Path) -> None:
         "tox_ini_fmt",
         str(tox_ini),
     ])
+
+
+@pytest.mark.parametrize(
+    ("start", "code", "output"),
+    [
+        pytest.param(
+            "[tox]\nrequires =\n    tox>=4.2\nenv_list=py311,py310",
+            1,
+            "--- tox.ini\n\n+++ tox.ini\n\n@@ -1,4 +1,6 @@\n\n "
+            "[tox]\n requires =\n     tox>=4.2\n-env_list=py311,py310\n+env_list =\n+    py311\n+    py310\n",
+            id="change",
+        ),
+        pytest.param(
+            "[tox]\nrequires =\n    tox>=4.2\nenv_list =\n    py311\n    py310\n",
+            0,
+            "no change for tox.ini\n",
+            id="no-change",
+        ),
+    ],
+)
+def test_main_check(  # ruff:ignore[too-many-arguments]
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+    mocker: MockerFixture,
+    start: str,
+    code: int,
+    output: str,
+) -> None:
+    mocker.patch("tox_ini_fmt.__main__.color_diff", no_color)
+    monkeypatch.chdir(tmp_path)
+    tox_ini = tmp_path / "tox.ini"
+    tox_ini.write_text(start)
+
+    assert run([str(tox_ini), "--check"]) == code
+
+    assert tox_ini.read_text() == start
+    out, err = capsys.readouterr()
+    assert not err
+    assert out == output