On `master` - file left with two blank lines at end

[adamtheturtle]

I have a Python file, example.py which ends with a newline:

class A:
    """
    Hello.
    """

adam@Adams-MacBook-Pro ~/D/r/vws-python (docformatter-debug)> cat example.py
class A:
    """
    Hello.
    """
adam@Adams-MacBook-Pro ~/D/r/vws-python (docformatter-debug)>

docformatter on master (and not in 1.7.7) adds an extra newline to the end of the file.
This happens since #318.
This matters to me as I wish to use Python 3.14 and only recent commits of docformatter are installable with 3.14.

[finswimmer]

Hey @adamtheturtle,

can you please provide a full reproducible example including how you call docformatter and any configuration? I'm not able to reproduce what you describe.

Given:

cat example.py
class A:
    """
    Hello.
    """

Running:

docformatter -i example.py

Result:

cat example.py
class A:
    """Hello."""

So I see no extra blank line.

fin swimmer

[adamtheturtle]

Thank you @finswimmer for looking at this.

This script demonstrates the difference (and requires uv):

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

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

ORIGINAL_CONTENT=$'class A:\n    """Hello."""\n'

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

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

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

This outputs:

Initial content:
class A:
    """Hello."""
------

docformatter stable (docformatter==1.7.7):
class A:
    """Hello."""
------

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

------

[finswimmer]

Ah, I see. In your first post it sounded like you meant, you already have one empty line after the docstring and docformatter adds an additional one.

What you show now, seems to be expected and is probably a fix. Because PEP-257 says:

Insert a blank line after all docstrings (one-line or multi-line) that document a class

fin swimmer

[adamtheturtle]

This leaves two newline characters at the end of the file. This conflicts, for example, with ruff format, black and the pre-commit hook end-of-file-fixer.

With this, docformatter --black conflicts with black, and so I still consider it a bug.

[finswimmer]

Sorry, I shouldn't have relied on the output of cat and instead opened the file in an editor. Now I see what you describe.

I would say this is a minor issue, because this only ever happen if the docstring is the last thing in the python file. I guess this only happens rarely. You can workaround it by adding ... or pass after the docstring until this is fixed.

[adamtheturtle]

Thank you for continuing to look @finswimmer .

In __init__.py it is common to only include a doctoring. In my projects, this issue arises for every __init__.py.

As a ruff user, that workaround suggestion hits https://docs.astral.sh/ruff/rules/unnecessary-placeholder/.

[adamtheturtle]

I also guess that this might be the same code that removes one of the blank lines between class definitions such as:

class A:
    """
    Hello.
    """


class B:
    """
    Hello.
    """

From PEP-8:

Surround top-level function and class definitions with two blank lines.

This is also the default for black and ruff, similarly meaning that docformatter --black does not conform to black standards.

Please let me know if you would like for me to raise a separate issue for that.

[finswimmer]

@adamtheturtle Can you try this one? #330