Regressions with v1.7.8-rc1 vs v1.7.7

[whoschek]

I just tried upgrading my project from docformatter v1.7.7 to 1.7.8rc1. I immediately reverted that upgrade because it introduces many seemingly unnecessary formatting regressions. There are too many to list here, but you can see them for yourself by changing the version in .pre-commit-config.yaml here: https://github.com/whoschek/bzfs/blob/main/.pre-commit-config.yaml#L41

and then run

pre-commit install --install-hooks; pre-commit run --all-files

I don't know if these formatting changes are intentional or not. If they are intentional, please disregard this post, and I will still appreciate docformatter. Thanks for this nice tool! Otherwise consider it as a testcase that might be helpful to weed out some corner cases.

[weibullguy]

Did you choose to make that change in response to my request on Discord or just because you like bleeding edge software?

I cloned your repository, updated to v1.7.8.-rc1, and ran pre-commit. I see 33 changes that were made.

I see two that capitalize the first word in the docstring like this.

-    """perf: Runs both I/O functions in parallel/concurrently."""
+    """Perf: Runs both I/O functions in parallel/concurrently."""

That is correct behavior, but you can add the following to your pyproject.toml to prevent this:

non-cap = [
    "perf:",
]

You can add as many words to this list of words not to capitalize when they appear as the first word in the summary as you'd like.

There are 25 changes related to blank lines following the docstring. Of these, 13 should be made according to the requirements that govern blank lines following docstrings. Those that start with PEP_257 come directly from PEP-257, the others are derived requirements to make docformatter compatible with other tools or styles.

PEP_257_6.1		Shall have one blank line after the closing triple quote (""") of a class docstring.
docformatter_8.2	Shall be one blank line after the closing triple quote (""") of a module docstring.
docformatter_8.2.1	Shall be two blank lines after the closing triple quote (""") of a module docstring when in `black` mode.
PEP_257_9.5		Shall be no blank lines after closing triple quote (""") of a function or method docstring.
docformatter_9.6	Shall be one blank line after closing triple quote (""") of a function or method docstring and inner function definition.
docformatter_9.7	Shall be two blank lines after closing triple quote (""") of a stub function docstring when the stub function contains no body.
docformatter_9.8	Shall be one blank line after closing triple quote (""") of a stub method docstring when the stub method contains no body.

The other 12 changes violate PEP_257_9.5 in that v1.7.8-rc1 is adding a second blank line before an inner function when one exists and docformatter is not in black mode. This needs to be fixed.

The other six changes also look like bugs and need to be fixed.

[whoschek]

Did you choose to make that change in response to my request on Discord or just because you like bleeding edge software?

I just randomly ran pre-commit autoupdate and the rc happened to pop up, so I tried it :-)

Thanks for taking a look! Looks like some of the issues are legit bugs after all.

There are also some cases of half garbled sentences, plus a case where an empty line before a docstring gets removed.

[weibullguy]

According to PEP-257, "There’s no blank line either before or after the docstring." So blank lines before docstrings should be removed.

The garbled sentences I saw and need to fix.

[whoschek]

The garbled sentences I saw and need to fix.

Cool. Thx!

According to PEP-257, "There’s no blank line either before or after the docstring." So blank lines before docstrings should be removed.

Are you sure this applies in this case here, where the blank line isn't immediately before the docstring but in some completely unrelated place far above, like here where there is a blank line between license an inline script metadata, like so?

# License blurb goes here ...
# See the License for the specific language governing permissions and
# limitations under the License.

# Inline script metadata conforming to https://packaging.python.org/specifications/inline-script-metadata
# /// script
# requires-python = ">=3.8"
# dependencies = []
# ///
#
"""
* docstring goes here
"""

Seems odd to remove that completely unrelated blank line far above, IMO.

[weibullguy]

Oh yeah, I saw that. I thought you meant immediately before the docstring. I just fixed this one so the blank will remain between preceding comment blocks.

[whoschek]

Oh yeah, I saw that. I thought you meant immediately before the docstring. I just fixed this one so the blank will remain between preceding comment blocks.

Ah, cool. Thx :-)

[freakboy3742]

Another data point: an upgrade to 1.7.8-rc1 has had made very weird suggestions in our code base, including completely re-ordering sentence order: beeware/rubicon-objc#622

[freakboy3742]

And another: beeware/briefcase#2418 - this one includes a bunch of changes to strings that aren't even docstrings (it's reformatting functions of the form:

def foo():
    return "this is a string"

interpreting "this is a string" as a docstring.
.