Add support for explicit document start marker --- in YAML docs

language_formatters_pre_commit_hooks/pretty_format_yaml.py

@@ -67,6 +67,12 @@ def pretty_format_yaml(argv: typing.Optional[typing.List[str]] = None) -> int:
             " enforce the limit we cannot guarantee that it is always possible"
         ),
     )
+    parser.add_argument(
+        "--explicit-start",
+        action="store_true",
+        dest="explicit_start",
+        help="Enforce a document-start marker (---)",
+    )
 
     parser.add_argument("filenames", nargs="*", help="Filenames to fix")
     args = parser.parse_args(argv)
@@ -83,6 +89,7 @@ def pretty_format_yaml(argv: typing.Optional[typing.List[str]] = None) -> int:
     yaml = YAML()
     yaml.indent(mapping=args.indent, sequence=args.indent + args.offset, offset=args.offset)
     yaml.preserve_quotes = args.preserve_quotes
+    yaml.explicit_start = args.explicit_start
     # Prevent ruamel.yaml to wrap yaml lines
     yaml.width = args.line_width  # type: ignore  # mypy recognise yaml.width as None
 
@@ -100,10 +107,14 @@ def pretty_format_yaml(argv: typing.Optional[typing.List[str]] = None) -> int:
         original_docs = re.split(separator_pattern, string_content, flags=re.MULTILINE)
 
         # A valid multi-document YAML file might starts with the separator.
-        # In this case the first document of original docs will be empty and should not be consdered
+        # In this case the first document of original docs will be empty and should not be considered
         if string_content.startswith("---"):
             original_docs = original_docs[1:]
 
+        # if file is a multi-doc, explicit_start must be turned off since separators will be added below
+        if len(original_docs) > 1:
+            yaml.explicit_start = False
+
         pretty_docs = []
 
         try:

test-data/pretty_format_yaml/explicit-start-pretty-formatted.yaml

@@ -0,0 +1,4 @@
+---
+root:
+  test:
+  - 1

tests/pretty_format_yaml_test.py

@@ -21,6 +21,7 @@ def change_dir():
     ("filename", "expected_retval"),
     (
         ("pretty-formatted.yaml", 0),
+        ("explicit-start-pretty-formatted.yaml", 1),
         ("not-pretty-formatted.yaml", 1),
         ("multi-doc-pretty-formatted.yaml", 0),
         ("multi-doc-not-pretty-formatted.yaml", 1),
@@ -63,3 +64,23 @@ def test_pretty_format_yaml_preserve_quotes():
     filename = "preserve-quotes-pretty-formatted.yaml"
     assert pretty_format_yaml([filename]) == 1
     assert pretty_format_yaml(["--preserve-quotes", filename]) == 0
+
+
+@pytest.mark.parametrize(
+    ("filename", "expected_retval"),
+    (
+        ("pretty-formatted.yaml", 1),
+        ("explicit-start-pretty-formatted.yaml", 0),
+        ("not-pretty-formatted.yaml", 1),
+        ("multi-doc-pretty-formatted.yaml", 0),
+        ("multi-doc-not-pretty-formatted.yaml", 1),
+        ("not-valid-file.yaml", 1),
+        ("ansible-vault.yaml", 0),
+        ("primitive.yaml", 0),
+        ("empty-doc-with-separator.yaml", 1),
+        ("empty-doc.yaml", 0),
+        ("multi-doc-with-empty-document-inside.yaml", 0),
+    ),
+)
+def test_explicit_document_start(filename, expected_retval):
+    assert pretty_format_yaml(["--explicit-start", filename]) == expected_retval