fix: keep docstring-only Python chunks valid (#12346)

Co-authored-by: Julian Risch <julian.risch@deepset.ai>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-authored-by: Sebastian Husch Lee <10526848+sjrl@users.noreply.github.com>

Author: 4 people

haystack/components/preprocessors/python_code_splitter.py

@@ -199,6 +199,12 @@ def _strip_docstring(
 
         before = source_lines[unit_start - 1 : ds_start - 1]
         after = source_lines[ds_end:unit_end]
+        # Removing the only statement from a function or class would leave an
+        # invalid suite. Keep the generated chunk syntactically valid.
+        if len(body) == 1:
+            docstring_line = source_lines[ds_start - 1]
+            indentation = docstring_line[: len(docstring_line) - len(docstring_line.lstrip())]
+            after.insert(0, f"{indentation}pass\n")
         return "".join(before + after), docstring
 
     def _emit_class_units(self, cls: ast.ClassDef, source_lines: list[str], cursor: int, units: list[_CodeUnit]) -> int:

releasenotes/notes/fix-python-code-splitter-docstring-only-20260814.yaml

@@ -0,0 +1,3 @@
+fixes:
+  - |
+    Ensures ``PythonCodeSplitter`` emits syntactically valid chunks when ``strip_docstrings=True`` is used on a function or class whose docstring is its only statement.

test/components/preprocessors/test_python_code_splitter.py

@@ -2,6 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import ast
 import textwrap
 
 import pytest
@@ -707,6 +708,17 @@ def method(self):
         assert "Class-level docstring." not in (header.content or "")
         assert "Class-level docstring." in " | ".join(header.meta.get("docstrings") or [])
 
+    @pytest.mark.parametrize(
+        "source", ['def only_docstring():\n    """Function docs."""\n', 'class OnlyDocstring:\n    """Class docs."""\n']
+    )
+    def test_strip_docstrings_keeps_docstring_only_units_valid(self, source):
+        splitter = PythonCodeSplitter(min_effective_lines=1, max_effective_lines=10, strip_docstrings=True)
+        result = splitter.run(documents=[Document(content=source)])
+
+        assert result["documents"]
+        for chunk in result["documents"]:
+            ast.parse(chunk.content or "")
+
 
 class TestTopLevelStatements:
     @pytest.fixture