one-line-docstring (PDF110)¶

Part of the PDF rule category.

View source · View documentation source · Search issues

Fix is always available.

What it does¶

Checks safely mapped simple multiline docstrings whose complete non-blank content is exactly one parsed summary line. If the whole docstring literal can be rendered on one physical source line without exceeding line-length, PDF110 collapses the opening quotes, summary, and closing quotes onto that line.

The line-length check uses the complete resulting physical source line, including indentation, any source before the literal, the full rendered string literal, and any same-line source after the literal. Tabs are measured using indent-width.

PDF110 only rewrites summary-only docstrings. It does not collapse docstrings with a body, paragraph, section, recognized structure, blank-only content, or a summary that spans multiple logical lines. It also skips true one-line docstrings, concatenated docstrings, and simple literals whose evaluated lines cannot be mapped safely back to physical source lines.

When a summary starts or ends with the quote delimiter character, PDF110 keeps valid Python source by using a value-preserving escape where possible, or a minimal separator space when escaping is not possible. That separator fallback can add a leading or trailing space to the evaluated __doc__ value.

Parsing settings and the active convention affect what counts as a recognized structure. For example, a single list item, heading, doctest, directive, reST field under the reST convention, or block quote is protected and is not treated as a plain summary. Disabling the matching docstring-parse-* setting can make generic structures eligible for collapse if they are then parsed as a single summary line.

Why is this useful?¶

Single-line docstrings are easier to scan when their complete content fits comfortably on one source line.

Ruff compatibility¶

This rule is intended to replace Ruff's D200 while respecting the configured line length before collapsing a docstring. Ruff's D200 fix is unsafe because it can create overlong source lines; PDF110 checks the final physical source line first.

Examples¶

The canonical PDF110 fix collapses a multiline docstring that contains only one summary line:

def area(radius: float) -> float:
    """
    Return the area.
    """

def area(radius: float) -> float:
    """Return the area."""

Module, class, function, and method docstrings are all considered. Same-line source after the closing quotes is preserved:

"""
Module summary.
"""

class Circle:
    """
    Circle model.
    """

    def area(self) -> float:
        """
        Return the area.
        """  # public API

"""Module summary."""

class Circle:
    """Circle model."""

    def area(self) -> float:
        """Return the area."""  # public API

Space/tab-only logical lines around the summary are removed as part of the collapse, but content whitespace on the summary line itself is preserved:

def stripped() -> None:
    """  

    Return the area.

    """

def leading_space() -> None:
    """  Summary with leading spaces.
    """

def stripped() -> None:
    """Return the area."""

def leading_space() -> None:
    """  Summary with leading spaces."""

PDF110 only collapses when the complete resulting source line fits within line-length:

line-length = 19

def area(radius: float) -> float:
    """
    Return the area.
    """

Same-line prefix and suffix source are included in the line-length check:

line-length = 39

def area(radius: float) -> float: """
    Return the area.
    """; return 0.0

Tabs are measured using the configured indent-width:

line-length = 22
indent-width = 4

def area() -> float:
    """
    Return area.
    """

def area() -> float:
    """Return area."""

Docstrings with a body, a paragraph, or a multi-line summary are unchanged:

def body() -> None:
    """Summary.

    Body.
    """

def wrapped() -> None:
    """Summary line
    continuation line.
    """

Recognized structures are not treated as summary-only docstrings:

docstring-convention = "google"

def section(value: int) -> None:
    """
    Args:
        value: Input value.
    """

def list_item() -> None:
    """
    - item
    """

reST fields are protected only under the reST convention:

docstring-convention = "rest"

def value() -> int:
    """
    :returns: Computed value.
    """

If the relevant structure parser is disabled, the same text can become a plain one-line summary and be collapsed:

docstring-parse-list-items = false

def list_item() -> None:
    """
    - item
    """

def list_item() -> None:
    """- item"""

PDF110 preserves the original string prefix and quote delimiter when possible, and escapes quote collisions when needed:

def raw_path() -> None:
    r'''
    Path C:\\temp.
    '''

def quoted() -> None:
    """
    "quoted"
    """

def raw_path() -> None:
    r'''Path C:\\temp.'''

def quoted() -> None:
    """\"quoted\""""

Concatenated docstrings are skipped. Safely mapped escapes remain exact when a multiline docstring is collapsed:

def concatenated() -> None:
    ("Summary "
     "text.")

def escaped() -> None:
    """
    Summary with tab\t escape.
    """

def concatenated() -> None:
    ("Summary "
     "text.")

def escaped() -> None:
    """Summary with tab\t escape."""

Options¶

• line-length: Maximum display width allowed for the complete collapsed source line.
• indent-width: Tab display width used when measuring the collapsed source line.