[pydocstyle] Escaped docstring in docstring (D301 )

[ukyen8]

Summary

This PR updates D301 rule to allow inclduing escaped docstring, e.g. \"""Foo.\""" or \"\"\"Bar.\"\"\", within a docstring.

Related issue: #12152

Test Plan

Add more test cases to D301.py and update the snapshot file.

[charliermarsh]

We likely also need to handle single quotes here (i.e., escaped single quotes within single-quote docstrings).

[ukyen8]

But D301 is based on double quotes, do we need to cover single-quote docstring here?

[MichaReiser]

I haven't verified this myself but the way I read the code is that docstrings are extracted from any string literal

ruff/crates/ruff_linter/src/docstrings/extraction.rs

Lines 6 to 15 in 7d16f83

	/// Extract a docstring from a function or class body.
	pub(crate) fn docstring_from(suite: &[Stmt]) -> Option<&ast::ExprStringLiteral> {
	let stmt = suite.first()?;
	// Require the docstring to be a standalone expression.
	let Stmt::Expr(ast::StmtExpr { value, range: _ }) = stmt else {
	return None;
	};
	// Only match strings.
	value.as_string_literal_expr()
	}

[MichaReiser]

This will panic if what comes after the \ is shorter than 3 characters. I would rewrite this to something like

Suggested change

	let escaped_triple_quotes =
	&bytes[position.saturating_add(1)..position.saturating_add(4)];
	if escaped_triple_quotes == b"\"\"\"" || escaped_triple_quotes == b"\'\'\'" {
	return false;
	}
	let after_first_backslash = &bytes[position + 1..];
	let is_escaped_triple = after_first_backslash.starts_with(b"\"\"\"")
	|| after_first_backslash.starts_with(b"\'\'\'");
	if is_escaped_triple {
	return false;
	}

[MichaReiser]

I don't think this assumption is correct and this might actually a bug in the existing implementation. For example, the function passed to any will be called twice for \\, once for each backslash position but the offsets aren't to indices apart.

What I understand is that you want to track if you're at the beginning of an escape sequence.

This is not fully fledged out, but I think we may have to rewrite the entire loop

    while let Some(position) = memchr::memchr(b'\\', &bytes[offset..]) {
        let after_escape = &body[position + 1..];
        let next_char_len = after_escape.chars().next().unwrap_or_default();

        let Some(escaped_char) = &after_escape.chars().next() else {
            break;
        };

        if matches!(escaped_char, '"' | '\'') {
            let is_escaped_triple =
                after_escape.starts_with("\"\"\"") || after_escape.starts_with("\'\'\'");

            if is_escaped_triple {
                // don't add a diagnostic
            }
            
            if position != 0 && offset == position {
                // An escape sequence, e.g. `\a\b`
            }
        }
        
        

        offset = position + escaped_char.len_utf8();
    }

[ukyen8]

Thank you. This helps a lot!

[charliermarsh]

Thanks!