Print out diff instead of complete file for formatting changes (#19)

Author: DanielNoord

pydocstringformatter/run.py

@@ -56,16 +56,24 @@ def _format_file(self, filename: Path) -> bool:
                 is_changed = True
 
         if is_changed:
+            try:
+                filename_str = os.path.relpath(filename)
+            except ValueError:  # pragma: no cover # Covered on Windows
+                # On Windows relpath raises ValueError's when the mounts differ
+                filename_str = str(filename)
+
             if self.config.write:
                 with open(filename, "w", encoding="utf-8") as file:
                     file.write(tokenize.untokenize(changed_tokens))
-                try:
-                    print(f"Formatted {os.path.relpath(filename)} 📖")
-                except ValueError:  # pragma: no cover
-                    # On Windows relpath raises ValueError's when mounts differ
-                    print(f"Formatted {filename} 📖")
+                    print(f"Formatted {filename_str} 📖")
             else:
-                sys.stdout.write(tokenize.untokenize(changed_tokens))
+                sys.stdout.write(
+                    utils._generate_diff(
+                        tokenize.untokenize(tokens),
+                        tokenize.untokenize(changed_tokens),
+                        filename_str,
+                    )
+                )
 
         return is_changed
 

pydocstringformatter/utils/__init__.py

@@ -8,6 +8,7 @@
     PydocstringFormatterError,
     TomlParsingError,
 )
+from pydocstringformatter.utils.file_diference import _generate_diff
 from pydocstringformatter.utils.find_docstrings import _is_docstring
 from pydocstringformatter.utils.find_python_file import _find_python_files
 
@@ -20,4 +21,5 @@
     "ParsingError",
     "_parse_toml_file",
     "TomlParsingError",
+    "_generate_diff",
 ]

pydocstringformatter/utils/file_diference.py

@@ -0,0 +1,14 @@
+import difflib
+
+
+def _generate_diff(old: str, new: str, filename: str) -> str:
+    """Generate a printable diff for two strings of sourcecode."""
+    return "\n".join(
+        difflib.unified_diff(
+            old.split("\n"),
+            new.split("\n"),
+            fromfile=filename,
+            tofile=filename,
+            lineterm="",
+        )
+    )

tests/data/format/no_changes/multi_line_variables.py.out

@@ -1 +1,6 @@
-Nothing to do! All docstrings are correct 🎉
+var = """A multi-line
+docstring"""
+
+var = """A multi-line
+docstring
+"""

tests/test_config.py

@@ -17,7 +17,14 @@ def test_no_toml(
     monkeypatch.chdir(CONFIG_DATA / "no_toml")
     pydocstringformatter.run_docstring_formatter(["test_package"])
     output = capsys.readouterr()
-    assert output.out == '"""A docstring"""\n'
+    assert output.out.endswith(
+        '''
+@@ -1,3 +1,2 @@
+-"""
+-A docstring"""
++"""A docstring"""
+ '''
+    )
     assert not output.err
 
 
@@ -39,7 +46,14 @@ def test_valid_toml_two(
     monkeypatch.chdir(CONFIG_DATA / "valid_toml_two")
     pydocstringformatter.run_docstring_formatter(["test_package"])
     output = capsys.readouterr()
-    assert output.out == '"""A docstring"""\n'
+    assert output.out.endswith(
+        '''
+@@ -1,3 +1,2 @@
+-"""
+-A docstring"""
++"""A docstring"""
+ '''
+    )
     assert not output.err
 
 
@@ -65,7 +79,13 @@ def test_no_write_argument(capsys: pytest.CaptureFixture[str], test_file: str) -
         assert "".join(file.readlines()) == '"""A multi-line\ndocstring"""'
 
     output = capsys.readouterr()
-    assert output.out == '"""A multi-line\ndocstring\n"""'
+    assert output.out.endswith(
+        '''
+@@ -1,2 +1,3 @@
+ """A multi-line
+-docstring"""
++docstring\n+"""'''
+    )
     assert not output.err
 
 

tests/test_formatting.py

@@ -1,4 +1,5 @@
 import os
+import pathlib
 from pathlib import Path
 from typing import List
 
@@ -25,10 +26,29 @@
     TESTS,
     ids=TEST_NAMES,
 )
-def test_formatting(test_file: str, capsys: pytest.CaptureFixture[str]) -> None:
-    """Test that we correctly format all files in the format directory"""
-    pydocstringformatter.run_docstring_formatter([test_file])
+def test_formatting(
+    test_file: str, capsys: pytest.CaptureFixture[str], tmp_path: pathlib.Path
+) -> None:
+    """Test that we correctly format all files in the format directory.
+
+    We create and write to a temporary file so that the original test file
+    isn't overwritten and the 'py.out' file can represent an actual
+    python file instead of a diff.
+    """
+    # Setup
+    temp_file_name = str(tmp_path / "test_file.py")
+    with open(test_file + ".out", encoding="utf-8") as expected_output:
+        expected_lines = expected_output.readlines()
+
+    # Get original lines from test file and write to temporary file
+    with open(test_file, encoding="utf-8") as original_file:
+        original_lines = original_file.readlines()
+    with open(temp_file_name, "w", encoding="utf-8") as temp_file:
+        temp_file.writelines(original_lines)
+
+    pydocstringformatter.run_docstring_formatter([temp_file_name, "--write"])
+
     output = capsys.readouterr()
     assert not output.err
-    with open(test_file + ".out", encoding="utf-8") as expected_output:
-        assert output.out == "".join(expected_output.readlines())
+    with open(temp_file_name, encoding="utf-8") as temp_file:
+        assert temp_file.readlines() == expected_lines

tests/test_run.py

@@ -28,7 +28,14 @@ def test_sys_agv_as_arguments(
         assert "".join(file.readlines()) == '"""A multi-line\ndocstring"""'
 
     output = capsys.readouterr()
-    assert output.out == '"""A multi-line\ndocstring\n"""'
+    assert output.out.endswith(
+        '''
+@@ -1,2 +1,3 @@
+ """A multi-line
+-docstring"""
++docstring
++"""'''
+    )
     assert not output.err