Skip to content

fix: leave docstrings with a backslash line continuation alone - #416

Open
Kernel-Hunter wants to merge 2 commits into
PyCQA:masterfrom
Kernel-Hunter:fix-docstring-backslash-continuation
Open

Kernel-Hunter wants to merge 2 commits into
PyCQA:masterfrom
Kernel-Hunter:fix-docstring-backslash-continuation

Conversation

@Kernel-Hunter

@Kernel-Hunter Kernel-Hunter commented Nov 16, 2026 •

Copy link
Copy Markdown

A docstring that starts with a backslash line continuation gets a literal backslash in its text after formatting. This module docstring comes from CPython's socket.py:

"""\
This module provides socket operations and some related functions.
On Unix, it supports IP (Internet Protocol) and Unix domain sockets.
"""

docformatter turns it into

"""\ This module provides socket operations and some related functions.

On Unix, it supports IP (Internet Protocol) and Unix domain sockets.
"""

The backslash used to join the lines. Now \ is an invalid escape that keeps the backslash, so __doc__ starts with \ This module and Python warns about the escape sequence. The same happens for a continuation in the middle of a description (goes on \ followed by and continues becomes goes on \ and continues), and for raw docstrings.

_do_format_docstring now returns the docstring unchanged when any line of it ends in an odd number of backslashes, which is a continuation. Docstrings with an even run, a literal backslash, are still formatted. I found it by running docformatter over the 150 top-level stdlib modules and comparing each docstring's text before and after.

tests/formatter/test_docstring_line_continuation.py covers a leading continuation, a method docstring, a continuation inside the description and a raw docstring. All four fail on master. The rest of tests/formatter and tests/test_string_functions.py pass; the end-to-end tests that error in my checkout (29, a missing VIRTUAL_ENV variable in my shell) error the same way on master.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants