snakefmt 2.0.0__tar.gz → 2.0.2__tar.gz

{snakefmt-2.0.0 → snakefmt-2.0.2}/CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [2.0.2](https://github.com/snakemake/snakefmt/compare/v2.0.1...v2.0.2) (2026-06-11)
+
+
+### Bug Fixes
+
+* preserve multiline docstring indentation under rules/checkpoints ([#304](https://github.com/snakemake/snakefmt/issues/304)) ([6fd0a5c](https://github.com/snakemake/snakefmt/commit/6fd0a5c563571b247585129a950c167cc6cc766d))
+
+
+### Documentation
+
+* replace PyPI badges with personalized downloads badge ([#301](https://github.com/snakemake/snakefmt/issues/301)) ([e034b36](https://github.com/snakemake/snakefmt/commit/e034b36601c73d57582f1f86b2e5a62b40ffad06))
+
+## [2.0.1](https://github.com/snakemake/snakefmt/compare/v2.0.0...v2.0.1) (2026-05-27)
+
+
+### Bug Fixes
+
+* prevent repeated indentation of multiline shell strings ([#299](https://github.com/snakemake/snakefmt/issues/299)) ([7b0d97f](https://github.com/snakemake/snakefmt/commit/7b0d97fa0a2d85d0d1d09bc17e58047366dad1c0))
+
 ## [2.0.0](https://github.com/snakemake/snakefmt/compare/v1.1.0...v2.0.0) (2026-05-22)
 
 

{snakefmt-2.0.0 → snakefmt-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snakefmt
-Version: 2.0.0
+Version: 2.0.2
 Summary: The uncompromising Snakemake code formatter
 Project-URL: Homepage, https://github.com/snakemake/snakefmt
 Project-URL: Repository, https://github.com/snakemake/snakefmt
@@ -96,10 +96,8 @@ design and specifications of [Black][black].
 
 ### PyPi
 
-
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/snakefmt)
 ![PyPI - Version](https://img.shields.io/pypi/v/snakefmt)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/snakefmt)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/snakefmt?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/snakefmt)
 
 ```sh
 pip install snakefmt

{snakefmt-2.0.0 → snakefmt-2.0.2}/README.md

@@ -77,10 +77,8 @@ design and specifications of [Black][black].
 
 ### PyPi
 
-
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/snakefmt)
 ![PyPI - Version](https://img.shields.io/pypi/v/snakefmt)
-![PyPI - Downloads](https://img.shields.io/pypi/dm/snakefmt)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/snakefmt?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/snakefmt)
 
 ```sh
 pip install snakefmt

{snakefmt-2.0.0 → snakefmt-2.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "snakefmt"
-version = "2.0.0"
+version = "2.0.2"
 description = "The uncompromising Snakemake code formatter"
 authors = [
     { name = "Michael Hall", email = "mhaldini@icloud.com" },

{snakefmt-2.0.0 → snakefmt-2.0.2}/snakefmt/formatter.py

@@ -55,6 +55,31 @@ def index_of_first_docstring(s: str) -> Optional[int]:
     return match.end(1) - 1
 
 
+def is_docstring(string: str) -> bool:
+    """
+    Returns True if `string` is a single docstring, optionally followed only by
+    comments (ignoring surrounding whitespace). These are the rule/checkpoint
+    buffers that Black mis-handles as module-level docstrings (see issue #303).
+    """
+    stripped = string.strip()
+    match = docstring_matcher.match(stripped)
+    if match is None:
+        return False
+    remainder = stripped[match.end(1) :].strip()
+    return remainder == "" or is_all_comments(remainder)
+
+
+def indent_docstring(docstring: str, target_indent: int) -> str:
+    """
+    Re-indents a Black-normalised rule/checkpoint docstring to `target_indent`.
+
+    Black treats a rule/checkpoint docstring as a module-level docstring and so
+    flattens it to column 0. We restore the keyword indentation on every line
+    here, leaving blank lines empty so they don't gain trailing whitespace.
+    """
+    return textwrap.indent(docstring, TAB * target_indent)
+
+
 class Formatter(Parser):
     def __init__(
         self,
@@ -104,7 +129,14 @@ class Formatter(Parser):
         if not from_python:
             formatted = self.run_black_format_str(self.buffer, self.block_indent)
             if self.keyword_indent > 0:
-                formatted = self.align_strings(formatted, self.keyword_indent)
+                if not self.syntax.accepts_python_code and is_docstring(self.buffer):
+                    # Black normalises rule/checkpoint docstrings but flattens them
+                    # to column 0 (it treats them as module-level docstrings).
+                    # align_strings cannot re-indent the inner lines of a multiline
+                    # string, so indent the whole docstring directly. See issue #303.
+                    formatted = indent_docstring(formatted, self.keyword_indent)
+                else:
+                    formatted = self.align_strings(formatted, self.keyword_indent)
         else:
             # Invalid python syntax, eg lone 'else:' between two rules, can occur.
             # Below constructs valid code statements and formats them.

{snakefmt-2.0.0 → snakefmt-2.0.2}/snakefmt/shell_formatter.py

@@ -157,26 +157,73 @@ _TRIPLE_QUOTE_RE = re.compile(r"""^([a-zA-Z]*)("{3}|'{3})([\s\S]*?)(\2)$""")
 
 
 def _indent_preserving_heredocs(text: str, indent: str) -> str:
-    """Indent each line by `indent`, skipping heredoc body and terminator lines.
+    """Indent each line by `indent`, skipping heredoc bodies, heredoc terminator
+    lines, and multi-line shell string literals (single/double quotes or backticks).
 
-    shfmt does not reformat heredoc bodies. This function mirrors that — it adds
-    the target indent to command lines but leaves heredoc content untouched so that
-    terminator words remain at column 0 (required by bash for `<<EOF`) or with only
-    leading tabs (for `<<-EOF`).
+    shfmt does not reformat heredoc bodies or re-indent multiline string literal
+    bodies. This function mirrors that — it adds the target indent to outer command
+    lines but leaves heredoc and multiline string content untouched.
     """
     out_lines: list[str] = []
-    in_heredoc: str | None = None
+    state: str | None = None  # Can be: None, "'", '"', '`', 'HEREDOC'
+    heredoc_delim: str | None = None
+
     for line in text.splitlines(keepends=True):
         stripped = line.rstrip("\n")
-        if in_heredoc is not None:
+
+        # Do not indent lines starting inside a multiline string or heredoc.
+        should_indent = state is None
+
+        if state == "HEREDOC":
+            if stripped == heredoc_delim or stripped.lstrip("\t") == heredoc_delim:
+                state = None
+                heredoc_delim = None
+        else:
+            # Scan character by character to track quote/backtick state transitions
+            i = 0
+            n = len(line)
+            while i < n:
+                char = line[i]
+                if state == "'":
+                    if char == "'":
+                        state = None
+                elif state == '"':
+                    if char == "\\":
+                        i += 1  # Skip escaped character inside double quotes
+                    elif char == '"':
+                        state = None
+                elif state == "`":
+                    if char == "\\":
+                        i += 1  # Skip escaped character inside backticks
+                    elif char == "`":
+                        state = None
+                else:  # state is None
+                    if char == "\\":
+                        i += 1  # Skip escaped character in normal code
+                    elif char == "#":
+                        # Comments can only start at the beginning of a word
+                        if i == 0 or line[i - 1].isspace() or line[i - 1] in ";|&()":
+                            break  # Rest of line is comment: ignore
+                    elif char == "'":
+                        state = "'"
+                    elif char == '"':
+                        state = '"'
+                    elif char == "`":
+                        state = "`"
+                i += 1
+
+            # If we end the line in state None, check if a new heredoc starts
+            if state is None:
+                m = _HEREDOC_START.search(line)
+                if m:
+                    state = "HEREDOC"
+                    heredoc_delim = m.group(1)
+
+        if should_indent and line.strip():
+            out_lines.append(indent + line)
+        else:
             out_lines.append(line)
-            if stripped == in_heredoc or stripped.lstrip("\t") == in_heredoc:
-                in_heredoc = None
-            continue
-        out_lines.append(indent + line if line.strip() else line)
-        m = _HEREDOC_START.search(line)
-        if m:
-            in_heredoc = m.group(1)
+
     return "".join(out_lines)
 
 

{snakefmt-2.0.0 → snakefmt-2.0.2}/tests/test_formatter.py

@@ -29,11 +29,11 @@ def test_emptyInput_emptyOutput():
 
 class TestSimpleParamFormatting:
     def test_simple_rule_one_input(self):
-        stream = "rule a:\n" f'{TAB * 1}input: "foo.txt"'
+        stream = f'rule a:\n{TAB * 1}input: "foo.txt"'
         formatter = setup_formatter(stream)
 
         actual = formatter.get_formatted()
-        expected = "rule a:\n" f"{TAB * 1}input:\n" f'{TAB * 2}"foo.txt",\n'
+        expected = f'rule a:\n{TAB * 1}input:\n{TAB * 2}"foo.txt",\n'
 
         assert actual == expected
 
@@ -41,7 +41,7 @@ class TestSimpleParamFormatting:
         """
         Keywords that expect a single parameter do not have newline + indent
         """
-        formatter = setup_formatter("configfile: \n" f'{TAB * 1}"foo.yaml"')
+        formatter = setup_formatter(f'configfile: \n{TAB * 1}"foo.yaml"')
 
         actual = formatter.get_formatted()
         expected = 'configfile: "foo.yaml"\n'
@@ -173,7 +173,7 @@ use rule * from other_workflow exclude ruleC, foo as other_*
         assert formatter.get_formatted() == snakecode
 
     def test_use_rule_no_with_two_line_indented(self):
-        snakecode = 'include: "file.txt"\n\n\n' "use rule * from module as module_*\n"
+        snakecode = 'include: "file.txt"\n\n\nuse rule * from module as module_*\n'
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
 
@@ -187,9 +187,7 @@ use rule * from other_workflow exclude ruleC, foo as other_*
 
     def test_use_rule_newline_spacing(self):
         snakecode = (
-            "use rule * from module as module_*\n\n\n"
-            "rule baz:\n"
-            f"{TAB * 1}threads: 4\n"
+            f"use rule * from module as module_*\n\n\nrule baz:\n{TAB * 1}threads: 4\n"
         )
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
@@ -401,7 +399,7 @@ class TestSimplePythonFormatting:
         mock_method.assert_called_once()
 
     def test_python_code_with_multi_indent_passes(self):
-        python_code = "if p:\n" f"{TAB * 1}for elem in p:\n" f"{TAB * 2}dothing(elem)\n"
+        python_code = f"if p:\n{TAB * 1}for elem in p:\n{TAB * 2}dothing(elem)\n"
         # test black gets called
         with mock.patch(
             "snakefmt.formatter.Formatter.run_black_format_str",
@@ -437,7 +435,7 @@ class TestSimplePythonFormatting:
         assert formatter.get_formatted() == snake_code
 
     def test_line_wrapped_python_code_outside_rule(self):
-        content = "list_of_lots_of_things = [1, 2, 3, 4, 5, 6]\n" "include: snakefile"
+        content = "list_of_lots_of_things = [1, 2, 3, 4, 5, 6]\ninclude: snakefile"
         line_length = 30
         formatter = setup_formatter(content, line_length=line_length)
 
@@ -453,9 +451,7 @@ class TestSimplePythonFormatting:
 
     def test_line_wrapped_python_code_inside_rule(self):
         content = (
-            f"rule a:\n"
-            f"{TAB}input:\n"
-            f"{TAB*2}list_of_lots_of_things = [1, 2, 3, 4, 5]"
+            f"rule a:\n{TAB}input:\n{TAB * 2}list_of_lots_of_things = [1, 2, 3, 4, 5]"
         )
         line_length = 30
         formatter = setup_formatter(content, line_length=line_length)
@@ -463,10 +459,10 @@ class TestSimplePythonFormatting:
         actual = formatter.get_formatted()
         expected = (
             "rule a:\n"
-            f"{TAB*1}input:\n"
-            f"{TAB*2}list_of_lots_of_things=[\n"
-            f"{TAB*3}1,\n{TAB*3}2,\n{TAB*3}3,\n{TAB*3}4,\n{TAB*3}5,\n"
-            f"{TAB*2}],\n"
+            f"{TAB * 1}input:\n"
+            f"{TAB * 2}list_of_lots_of_things=[\n"
+            f"{TAB * 3}1,\n{TAB * 3}2,\n{TAB * 3}3,\n{TAB * 3}4,\n{TAB * 3}5,\n"
+            f"{TAB * 2}],\n"
         )
 
         assert actual == expected
@@ -499,11 +495,11 @@ class TestSimplePythonFormatting:
         """Issue 262. Make sure no spacing added between !r"""
         snakecode = (
             'if config.get("treefix_root", "").startswith(ROOT_FLAG):\n'
-            f"{TAB*1}print(\n"
-            f"{TAB*2}f\"Removing the flag {{ROOT_FLAT!r}} from config['treefix_root'] ; \"\n"  # noqa: E501
-            f'{TAB*2}f"consider updating the config param in the config file.",\n'
-            f"{TAB*2}file=sys.stderr,\n"
-            f"{TAB*1})\n"
+            f"{TAB * 1}print(\n"
+            f"{TAB * 2}f\"Removing the flag {{ROOT_FLAT!r}} from config['treefix_root'] ; \"\n"  # noqa: E501
+            f'{TAB * 2}f"consider updating the config param in the config file.",\n'
+            f"{TAB * 2}file=sys.stderr,\n"
+            f"{TAB * 1})\n"
         )
         formatter = setup_formatter(snakecode)
 
@@ -554,7 +550,7 @@ class TestComplexPythonFormatting:
         assert formatter.get_formatted() == expected
 
     def test_python_code_after_nested_snakecode_gets_formatted(self):
-        snakecode = "if condition:\n" f'{TAB * 1}include: "a"\n' "b=2\n"
+        snakecode = f'if condition:\n{TAB * 1}include: "a"\nb=2\n'
         with mock.patch(
             "snakefmt.formatter.Formatter.run_black_format_str", spec=True
         ) as mock_m:
@@ -576,7 +572,7 @@ class TestComplexPythonFormatting:
         assert formatter.get_formatted() == expected
 
     def test_python_code_before_nested_snakecode_gets_formatted(self):
-        snakecode = "b=2\n" "if condition:\n" f'{TAB * 1}include: "a"\n'
+        snakecode = f'b=2\nif condition:\n{TAB * 1}include: "a"\n'
         with mock.patch(
             "snakefmt.formatter.Formatter.run_black_format_str", spec=True
         ) as mock_m:
@@ -585,7 +581,7 @@ class TestComplexPythonFormatting:
             assert mock_m.call_count == 3
 
         formatter = setup_formatter(snakecode)
-        expected = "b = 2\n" "if condition:\n\n" f'{TAB * 1}include: "a"\n'
+        expected = f'b = 2\nif condition:\n\n{TAB * 1}include: "a"\n'
         assert formatter.get_formatted() == expected
 
     def test_pythoncode_parser_based_formatting_before_snakecode(self):
@@ -826,9 +822,7 @@ class TestStringFormatting:
         assert formatter.get_formatted() == expected
 
     def test_keyword_with_tpq_inside_expression_left_alone(self):
-        snakecode = (
-            "rule test:\n" f"{TAB * 1}run:\n" f'{TAB * 2}shell(f"""shell stuff""")\n'
-        )
+        snakecode = f'rule test:\n{TAB * 1}run:\n{TAB * 2}shell(f"""shell stuff""")\n'
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
 
@@ -984,6 +978,141 @@ rule a:
 '''
         assert formatter.get_formatted() == expected
 
+    def test_multiline_docstring_inside_rule_preserves_indentation(self):
+        """https://github.com/snakemake/snakefmt/issues/303"""
+        snakecode = (
+            "rule test:\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}Comment\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == snakecode
+
+    def test_multiline_docstring_inside_checkpoint_preserves_indentation(self):
+        """https://github.com/snakemake/snakefmt/issues/303"""
+        snakecode = (
+            "checkpoint test:\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}Checkpoint comment\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == snakecode
+
+    def test_single_line_docstring_inside_rule_remains_intact(self):
+        """https://github.com/snakemake/snakefmt/issues/303"""
+        snakecode = (
+            "rule test:\n"
+            f'{TAB * 1}"""Comment"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == snakecode
+
+    def test_multiline_docstring_with_blank_line_inside_rule(self):
+        """A blank line inside a docstring stays empty (no trailing whitespace)"""
+        snakecode = (
+            "rule test:\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}First paragraph.\n"
+            "\n"
+            f"{TAB * 1}Second paragraph.\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        # The expected output equals the input: the blank line stays a bare "\n".
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == snakecode
+
+    def test_multiline_docstring_preserves_relative_indentation(self):
+        """Indented lines within a docstring keep their relative indentation"""
+        snakecode = (
+            "rule test:\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}Summary line.\n"
+            f"{TAB * 2}Indented detail.\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == snakecode
+
+    def test_multiline_docstring_followed_by_comment_inside_rule(self):
+        """A docstring followed by a comment is still indented under the rule"""
+        snakecode = (
+            "rule test:\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}Comment\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}# trailing comment\n"
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        # Black inserts a blank line between the docstring and the comment.
+        expected = (
+            "rule test:\n"
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}Comment\n"
+            f'{TAB * 1}"""\n'
+            "\n"
+            f"{TAB * 1}# trailing comment\n"
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == expected
+
+    def test_collapsing_docstring_inside_rule_keeps_black_normalisation(self):
+        """Black still collapses a single-line docstring; indentation is preserved"""
+        snakecode = (
+            "rule a:\n"
+            f'{TAB * 1}"""The rule a\n'
+            f'{TAB * 1}"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        expected = (
+            "rule a:\n"
+            f'{TAB * 1}"""The rule a"""\n'
+            f"{TAB * 1}input:\n"
+            f'{TAB * 2}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == expected
+
+    def test_multiline_docstring_inside_nested_rule_preserves_indentation(self):
+        """A docstring in a rule nested under an if-block keeps its deeper indent"""
+        snakecode = (
+            "if True:\n"
+            f"{TAB * 1}rule test:\n"
+            f'{TAB * 2}"""\n'
+            f"{TAB * 2}Nested comment\n"
+            f'{TAB * 2}"""\n'
+            f"{TAB * 2}input:\n"
+            f'{TAB * 3}"test.txt",\n'
+        )
+        # snakefmt inserts a blank line after the `if True:` header.
+        expected = (
+            "if True:\n"
+            "\n"
+            f"{TAB * 1}rule test:\n"
+            f'{TAB * 2}"""\n'
+            f"{TAB * 2}Nested comment\n"
+            f'{TAB * 2}"""\n'
+            f"{TAB * 2}input:\n"
+            f'{TAB * 3}"test.txt",\n'
+        )
+        formatter = setup_formatter(snakecode)
+        assert formatter.get_formatted() == expected
+
     def test_shell_mixed_string_types(self):
         """https://github.com/snakemake/snakefmt/issues/129"""
         snakecode = (
@@ -1095,11 +1224,7 @@ rule a:
         mock_format.side_effect = side_effect
 
         snakecode = (
-            "rule a:\n"
-            f"{TAB * 1}shell:\n"
-            f'{TAB * 2}"""\n'
-            f"{TAB * 2}cmd\n"
-            f'{TAB * 2}"""\n'
+            f'rule a:\n{TAB * 1}shell:\n{TAB * 2}"""\n{TAB * 2}cmd\n{TAB * 2}"""\n'
         )
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
@@ -1131,11 +1256,9 @@ class TestReformatting_SMK_BREAK:
     def test_key_value_parameter_repositioning(self):
         """Key/val params can occur before positional params"""
         formatter = setup_formatter(
-            f"rule a:\n" f"{TAB * 1}input:\n" f'{TAB * 2}a="b",\n' f'{TAB * 2}"c"\n'
-        )
-        expected = (
-            f"rule a:\n" f"{TAB * 1}input:\n" f'{TAB * 2}"c",\n' f'{TAB * 2}a="b",\n'
+            f'rule a:\n{TAB * 1}input:\n{TAB * 2}a="b",\n{TAB * 2}"c"\n'
         )
+        expected = f'rule a:\n{TAB * 1}input:\n{TAB * 2}"c",\n{TAB * 2}a="b",\n'
         assert formatter.get_formatted() == expected
 
 
@@ -1147,7 +1270,7 @@ class TestCommentTreatment:
         assert formatter.get_formatted() == expected
 
     def test_comment_after_keyword_kept(self):
-        snakecode = "rule a:  # A comment \n" f"{TAB * 1}threads: 4\n"
+        snakecode = f"rule a:  # A comment \n{TAB * 1}threads: 4\n"
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
 
@@ -1179,9 +1302,7 @@ class TestCommentTreatment:
         assert formatter.get_formatted() == expected
 
     def test_comment_outside_keyword_context_stays_untouched(self):
-        snakecode = (
-            f"rule a:\n" f"{TAB * 1}run:\n" f"{TAB * 2}f()\n\n\n" f"# A comment\n"
-        )
+        snakecode = f"rule a:\n{TAB * 1}run:\n{TAB * 2}f()\n\n\n# A comment\n"
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
 
@@ -1326,10 +1447,7 @@ class TestCommentTreatment:
     def test_two_comments_in_global_context(self):
         """https://github.com/snakemake/snakefmt/issues/169#issuecomment-1365540999"""
         snakecode = (
-            'configfile: "config.yaml"\n\n\n'
-            "# AAA\n"
-            "# BBB\n\n"
-            'BATCH = "20220202"\n'
+            'configfile: "config.yaml"\n\n\n# AAA\n# BBB\n\nBATCH = "20220202"\n'
         )
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
@@ -1349,7 +1467,7 @@ class TestCommentTreatment:
 
 class TestNewlineSpacing:
     def test_parameter_keyword_spacing_above(self):
-        formatter = setup_formatter("b = 2\n" 'configfile: "config.yaml"')
+        formatter = setup_formatter('b = 2\nconfigfile: "config.yaml"')
 
         actual = formatter.get_formatted()
         expected = 'b = 2\n\n\nconfigfile: "config.yaml"\n'
@@ -1381,7 +1499,7 @@ class TestNewlineSpacing:
             assert formatter.get_formatted() == replaced
 
     def test_repeated_parameter_keyword_comment_in_between_no_spacing(self):
-        snakecode = 'include: "a"\n# A comment\n' ' # c2\ninclude: "b"\n'
+        snakecode = 'include: "a"\n# A comment\n # c2\ninclude: "b"\n'
         expected = 'include: "a"\n# A comment\n# c2\ninclude: "b"\n'
         assert setup_formatter(snakecode).get_formatted() == expected
 
@@ -1454,35 +1572,23 @@ below_rule = "2spaces"
         assert formatter.get_formatted() == expected
 
     def test_initial_comment_does_not_trigger_spacing(self):
-        snakecode = (
-            f"# load config\n" f"rule all:\n" f"{TAB * 1}input:\n" f"{TAB * 2}files,\n"
-        )
+        snakecode = f"# load config\nrule all:\n{TAB * 1}input:\n{TAB * 2}files,\n"
 
         formatter = setup_formatter(snakecode)
         assert formatter.get_formatted() == snakecode
 
     def test_comment_sticks_to_rule(self):
         snakecode = (
-            "def p():\n"
-            f"{TAB * 1}pass\n"
-            f"#My rule a\n"
-            f"rule a:\n"
-            f"{TAB * 1}threads: 1\n"
+            f"def p():\n{TAB * 1}pass\n#My rule a\nrule a:\n{TAB * 1}threads: 1\n"
         )
         formatter = setup_formatter(snakecode)
         expected = (
-            "def p():\n"
-            f"{TAB * 1}pass\n\n\n"
-            f"# My rule a\n"
-            f"rule a:\n"
-            f"{TAB * 1}threads: 1\n"
+            f"def p():\n{TAB * 1}pass\n\n\n# My rule a\nrule a:\n{TAB * 1}threads: 1\n"
         )
         assert formatter.get_formatted() == expected
 
     def test_keyword_disjoint_comment_stays_keyword_disjoint(self):
-        snakecode = (
-            "def p():\n" f"{TAB * 1}pass\n" f"#A lone comment\n\n" f'include: "a"\n'
-        )
+        snakecode = f'def p():\n{TAB * 1}pass\n#A lone comment\n\ninclude: "a"\n'
         formatter = setup_formatter(snakecode)
         expected = (
             "def p():\n"
@@ -1498,8 +1604,8 @@ below_rule = "2spaces"
         assert setup_formatter(snakecode).get_formatted() == expected
 
     def test_comment_inside_python_code_sticks_to_rule(self):
-        snakecode = f"if p:\n" f"{TAB * 1}# A comment\n" f'{TAB * 1}include: "a"\n'
-        expected = f"if p:\n\n" f"{TAB * 1}# A comment\n" f'{TAB * 1}include: "a"\n'
+        snakecode = f'if p:\n{TAB * 1}# A comment\n{TAB * 1}include: "a"\n'
+        expected = f'if p:\n\n{TAB * 1}# A comment\n{TAB * 1}include: "a"\n'
         assert setup_formatter(snakecode).get_formatted() == expected
 
     def test_comment_below_keyword_gets_spaced(self):
@@ -1588,14 +1694,14 @@ class TestLineWrapping:
         """https://github.com/snakemake/snakefmt/issues/124"""
         snakecode = (
             "rule a:\n"
-            f"{TAB*1}output:\n"
-            f'{TAB*2}"foo",\n'
-            f"{TAB*1}params:\n"
-            f"{TAB*2}datasources=(\n"
-            f'{TAB*3}"-s {{}}".format(" ".join(config["annotations"]["dgidb"]["datasources"]))\n'  # noqa: E501
-            f'{TAB*3}if config["annotations"]["dgidb"].get("datasources", "")\n'
-            f'{TAB*3}else ""\n'
-            f"{TAB*2}),\n"
+            f"{TAB * 1}output:\n"
+            f'{TAB * 2}"foo",\n'
+            f"{TAB * 1}params:\n"
+            f"{TAB * 2}datasources=(\n"
+            f'{TAB * 3}"-s {{}}".format(" ".join(config["annotations"]["dgidb"]["datasources"]))\n'  # noqa: E501
+            f'{TAB * 3}if config["annotations"]["dgidb"].get("datasources", "")\n'
+            f'{TAB * 3}else ""\n'
+            f"{TAB * 2}),\n"
         )
         formatter = setup_formatter(snakecode)
 
@@ -1605,15 +1711,15 @@ class TestLineWrapping:
         """https://github.com/snakemake/snakefmt/issues/124#issuecomment-986845398"""
         snakecode = (
             "if True:\n\n"
-            f"{TAB*1}def func1():\n"
-            f'''{TAB*2}"""docstring"""\n'''
-            f"{TAB*2}pass\n\n"
-            f"{TAB*1}rule foo:\n"
-            f"{TAB*2}shell:\n"
-            f'{TAB*3}"echo bar"\n\n'
-            f"{TAB*1}def func2():\n"
-            f'''{TAB*2}"""this function should stay indented"""\n'''
-            f"{TAB*2}pass\n"
+            f"{TAB * 1}def func1():\n"
+            f'''{TAB * 2}"""docstring"""\n'''
+            f"{TAB * 2}pass\n\n"
+            f"{TAB * 1}rule foo:\n"
+            f"{TAB * 2}shell:\n"
+            f'{TAB * 3}"echo bar"\n\n'
+            f"{TAB * 1}def func2():\n"
+            f'''{TAB * 2}"""this function should stay indented"""\n'''
+            f"{TAB * 2}pass\n"
         )
         formatter = setup_formatter(snakecode)
 
@@ -1990,7 +2096,7 @@ def test_invalid_python_error_line_number():
 
 
 def test_invalid_python_error_eof():
-    snakecode = "rule a:\n" f"{TAB * 1}run:\n" f"{TAB * 2}a = \n"
+    snakecode = f"rule a:\n{TAB * 1}run:\n{TAB * 2}a = \n"
     with pytest.raises(InvalidPython) as excinfo:
         setup_formatter(snakecode).get_formatted()
     msg = str(excinfo.value)
@@ -2026,7 +2132,8 @@ def test_invalid_python_error_no_dedent(mock_format):
     from snakefmt.parser.syntax import KeywordSyntax
 
     formatter.context = Context(
-        None, KeywordSyntax("Global", keyword_indent=0, accepts_py=True)  # type: ignore
+        None,
+        KeywordSyntax("Global", keyword_indent=0, accepts_py=True),  # type: ignore
     )
     # Manually set last_token to something that isn't DEDENT/ENDMARKER
     formatter.last_token = tokenize.TokenInfo(
@@ -2046,7 +2153,7 @@ def test_invalid_python_error_no_match(mock_format):
         raise black.parsing.InvalidInput("Custom black error without line number")
 
     mock_format.side_effect = side_effect
-    snakecode = "rule a:\n" f"{TAB * 1}run:\n" f"{TAB * 2}a = 1\n"
+    snakecode = f"rule a:\n{TAB * 1}run:\n{TAB * 2}a = 1\n"
     with pytest.raises(InvalidPython) as excinfo:
         setup_formatter(snakecode).get_formatted()
     msg = str(excinfo.value)
@@ -2067,13 +2174,7 @@ def test_multiline_fallback(mock_format):
 
     mock_format.side_effect = side_effect
 
-    snakecode = (
-        "rule a:\n"
-        f"{TAB * 1}shell:\n"
-        f'{TAB * 2}"""\n'
-        f"{TAB * 2}cmd\n"
-        f'{TAB * 2}"""\n'
-    )
+    snakecode = f'rule a:\n{TAB * 1}shell:\n{TAB * 2}"""\n{TAB * 2}cmd\n{TAB * 2}"""\n'
     formatter = setup_formatter(snakecode)
     # The actual result won't be perfect because we hand-mocked Black,
     # but it guarantees the code path is executed.
@@ -2111,6 +2212,67 @@ def test_index_of_first_docstring_match():
     assert index_of_first_docstring('"""docstring"""') == 14
 
 
+class TestDocstringHelpers:
+    """Unit tests for the is_docstring / indent_docstring helpers (issue #303)."""
+
+    @pytest.mark.parametrize(
+        "string",
+        [
+            # Real rule/checkpoint docstring buffers reaching is_docstring():
+            '"""single line"""',  # single-line docstring buffer
+            '"""\nmultiline\n"""',  # the issue #303 multiline buffer
+            'r"""raw docstring"""',  # raw docstring
+            "'''single quotes'''",  # single-quoted docstring
+            '"""docstring"""\n# trailing comment',  # docstring + comment (Hocnonsense)
+            # Defensive: leading/trailing whitespace only guards the .strip().
+            '  \n"""leading/trailing whitespace"""\n  ',
+        ],
+    )
+    def test_is_docstring_true(self, string):
+        from snakefmt.formatter import is_docstring
+
+        assert is_docstring(string) is True
+
+    @pytest.mark.parametrize(
+        "string",
+        [
+            # Real buffers that must NOT be treated as docstrings:
+            "# just a comment",  # comment-only rule buffer
+            'x = """assigned triple-quoted"""',  # assignment, not a docstring
+            # Defensive: these can't occur as a directive-context buffer, but the
+            # helper must still reject them (empty is short-circuited earlier;
+            # arbitrary Python is invalid inside a rule directive context).
+            "",
+            "x = 1",
+            '"""docstring"""\nx = 1',  # docstring followed by code
+            'x = 1\n"""docstring"""',  # code followed by docstring
+        ],
+    )
+    def test_is_docstring_false(self, string):
+        from snakefmt.formatter import is_docstring
+
+        assert is_docstring(string) is False
+
+    def test_indent_docstring_single_line(self):
+        from snakefmt.formatter import indent_docstring
+
+        assert indent_docstring('"""doc"""\n', 1) == f'{TAB * 1}"""doc"""\n'
+
+    def test_indent_docstring_multiline(self):
+        from snakefmt.formatter import indent_docstring
+
+        docstring = '"""\nline\n"""\n'
+        expected = f'{TAB * 2}"""\n{TAB * 2}line\n{TAB * 2}"""\n'
+        assert indent_docstring(docstring, 2) == expected
+
+    def test_indent_docstring_leaves_blank_lines_without_trailing_whitespace(self):
+        from snakefmt.formatter import indent_docstring
+
+        docstring = '"""\na\n\nb\n"""\n'
+        expected = f'{TAB * 1}"""\n{TAB * 1}a\n\n{TAB * 1}b\n{TAB * 1}"""\n'
+        assert indent_docstring(docstring, 1) == expected
+
+
 class TestFmtOffOn:
     """Tests for # fmt: off / # fmt: on directives."""
 
@@ -2210,10 +2372,10 @@ class TestFmtOffOn:
         )
         assert setup_formatter(code).get_formatted() == expected
         bad_indent = "  "
-        snakecode = "rule:\n" " run:\n" + (
+        snakecode = "rule:\n run:\n" + (
             "".join(f"{bad_indent}{i}\n" for i in code.splitlines())
         )
-        snakexpected = "rule:\n" f"{TAB * 1}run:\n" + (
+        snakexpected = f"rule:\n{TAB * 1}run:\n" + (
             f"{TAB * 2}# ?\n"
             f"{TAB * 2}x = [1, 2, 3]\n"
             f"{TAB * 2}# fmt: off\n"
@@ -2348,7 +2510,7 @@ class TestFmtOffOn:
         assert formatter.get_formatted() == expected
 
     def test_fmt_off_lagging_comments(self):
-        expected = "if 1:\n" f"{TAB * 1}lagging_comments\n" "\n" f"{TAB * 1}# fmtany\n"
+        expected = f"if 1:\n{TAB * 1}lagging_comments\n\n{TAB * 1}# fmtany\n"
         assert setup_formatter(expected).get_formatted() == expected
         expected = (
             "if 1:\n"
@@ -2489,8 +2651,8 @@ class TestFmtOffSort:
     def test_fmt_off_sort_nothing(self):
         code1, formatted1 = TestSortFormatting.sorting_comprehensive
         code3, formatted3 = TestSortFormatting.sort_inline_comments
-        code = code1.rstrip() + "\n" "\n" "if 1:\n" " pass\n" "\n\n" + code3
-        expected = formatted1 + "\n\n" "if 1:\n" f"{TAB}pass\n" "\n\n" + formatted3
+        code = code1.rstrip() + "\n\nif 1:\n pass\n\n\n" + code3
+        expected = formatted1 + f"\n\nif 1:\n{TAB}pass\n\n\n" + formatted3
         assert setup_formatter(code, sort_params=True).get_formatted() == expected
 
     def test_fmt_off_sort_between_directive(self):

{snakefmt-2.0.0 → snakefmt-2.0.2}/tests/test_shell_formatter.py

@@ -271,3 +271,131 @@ class TestFormatPythonStringLiteralHeredocs:
             '        """'
         )
         assert format_python_string_literal(literal, target_indent=2) == expected
+
+
+class TestFormatPythonStringLiteralMultilineStrings:
+    def test_multiline_single_quoted_string_idempotent(self):
+        # Multi-line single-quoted string inside the shell block (e.g. bash -c '...')
+        literal = (
+            '"""\n'
+            "        squashfs-mount image.sqsh:/env -- bash -c '\n"
+            "            source /env/bin/activate\n"
+            "            echo hello\n"
+            "            '\n"
+            '        """'
+        )
+
+        # First run formats the outer code and should not mangle the
+        # inner string's indent
+        f1 = format_python_string_literal(literal, target_indent=2)
+        # Second run should produce the exact same output (idempotency)
+        f2 = format_python_string_literal(f1, target_indent=2)
+
+        assert f1 == f2
+
+    def test_multiline_double_quoted_string_idempotent(self):
+        # Multi-line double-quoted string inside the shell block (e.g. echo "...")
+        literal = (
+            '"""\n        echo "line 1\n        line 2\n        line 3"\n        """'
+        )
+
+        f1 = format_python_string_literal(literal, target_indent=2)
+        f2 = format_python_string_literal(f1, target_indent=2)
+
+        assert f1 == f2
+
+    def test_multiline_backtick_string_idempotent(self):
+        # Multi-line backtick string inside the shell block
+        literal = (
+            '"""\n        echo `line 1\n        line 2\n        line 3`\n        """'
+        )
+
+        f1 = format_python_string_literal(literal, target_indent=2)
+        f2 = format_python_string_literal(f1, target_indent=2)
+
+        assert f1 == f2
+
+    def test_double_quote_escaping(self):
+        # \" inside double quotes
+        literal = '"""\n        echo "line 1 \\" still inside \\" line 2"\n        """'
+        f1 = format_python_string_literal(literal, target_indent=2)
+        assert '\\" still inside \\"' in f1
+
+    def test_general_escapes(self):
+        # \ in normal code
+        literal = '"""\n        echo \\$foo\n        """'
+        f1 = format_python_string_literal(literal, target_indent=2)
+        assert "echo \\$foo" in f1
+
+    def test_comments_diverse_boundaries(self):
+        # Comment at line start, comment after space
+        literal = (
+            '"""\n'
+            "        # start comment\n"
+            "        echo foo # inline comment\n"
+            '        """'
+        )
+        f1 = format_python_string_literal(literal, target_indent=2)
+        assert "        # start comment" in f1
+
+    def test_non_triple_quoted_string_returned_unchanged(self):
+        literal = '"echo hello"'
+        assert format_python_string_literal(literal, target_indent=2) == literal
+
+    def test_newline_prepending_branches(self):
+        # 1. indented content is non-empty (does not start with newline)
+        literal1 = '"""\nls\n"""'
+        f1 = format_python_string_literal(literal1, target_indent=2)
+        assert f1.startswith('"""\n        ls')
+
+        # 2. indented content is empty
+        literal2 = '"""\n"""'
+        f2 = format_python_string_literal(literal2, target_indent=2)
+        assert f2 == '"""\n        """'
+
+
+def test_indent_preserving_heredocs_direct_edge_cases():
+    # 1. Backtick state transition
+    text = "echo `line 1\nline 2\nline 3`\n"
+    res = _indent_preserving_heredocs(text, "    ")
+    assert res == "    echo `line 1\nline 2\nline 3`\n"
+
+    # 2. Escaped backtick inside backticks
+    text = "echo `line 1 \\` line 2`\n"
+    res = _indent_preserving_heredocs(text, "    ")
+    assert res == "    echo `line 1 \\` line 2`\n"
+
+    # 3. Escaped double quote inside double quotes
+    text = 'echo "line 1 \\" line 2"\n'
+    res = _indent_preserving_heredocs(text, "    ")
+    assert res == '    echo "line 1 \\" line 2"\n'
+
+    # 4. Escaped backslash in normal code
+    text = "echo \\\\\n"
+    res = _indent_preserving_heredocs(text, "    ")
+    assert res == "    echo \\\\\n"
+
+    # 5. Comment boundaries after control characters and inside words (valid syntax)
+    text = (
+        "# start comment\n"
+        "echo bar;# control ;\n"
+        "echo bar&# control &\n"
+        "echo bar |# control |\n"
+        "cat\n"
+        "(# control (\n"
+        "echo inside\n"
+        ")# control )\n"
+        "echo foo#bar\n"
+    )
+    res = _indent_preserving_heredocs(text, "    ")
+    assert res == (
+        "    # start comment\n"
+        "    echo bar;# control ;\n"
+        "    echo bar&# control &\n"
+        "    echo bar |# control |\n"
+        "    cat\n"
+        "    (# control (\n"
+        "    echo inside\n"
+        "    )# control )\n"
+        "    echo foo#bar\n"
+    )

{snakefmt-2.0.0 → snakefmt-2.0.2}/tests/test_snakefmt.py

@@ -97,7 +97,7 @@ class TestCLIBasic:
         cli_runner.invoke(main, params)
         actual_stat = file.stat()
 
-        assert actual_stat == expected_stat
+        assert actual_stat.st_mtime == expected_stat.st_mtime
 
 
 class TestCLICheck:

{snakefmt-2.0.0 → snakefmt-2.0.2}/uv.lock

@@ -1019,7 +1019,7 @@ wheels = [
 
 [[package]]
 name = "snakefmt"
-version = "2.0.0"
+version = "2.0.2"
 source = { editable = "." }
 dependencies = [
     { name = "black" },