Skip to content

Incompatibility between --black spacing after docstring on master and what black expects #331

@adamtheturtle

Description

@adamtheturtle

docformatter 1.7.7 with --black and black are both happy with the following snippet:

"""
A
"""

pass

However, docformatter on master with --black adds an extra newline after the docstring, which makes the code incompatible with black.

Reproduction script

This script (which requires uv) demonstrates the difference between black's expectation and docformatter --black. It also demonstrates that #330 does not resolve the incompatibility.

#!/usr/bin/env bash
set -euo pipefail

DOCFORMATTER_STABLE="docformatter==1.7.7"
DOCFORMATTER_MASTER_REF="git+https://github.com/PyCQA/docformatter@7798699c0a9ddcc41a16b4dd7b8e216443f78792"
DOCFORMATTER_FINSWIMMER_REF="git+https://github.com/finswimmer/docformatter@948c28a5d43106bad3ec796fdf26f87cbdaee085"

ORIGINAL_CONTENT=$'"""\nA\n"""\n\npass\n'

echo "Initial content:"
printf '%s' "$ORIGINAL_CONTENT"
echo "------"

echo
echo "black:"
printf '%s' "$ORIGINAL_CONTENT" | uvx --python=3.13 --with="black==25.11.0" black -q -
echo "------"

echo
echo "docformatter stable (${DOCFORMATTER_STABLE}):"
printf '%s' "$ORIGINAL_CONTENT" | uvx --python=3.13 --from "${DOCFORMATTER_STABLE}" docformatter --black -
echo "------"

echo
echo "docformatter master (${DOCFORMATTER_MASTER_REF}):"
printf '%s' "$ORIGINAL_CONTENT" | uvx --python=3.13 --from "${DOCFORMATTER_MASTER_REF}" docformatter --black -
echo "------"

echo
echo "docformatter finswimmer (${DOCFORMATTER_FINSWIMMER_REF}):"
printf '%s' "$ORIGINAL_CONTENT" | uvx --python=3.13 --from "${DOCFORMATTER_FINSWIMMER_REF}" docformatter --black -
echo "------"

Reproduction script output

Initial content:
"""
A
"""

pass
------

black:
"""
A
"""

pass
------

docformatter stable (docformatter==1.7.7):
"""
A
"""

pass
------

docformatter master (git+https://github.com/PyCQA/docformatter@7798699c0a9ddcc41a16b4dd7b8e216443f78792):
"""
A
"""


pass
------

docformatter finswimmer (git+https://github.com/finswimmer/docformatter@948c28a5d43106bad3ec796fdf26f87cbdaee085):
"""
A
"""


pass
------

Prior discussion

From @finswimmer at #330 (comment):

I'm not sure how to handle the conflict with black. The code clearly says, that it will ensure 2 empty line follow the module docstring. I couldn't find enough information what the current behavior of black should. There are some older issue that state that 2 lines are intended, e.g. psf/black#4027 So can you please open a separate issue for this and hopefully @weibullguy can clarify how they like to proceed with this?

Metadata

Metadata

Assignees

No one assigned

    Labels

    freshThis is a new issue

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions