Merge 98649b4 into 319295c

docs/index.md

@@ -190,6 +190,16 @@ export YAMLFIX_COMMENTS_REQUIRE_STARTING_SPACE="true"
 
 This option enforces a space between the comment indicator (`#`) and the first character in the comment. It implements the enforcement of the yamllint rule `rules.comments.require-starting-space` - see: https://yamllint.readthedocs.io/en/stable/rules.html#module-yamllint.rules.comments
 
+### Comments Whitelines
+
+Default: `comments_whitelines: int = 1`<br>
+Environment variable override:
+```bash
+export YAMLFIX_COMMENTS_WHITELINES="1"
+```
+
+This option allows to add a specific number of whitelines before a comment that starts at the beginning of a new line
+
 ### Config Path
 
 Default: `config_path: Optional[str] = None`<br>

pyproject.toml

@@ -305,6 +305,7 @@ pylint = [
             # though they are not used in the function directly, they are used to
             # configure the test.
   "-R0904", # Too many public methods (25/20) (too-many-public-methods)
+  "-C0302", # Allows module to have unlimited number of lines.
 ]
 
 [tool.flakeheaven.exceptions."tests/factories.py"]

src/yamlfix/adapters.py

@@ -3,7 +3,7 @@
 import logging
 import re
 from io import StringIO
-from typing import Any, Callable, List, Optional, Tuple
+from typing import Any, Callable, List, Match, Optional, Tuple
 
 from ruyaml.main import YAML
 from ruyaml.nodes import MappingNode, Node, ScalarNode, SequenceNode
@@ -351,6 +351,7 @@ def fix(self, source_code: str) -> str:
             self._restore_jinja_variables,
             self._restore_double_exclamations,
             self._fix_comments,
+            self._fix_whitelines,
             self._fix_top_level_lists,
             self._fix_flow_style_lists,
             self._add_newline_at_end_of_file,
@@ -606,6 +607,61 @@ def _fix_comments(self, source_code: str) -> str:
 
         return "\n".join(fixed_source_lines)
 
+    def _fix_whitelines(self, source_code: str) -> str:
+        """Fixes number of consecutive whitelines.
+
+        Before a comment-only line, either:
+          - 0 whitelines are allowed
+          - Exactly `self.config.comments_whitelines` whitelines are allowed
+
+        This method removes extraneous whitelines that are not immediately followed by
+        a comment.
+
+        Args:
+            self: Source code to be corrected.
+
+        Returns:
+            Source code with appropriate whitelines standards.
+        """
+        config = self.config
+        n_whitelines_from_content = config.comments_whitelines
+
+        desired_whitelines_with_comments = "\n" * (n_whitelines_from_content + 1) + "#"
+        re_whitelines_with_comments = "\n\n+[#]"
+        re_whitelines_with_no_comments = "\n\n+[^#\n]"
+
+        source_code = re.sub(
+            pattern=re_whitelines_with_comments,
+            repl=desired_whitelines_with_comments,
+            string=source_code,
+        )
+        source_code = re.sub(
+            pattern=re_whitelines_with_no_comments,
+            repl=self._remove_extra_whitelines,
+            string=source_code,
+        )
+
+        return source_code
+
+    @staticmethod
+    def _remove_extra_whitelines(match: Match[str]) -> str:
+        """Removes extra whitelines.
+
+        Method used by `SourceCodeFixer._fix_whitelines()` to remove extra whitelines
+        when whitelines are not followed by a comment.
+
+        Args:
+            match: The matched expression by `re`
+
+        Returns:
+            A single new line character followed by the last character of the matched
+            string
+        """
+        pattern_str = match.group()
+        adjusted_pattern_str = "\n" + pattern_str[-1]
+
+        return adjusted_pattern_str
+
     @staticmethod
     def _restore_double_exclamations(source_code: str) -> str:
         """Restore the double exclamation marks.

src/yamlfix/model.py

@@ -19,6 +19,7 @@ class YamlfixConfig(ConfigSchema):
     allow_duplicate_keys: bool = False
     comments_min_spaces_from_content: int = 2
     comments_require_starting_space: bool = True
+    comments_whitelines: int = 1
     config_path: Optional[str] = None
     explicit_start: bool = True
     indent_mapping: int = 2

tests/unit/test_adapter_yaml.py

@@ -568,9 +568,6 @@ def test_sequence_flow_style_with_trailing_newlines(self) -> None:
             """\
             ---
             list: [item, item]
-
-
-
             key: value
             """
         )