exit 1 with nbqa-diff (#704)

* exit 1 with nbqa-diff

* pin myst-parser

* leave message if nothing changed

docs/configuration.rst

@@ -8,6 +8,15 @@ You can configure :code:`nbQA` either at the command line, or by using a :code:`
 .. note::
     Please note that if you pass the same option via both the :code:`pyproject.toml` file and via the command-line, the command-line will take precedence.
 
+Preview / CI
+------------
+
+To preview changes without modifying your notebook, using the :code:`--nbqa-diff` flag. The return code will be ``1`` if ``nbQA`` would've modified any of
+your notebooks, and ``0`` otherwise.
+
+.. note::
+    You should not use ``-nbqa-diff`` alongside tools such as ``flake8`` which only check your code. Instead, use it with formatters such as ``isort``.
+
 Extra flags
 ~~~~~~~~~~~
 

nbqa/__main__.py

@@ -643,7 +643,10 @@ def _main(cli_args: CLIArgs, configs: Configs) -> int:
                 sys.stdout.write(
                     "To apply these changes, remove the `--nbqa-diff` flag\n"
                 )
-            return output_code
+            else:
+                sys.stdout.write("Notebook(s) would be left unchanged\n")
+            # For diff, we return 0 if no mutation would've occurred, and 1 otherwise.
+            return int(mutated)
 
     finally:
         _clean_up_tmp_files(nb_to_tmp_mapping)

tests/test_nbqa_diff.py

@@ -69,7 +69,7 @@ def test_invalid_syntax_with_nbqa_diff(capsys: "CaptureFixture") -> None:
     main(["black", os.path.abspath(path), "--nbqa-diff", "--nbqa-dont-skip-bad-cells"])
 
     out, err = capsys.readouterr()
-    expected_out = ""
+    expected_out = "Notebook(s) would be left unchanged\n"
     expected_err = (
         (f"{COLLISION} {BROKEN_HEART} {COLLISION}\n1 file failed to reformat.\n")
         .encode("ascii", "backslashreplace")

tests/test_non_python_notebook.py

@@ -20,5 +20,5 @@ def test_non_python_notebook(capsys: "CaptureFixture") -> None:
     path = os.path.join("tests", "invalid_data", "non_python_notebook.ipynb")
     main(["black", path, "--nbqa-diff"])
     out, _ = capsys.readouterr()
-    expected_out = ""
+    expected_out = "Notebook(s) would be left unchanged\n"
     assert out == expected_out

tests/test_skip_celltags.py

@@ -53,7 +53,7 @@ def test_skip_celltags_cli_md(capsys: "CaptureFixture") -> None:
     )
 
     out, err = capsys.readouterr()
-    expected_out = ""
+    expected_out = "Notebook(s) would be left unchanged\n"
     expected_err = ""
 
     assert out == expected_out

tests/tools/test_autopep8.py

@@ -64,5 +64,5 @@ def test_successive_runs_using_autopep8(
     main(["autopep8", str(test_notebook), "-i", "--nbqa-diff"])
 
     out, err = capsys.readouterr()
-    assert out == ""
+    assert out == "Notebook(s) would be left unchanged\n"
     assert err == ""

tests/tools/test_black.py

@@ -440,7 +440,7 @@ def test_invalid_syntax_with_nbqa_diff(capsys: "CaptureFixture") -> None:
     main(["black", os.path.abspath(path), "--nbqa-diff", "--nbqa-dont-skip-bad-cells"])
 
     out, err = capsys.readouterr()
-    expected_out = ""
+    expected_out = "Notebook(s) would be left unchanged\n"
     expected_err = (
         (f"{COLLISION} {BROKEN_HEART} {COLLISION}\n1 file failed to reformat.\n")
         .encode("ascii", "backslashreplace")

tests/tools/test_isort_works.py

@@ -227,3 +227,18 @@ def test_comment_after_trailing_semicolons(capsys: "CaptureFixture") -> None:
         "To apply these changes, remove the `--nbqa-diff` flag\n"
     )
     assert out == expected_out
+
+
+def test_return_code_false_positive() -> None:
+    """
+    Check return code is 0 when running with ``--lines-after-imports=2``.
+    """
+    notebook = os.path.join(
+        "tests", "data", "notebook_with_separated_imports_other.ipynb"
+    )
+
+    result = main(["isort", str(notebook), "--nbqa-diff", "--lines-after-imports=2"])
+    assert result == 0
+
+    result = main(["isort", str(notebook), "--nbqa-diff", "--float-to-top"])
+    assert result == 1

tests/tools/test_mdformat.py

@@ -52,5 +52,5 @@ def test_mdformat_works_with_empty_file(capsys: "CaptureFixture") -> None:
     main(["mdformat", path, "--nbqa-diff", "--nbqa-md"])
 
     out, err = capsys.readouterr()
-    assert out == ""
+    assert out == "Notebook(s) would be left unchanged\n"
     assert err == ""

tests/tools/test_yapf.py

@@ -51,5 +51,5 @@ def test_successive_runs_using_yapf(
     main(["yapf", str(test_notebook), "--in-place", "--nbqa-diff"])
 
     out, _ = capsys.readouterr()
-    expected_out = ""
+    expected_out = "Notebook(s) would be left unchanged\n"
     assert out == expected_out