gh-137308: Replace a single docstring with pass

Author: sobolevn

Lib/test/test_ast/test_ast.py

@@ -220,6 +220,29 @@ def test_negative_locations_for_compile(self):
                 # This also must not crash:
                 ast.parse(tree, optimize=2)
 
+    def test_docstring_optimization_single_node(self):
+        # https://github.com/python/cpython/issues/137308
+        for code in [
+            'class A: """Docstring"""',
+            'def func(): """Docstring"""',
+            'async def func(): """Docstring"""',
+        ]:
+            for opt_level in [0, 1, 2]:
+                with self.subTest(code=code, opt_level=opt_level):
+                    mod = ast.parse(code, optimize=opt_level)
+                    self.assertEqual(len(mod.body[0].body), 1)
+                    if opt_level == 2:
+                        self.assertIsInstance(mod.body[0].body[0], ast.Pass)
+                    else:
+                        self.assertIsInstance(mod.body[0].body[0], ast.Expr)
+                        self.assertIsInstance(
+                            mod.body[0].body[0].value,
+                            ast.Constant,
+                        )
+
+                    compile(mod, "a", "exec")
+                    compile(mod, "a", "exec", optimize=opt_level)
+
     def test_slice(self):
         slc = ast.parse("x[::]").body[0].value.slice
         self.assertIsNone(slc.upper)

Misc/NEWS.d/next/Core_and_Builtins/2025-08-02-10-27-53.gh-issue-137308.at05p_.rst

@@ -0,0 +1,3 @@
+Replace a single docstring in a node body to a :keyword:`pass`, so node's
+body is never empty. There was a :exc:`ValueError` in :func:`compile`
+otherwise.

Python/ast_preprocess.c

@@ -435,13 +435,37 @@ stmt_seq_remove_item(asdl_stmt_seq *stmts, Py_ssize_t idx)
     return 1;
 }
 
+static int
+remove_docstring(asdl_stmt_seq *stmts, Py_ssize_t idx, PyArena *ctx_)
+{
+    // In case there's just the docstring in the body, replace it with `pass`
+    // keyword, so body won't be empty.
+    if (asdl_seq_LEN(stmts) == 1) {
+        stmt_ty docstring = (stmt_ty)asdl_seq_GET(stmts, 0);
+        stmt_ty pass = _PyAST_Pass(
+            docstring->lineno, docstring->col_offset,
+            // we know that `pass` always takes 4 chars and a single line,
+            // while docstring can span on multiple lines
+            docstring->lineno, docstring->col_offset + 4,
+            ctx_
+        );
+        if (pass == NULL) {
+            return 0;
+        }
+        asdl_seq_SET(stmts, 0, pass);
+        return 1;
+    }
+    // In case there are more than 1 body items, just remove the docstring.
+    return stmt_seq_remove_item(stmts, idx);
+}
+
 static int
 astfold_body(asdl_stmt_seq *stmts, PyArena *ctx_, _PyASTPreprocessState *state)
 {
     int docstring = _PyAST_GetDocString(stmts) != NULL;
     if (docstring && (state->optimize >= 2)) {
         /* remove the docstring */
-        if (!stmt_seq_remove_item(stmts, 0)) {
+        if (!remove_docstring(stmts, 0, ctx_)) {
             return 0;
         }
         docstring = 0;