missing-blank-line (PDF201)¶
Part of the PDF rule category.
View source · View documentation source · Search issues
Fix is always available.
What it does¶
Checks for safely provable missing blank logical lines inside docstrings.
PDF201 inserts exactly one blank line when a blank separator is required and the surrounding structure is unambiguous. It inserts a separator between a one-line summary and a following recognized structure, including convention sections, reST fields under the reST convention, standalone colon-ended lines, headings, lists, doctests, code fences, block quotes, tables, directives, literal blocks, and verbatim blocks.
With docstring-convention = "google" or docstring-convention = "numpy", PDF201 also inserts missing blank lines before recognized top-level sections. This covers a section that follows a paragraph and adjacent recognized sections. It does not insert blank lines between a section header and its content, and it does not insert blank lines between consecutive convention entries inside a section.
The docstring-blank-line-after-last-section setting controls whether a blank line is required after the final recognized Google or NumPy section. When enabled, PDF201 inserts one trailing blank after the final recognized section when that section has body content, and uses a canonical closing-quote prefix line when the closing quotes were originally on the same line as section content. The setting has no effect when the active convention does not parse the final block as a Google or NumPy section.
Generated blank-line text follows docstring-blank-line-style: blank inserts an empty line, while aligned inserts the canonical docstring margin. Generated line endings follow the resolved file line ending.
PDF201 deliberately avoids guesses. It does not split ambiguous prose, does not split a multi-line summary, does not insert separators before unrecognized text, and does not rewrite concatenated docstrings or simple literals whose evaluated lines cannot be safely mapped back to source lines.
Why is this useful?¶
Blank lines make boundaries between summaries, descriptions, structures, and sections explicit. This rule covers the cases where the parser has already identified the boundary, while leaving ambiguous prose for a human or a warning rule such as PDF203.
Ruff compatibility¶
This rule covers fixable missing-blank-line cases from Ruff's D205, D410, D411, and optionally D413 when pydocformatter can prove that a blank line is required. D413-style final-section spacing is controlled by docstring-blank-line-after-last-section.
Examples¶
Missing blank line between a one-line summary and a Google section:
docstring-convention = "google"
def area(radius: float) -> float:
"""Return the area.
Args:
radius: Circle radius.
"""
def area(radius: float) -> float:
"""Return the area.
Args:
radius: Circle radius.
"""
Missing blank lines before a section after a paragraph and before an adjacent section are inserted in one pass:
docstring-convention = "google"
def convert(value: int) -> str:
"""Convert a value.
More details about conversion.
Args:
value: Value to convert.
Returns:
str: Converted value.
"""
def convert(value: int) -> str:
"""Convert a value.
More details about conversion.
Args:
value: Value to convert.
Returns:
str: Converted value.
"""
NumPy sections are recognized only when the NumPy convention is active:
docstring-convention = "numpy"
def area(radius: float) -> float:
"""Return the area.
Parameters
----------
radius : float
Circle radius.
Returns
-------
float
Area.
"""
def area(radius: float) -> float:
"""Return the area.
Parameters
----------
radius : float
Circle radius.
Returns
-------
float
Area.
"""
Generic recognized structures after a summary are also separated:
def example() -> None:
"""Run the example.
```text
first
second
```
"""
def choices() -> None:
"""Choose a value.
- alpha
first choice
"""
def statuses() -> None:
"""Choose a status.
Accepted values:
pending, active, or disabled.
"""
def example() -> None:
"""Run the example.
```text
first
second
```
"""
def choices() -> None:
"""Choose a value.
- alpha
first choice
"""
def statuses() -> None:
"""Choose a status.
Accepted values:
pending, active, or disabled.
"""
reST fields after a summary are separated when the reST convention is active:
docstring-convention = "rest"
def value() -> int:
"""Return a value.
:returns: Computed value.
"""
def value() -> int:
"""Return a value.
:returns: Computed value.
"""
The final-section setting optionally requires one blank line after the last recognized section:
docstring-convention = "google"
docstring-blank-line-after-last-section = true
def parse(value: str) -> int:
"""Parse a value.
Args:
value: Value to parse."""
def parse(value: str) -> int:
"""Parse a value.
Args:
value: Value to parse.
"""
Aligned blank-line style inserts the canonical docstring margin on generated blank lines:
docstring-convention = "google"
docstring-blank-line-style = "aligned"
def area(radius: float) -> float:
"""Return the area.
Args:
radius: Circle radius.
"""
def area(radius: float) -> float:
"""Return the area.
Args:
radius: Circle radius.
"""
Existing whitespace-only separators are not duplicated; PDF103 can normalize their exact whitespace spelling separately:
docstring-convention = "google"
def area(radius: float) -> float:
"""Return the area.
Args:
radius: Circle radius.
"""
Ambiguous prose and multi-line summaries are unchanged:
def area(radius: float) -> float:
"""Return the area
after validating the radius.
"""
def other() -> None:
"""Summary.
Body text that could be prose.
"""
Unsafe source mappings are skipped:
docstring-convention = "google"
def escaped() -> None:
"""Summary.\nArgs:\n value: Description."""
def concatenated() -> None:
("Summary.\n"
"Args:\n"
" value: Description.")
Options¶
docstring-blank-line-style: Controls whether inserted blank docstring lines are empty or aligned to the docstring indentation.docstring-blank-line-after-last-section: Requires one trailing blank line after the final recognized section when enabled.indent-style: Indentation style used when inserted blank lines need generated indentation.indent-width: Indentation width used when inserted blank lines need generated indentation and tab measurement.