Regression: HEAD messes up numpy-style docstrings

[Wuestengecko]

Hi! The current git HEAD (d9ace1f) running on Python 3.13 appears to have a regression around handling docstrings that follow the numpy convention. While previous versions up to (including) v1.7.7 "handled" those by simply ignoring them entirely, HEAD treats them as normal docstrings made up of simple, unformatted paragraphs.

Consider this demo function:

def numpy(n: int, colors: bool) -> int:
    """Do a number of things.

    Parameters
    ----------
    n
        How many things to do.
    colors
        True to paint the things in bright colors, False to keep them
        dull and grey.

    Returns
    -------
    int
        How many things were actually done.
    """
    return n

v1.7.7 does not touch this file at all, as it detects the Numpy-style formatting and knows it can't handle that. HEAD however seems to have lost this detection logic:

docformatter numpytest.py
--- before/numpytest.py
+++ after/numpytest.py
@@ -1,17 +1,9 @@
 def numpy(n: int, colors: bool) -> int:
     """Do a number of things.

-    Parameters
-    ----------
-    n
-        How many things to do.
-    colors
-        True to paint the things in bright colors, False to keep them
-        dull and grey.
+    Parameters ---------- n     How many things to do. colors     True to paint the
+    things in bright colors, False to keep them     dull and grey.

-    Returns
-    -------
-    int
-        How many things were actually done.
+    Returns ------- int     How many things were actually done.
     """
     return n

Interestingly, HEAD also does not touch this file when copying the type annotations from the function signature into the docstring, like:

    Parameters
    ----------
    n : int                     # <- This bit
        How many things to do.

---

Bisecting has led me to the big squash-merge of #318. Digging further into it (git fetch origin +refs/pull/318/head:refs/heads/pr-318) leads to a bunch of consecutive commits which are broken and can't be individually tested. They form a huge refactor over several thousands of lines:

$ git bisect next
There are only 'skip'ped commits left to test.
The first bad commit could be any of:
86ffee2ed4735f6d920d268417c0f06c2522fb0c
9f45b298ea0512a596318d76572907e3856b819e
3e931a174bd9d005f46d3c328e235ab367fc60ae
a31913c304aa13b2c0c814f86ccf330febda7a02
75caaf32a2b2bb69199480335b0422a08a2d6c6a
b9585ad8245c8b238c3d996bc17241e721465fda
f2e8b9bc4f7168c0fb96a8e5e59326ed22763056
We cannot bisect more!

$ git log --format=oneline 75caaf32\^..f2e8b9bc
f2e8b9bc4f7168c0fb96a8e5e59326ed22763056 refactor: add function to have field lists take precedence over URL strings
b9585ad8245c8b238c3d996bc17241e721465fda refactor: move string manipulation functions from syntax module
3e931a174bd9d005f46d3c328e235ab367fc60ae refactor: add new module with functions for wrapping various elements
9f45b298ea0512a596318d76572907e3856b819e refactor: add new module with functions for detecting various types of patterns
86ffee2ed4735f6d920d268417c0f06c2522fb0c refactor: add new module with constant values
a31913c304aa13b2c0c814f86ccf330febda7a02 refactor: add new module with functions for classifying docstring types
75caaf32a2b2bb69199480335b0422a08a2d6c6a refactor: split long functions/methods into smaller functions

$ git diff --stat 75caaf32\^..f2e8b9bc
 src/docformatter/__init__.py                       |  11 +-
 src/docformatter/classify.py                       | 479 ++++++++++
 src/docformatter/constants.py                      | 232 +++++
 src/docformatter/format.py                         | 932 ++++++++++++++-----
 src/docformatter/patterns/__init__.py              |  36 +
 src/docformatter/patterns/fields.py                | 229 +++++
 src/docformatter/patterns/headers.py               | 143 +++
 src/docformatter/patterns/lists.py                 | 233 +++++
 src/docformatter/patterns/misc.py                  | 124 +++
 src/docformatter/patterns/rest.py                  |  58 ++
 src/docformatter/patterns/url.py                   |  84 ++
 src/docformatter/strings.py                        | 306 +++++--
 src/docformatter/syntax.py                         | 997 ---------------------
 src/docformatter/util.py                           | 111 ++-
 src/docformatter/wrappers/__init__.py              |  34 +
 src/docformatter/wrappers/description.py           | 133 +++
 src/docformatter/wrappers/fields.py                | 174 ++++
 src/docformatter/wrappers/summary.py               |  50 ++
 src/docformatter/wrappers/url.py                   | 101 +++
 tests/_data/string_files/format_black.toml         |  75 --
 tests/_data/string_files/format_code.toml          | 324 -------
 tests/_data/string_files/format_code_ranges.toml   |  58 --
 tests/_data/string_files/format_epytext.toml       |  52 --
 tests/_data/string_files/format_lists.toml         |  80 --
 tests/_data/string_files/format_sphinx.toml        | 285 ------
 tests/_data/string_files/format_style_options.toml |  38 -
 tests/_data/string_files/format_urls.toml          | 648 -------------
 tests/_data/string_files/format_wrap.toml          | 133 ---
 tests/formatter/test_format_black.py               | 169 ----
 tests/formatter/test_format_code.py                | 609 -------------
 tests/formatter/test_format_code_ranges.py         | 107 ---
 tests/formatter/test_format_epytext.py             | 133 ---
 tests/formatter/test_format_lists.py               | 152 ----
 tests/formatter/test_format_sphinx.py              | 512 -----------
 tests/formatter/test_format_styles.py              | 147 ---
 tests/formatter/test_format_urls.py                | 674 --------------
 tests/formatter/test_format_wrap.py                | 407 ---------
 tests/test_strip_docstring.py                      | 222 -----
 38 files changed, 3133 insertions(+), 6159 deletions(-)

[finswimmer]

Hey @Wuestengecko,

can you please try if #339 fixes the issue?

fins wimmer