frame-docstrings

frame-docstrings rewrites every docstring to the """ form, because Python takes any string literal standing first in a module, class, or function as its docstring whatever quotes surround it, and the quotes are the docstring's frame. A '''-delimited docstring, a plain '...' or "...", and an already-""" docstring all end up on the same triple-double-quote delimiter, with a raw r prefix kept as written on the opener since PEP 257 sanctions r""" for a docstring carrying a backslash.

For a multi-line docstring the rule also puts the opening """ on its own line at the docstring's indent and drops the closing """ to its own line beneath the last content line, leaving the prose body between them as written. It runs ahead of expand-docstrings, so a requoted one-liner expands to the multi-line form in the same pass, and wrap-docstrings then wraps the description prose against its budget.

The Docstring walker reads against the PEP 257 definition, so an f-string docstring (f"""..."""), a bytes literal (b"""..."""), and a concatenated string are excluded by construction, Python assigning none of them a __doc__. The rule keeps the original quotes rather than corrupt the string where re-delimiting to """ would break it, because the body already carries a """ run or a single-line body ends in ", and a docstring whose body is blank keeps its quotes too.

Configuration

Key	Type	Default	Meaning
enabled	bool	true	Turns the rule on or off.

The Canonical Case

The opening """ of greet's multi-line docstring shares its line with Summary line starts inline with the opener. That first sentence moves to a new line beneath the opener, and every line between the delimiters stays as written.

def greet():
    """
    Summary line starts inline with the opener.
    Trailing line sits at the docstring's indent.
    """
    return 1

More Examples

The closing """ of greet's docstring shares a line with Trailing line touches the closer. The closer moves to the next line at the docstring's indent, and the body lines above it stay as written.

escape_pattern's docstring pairs an r prefix with plain "..." quotes because its body contains the \d escape. The requote to r"""...""" keeps the prefix on the opener, the raw form PEP 257 permits for a docstring containing a backslash.

summarize's docstring is written as 'A single-quoted summary.'. It requotes to """A single-quoted summary.""", because the rule identifies a docstring by its position as the first statement of the definition rather than by its quotes, and always emits """.

summarize's docstring sits between triple-single-quote delimiters, and both delimiters become """, the form PEP 257 recommends, and the body lines Summary line. and More detail here. stay exactly where they were.

BeforeAfter

No Change

render's single-quoted docstring contains a literal """ in its body. The original quotes stay and no diagnostic is emitted, because a """ frame around a body that already contains """ would end the string early.

BeforeAfter

No Change

greet's multi-line docstring already has its opening and closing """ on their own lines. The output matches the input and no diagnostic is emitted, because the rule fires only when a delimiter shares a line with body text, and neither does here.

1. 1. frame-docstrings
   2. align-colons
   3. wrap-docstrings

   render's docstring starts its summary on the """ line and carries an Args: section. frame-docstrings moves the summary off the opener line, align-colons pads the : after template, context_map, and escape_html into one column, and wrap-docstrings wraps the summary to the docstring budget across two lines.

   1. frame-docstrings
   2. align-colons
   3. wrap-docstrings
2. 1. alphabetize-siblings
   2. expand-docstrings
   3. frame-docstrings
   4. space-statements

   zeta, alpha, and beta arrive out of order, alpha with a two-line docstring and the other two with one-line docstrings. alphabetize-siblings sorts the methods, expand-docstrings rewrites the one-line docstrings of beta and zeta to multi-line form, and frame-docstrings puts every """ on its own line, with space-statements writing one blank line between the methods.

   1. alphabetize-siblings
   2. expand-docstrings
   3. frame-docstrings
   4. space-statements

Related

📰

wrap-docstrings

Docs

Wraps a docstring's description prose to docstring-line-length and its Title-case-headed sections to the budget docstring-structured-policy selects.

📰

expand-docstrings

Docs

Expands a single-line triple-quoted docstring so its opener, its body, and its closer each sit on a line of their own.

For the docstring budgets that govern wrapping, the Configuration chapter covers the description and structured line lengths.