feat(patterns): improve handling of field and section lists for mixed-style docstrings

Improve handling of field and section lists for mixed-style docstrings

- Refactor field list detection to preserve Google/NumPy sections when using Sphinx/Epytext styles.
- Update list pattern recognition to distinguish between field-based and section-based styles.
- Ensure only the appropriate sections are wrapped, preserving formatting for others.
- Update description splitting logic to wrap only the description before a preserved section.
- Add force_wrap shortcut to always wrap as regular text.
- Update test data to reflect new logic (NumPy sections in Sphinx-style docs are now preserved).
- Improves compliance with requirements for mixed-style docstrings and prevents unwanted wrapping.

Author: jaysheeldodia

src/docformatter/patterns/fields.py

@@ -77,7 +77,39 @@ def do_find_field_lists(
             for _field in re.finditer(SPHINX_REGEX, text)
         ]
         _wrap_parameters = True
-
+    elif style == "google":
+        _field_idx = [
+            (_field.start(0), _field.end(0))
+            for _field in re.finditer(GOOGLE_REGEX, text, re.MULTILINE)
+        ]
+        _wrap_parameters = False  # Don't wrap Google-style field lists
+    elif style == "numpy":
+        _field_idx = [
+            (_field.start(0), _field.end(0))
+            for _field in re.finditer(NUMPY_REGEX, text, re.MULTILINE)
+        ]
+        _wrap_parameters = False  # Don't wrap NumPy-style field lists
+    
+    # If no field lists were found for the current style, check for field lists
+    # from other styles and preserve them as-is (don't wrap).
+    if not _field_idx:
+        # Check for Google-style field lists (e.g., "Args:", "Returns:").
+        # Use a more specific pattern that only matches known Google section names.
+        google_sections = r'^ *(Args|Arguments|Attributes|Example|Examples|Note|Notes|' \
+                         r'See Also|References|Returns|Return|Raises|Raise|Yields|Yield|' \
+                         r'Warns|Warning|Warnings|Receives|Receive|Other Parameters):$'
+        google_matches = list(re.finditer(google_sections, text, re.MULTILINE))
+        if google_matches:
+            _field_idx = [(_field.start(0), _field.end(0)) for _field in google_matches]
+            _wrap_parameters = False
+        
+        # If still nothing, check for NumPy-style field lists
+        if not _field_idx:
+            numpy_matches = list(re.finditer(NUMPY_REGEX, text, re.MULTILINE))
+            if numpy_matches:
+                _field_idx = [(_field.start(0), _field.end(0)) for _field in numpy_matches]
+                _wrap_parameters = False
+                
     return _field_idx, _wrap_parameters
 
 

src/docformatter/patterns/lists.py

@@ -83,24 +83,48 @@ def is_type_of_list(
     if is_field_list(text, style):
         return False
 
-    return any(
-        (
+    # Check for various list patterns
+    for line in split_lines:
+        # Always check for non-field-list patterns
+        if (
             is_bullet_list(line)
             or is_enumerated_list(line)
             or is_rest_section_header(line)
             or is_option_list(line)
-            or is_epytext_field_list(line)
-            or is_sphinx_field_list(line)
-            or is_numpy_field_list(line)
-            or is_numpy_section_header(line)
-            or is_google_field_list(line)
-            or is_user_defined_field_list(line)
             or is_literal_block(line)
             or is_inline_math(line)
             or is_alembic_header(line)
-        )
-        for line in split_lines
-    )
+            or is_user_defined_field_list(line)
+        ):
+            return True
+        
+        # For field list patterns from other styles:
+        # - When using epytext or sphinx (field-based styles), do NOT treat
+        #   section-based styles (Google/NumPy) as lists to skip. Instead, return
+        #   False so that do_split_description can wrap the description while
+        #   preserving the field sections.
+        # - When using numpy or google (section-based styles), check for all field
+        #   list patterns to maintain backward compatibility.
+        if style in ("numpy", "google"):
+            # For numpy and google styles, check all field list patterns
+            if (
+                is_epytext_field_list(line)
+                or is_sphinx_field_list(line)
+                or is_numpy_field_list(line)
+                or is_numpy_section_header(line)
+                or is_google_field_list(line)
+            ):
+                return True
+        elif style in ("epytext", "sphinx"):
+            # For field-based styles, only check for OTHER field-based styles
+            if style != "epytext" and is_epytext_field_list(line):
+                return True
+            if style != "sphinx" and is_sphinx_field_list(line):
+                return True
+            # Do NOT check for Google/NumPy patterns - they'll be preserved by
+            # do_split_description
+    
+    return False
 
 
 def is_bullet_list(line: str) -> Union[Match[str], None]:

src/docformatter/strings.py

@@ -298,7 +298,7 @@ def do_split_description(
         _url_idx,
     )
 
-    if not _url_idx and not (_field_idx and _wrap_fields):
+    if not _url_idx and not _field_idx:
         return description_to_list(
             text,
             indentation,
@@ -314,7 +314,7 @@ def do_split_description(
             wrap_length,
         )
 
-    if _field_idx:
+    if _field_idx and _wrap_fields:
         _lines, _text_idx = _wrappers.do_wrap_field_lists(
             text,
             _field_idx,
@@ -323,6 +323,24 @@ def do_split_description(
             indentation,
             wrap_length,
         )
+    elif _field_idx and not _wrap_fields:
+        # Field lists were found but should not be wrapped (e.g., Google/NumPy style
+        # when using a different style). Wrap the text before the first field list,
+        # then preserve the rest as-is.
+        _lines.extend(
+            description_to_list(
+                text[_text_idx : _field_idx[0][0]],
+                indentation,
+                wrap_length,
+            )
+        )
+        # Add the field list section as-is, preserving original formatting.
+        # The text has already been reindented by do_wrap_description, so we
+        # just preserve the lines as they are.
+        _field_section = text[_field_idx[0][0]:].splitlines()
+        for line in _field_section:
+            _lines.append(line if line.strip() else "")
+        _text_idx = len(text)
     else:
         # Finally, add everything after the last URL or field list directive.
         _lines += _wrappers.do_close_description(text, _text_idx, indentation)

src/docformatter/wrappers/description.py

@@ -95,6 +95,13 @@ def do_wrap_description(  # noqa: PLR0913
     ):
         return text
 
+    # When force_wrap is True, wrap everything as regular text without special
+    # handling for field lists.
+    if force_wrap:
+        return indentation + "\n".join(
+            _strings.description_to_list(text, indentation, wrap_length)
+        ).strip()
+    
     lines = _strings.do_split_description(text, indentation, wrap_length, style)
 
     return indentation + "\n".join(lines).strip()

tests/_data/string_files/description_wrappers.toml

@@ -54,7 +54,8 @@ This is a long description from a docstring that will contain an heuristic list.
         Item 3
 """
 expected = """
-    This is a long description from a docstring that will contain an heuristic list.  The description shouldn't get wrapped at all.
+    This is a long description from a docstring that will contain an
+    heuristic list.  The description shouldn't get wrapped at all.
 
         Example:
             Item one

tests/_data/string_files/list_patterns.toml

@@ -126,7 +126,7 @@ Parameters
 """
 strict = false
 style = "sphinx"
-expected = true
+expected = false  # Changed from true: NumPy sections in Sphinx docs should be preserved, not skip wrapping
 
 [is_google_list_numpy_style]
 instring = """\