add numpydoc section name checker

Author: akaszynski

.gitignore

@@ -4,3 +4,4 @@ dist/
 docs/_build
 
 .coverage
+*.pyc

pydocstringformatter/_formatting/__init__.py

@@ -16,6 +16,7 @@
 from pydocstringformatter._formatting.formatters_numpydoc import (
     NumpydocNameColonTypeFormatter,
     NumpydocSectionHyphenLengthFormatter,
+    NumpydocSectionNameFormatter,
     NumpydocSectionOrderingFormatter,
     NumpydocSectionSpacingFormatter,
 )
@@ -35,6 +36,7 @@
     NumpydocNameColonTypeFormatter(),
     NumpydocSectionSpacingFormatter(),
     NumpydocSectionHyphenLengthFormatter(),
+    NumpydocSectionNameFormatter(),
     LineWrapperFormatter(),
     BeginningQuotesFormatter(),
     ClosingQuotesFormatter(),

pydocstringformatter/_formatting/formatters_numpydoc.py

@@ -4,29 +4,31 @@
 
 from pydocstringformatter._formatting.base import NumpydocSectionFormatter
 
+NUMPYDOC_SECTIONS = (
+    "Summary",
+    "Parameters",
+    "Attributes",
+    "Methods",
+    "Returns",
+    "Yields",
+    "Receives",
+    "Other Parameters",
+    "Raises",
+    "Warns",
+    "Warnings",
+    "See Also",
+    "Notes",
+    "References",
+    "Examples",
+)  # Order must match numpydoc
+
 
 class NumpydocSectionOrderingFormatter(NumpydocSectionFormatter):
     """Change section order to match numpydoc guidelines."""
 
     name = "numpydoc-section-order"
 
-    numpydoc_section_order = (
-        "Summary",
-        "Parameters",
-        "Attributes",
-        "Methods",
-        "Returns",
-        "Yields",
-        "Receives",
-        "Other Parameters",
-        "Raises",
-        "Warns",
-        "Warnings",
-        "See Also",
-        "Notes",
-        "References",
-        "Examples",
-    )
+    numpydoc_section_order = NUMPYDOC_SECTIONS
 
     def treat_sections(
         self, sections: OrderedDict[str, list[str]]
@@ -105,6 +107,22 @@ def treat_sections(
         return sections
 
 
+class NumpydocSectionNameFormatter(NumpydocSectionFormatter):
+    """Check if sections are named correctly."""
+
+    name = "numpydoc-section-name-checker"
+
+    def treat_sections(
+        self, sections: OrderedDict[str, list[str]]
+    ) -> OrderedDict[str, list[str]]:
+        """Ensure proper spacing between sections."""
+        for section_name in sections:
+            if section_name not in NUMPYDOC_SECTIONS:
+                raise ValueError(f"Invalid section_name '{section_name}'")
+
+        return sections
+
+
 class NumpydocSectionHyphenLengthFormatter(NumpydocSectionFormatter):
     """Ensure hyphens after section header lines are proper length."""
 

pydocstringformatter/run.py

@@ -128,6 +128,9 @@ def format_file_tokens(
             UnstableResultError::
                 If the formatters are not able to get to a stable result.
                 It reports what formatters are still modifying the tokens.
+            RuntimeError::
+                If a formatter fails to apply on a docstring. It reports which
+                file and which line numbers where the formatter failed.
         """
         formatted_tokens: list[tokenize.TokenInfo] = []
         is_changed = False
@@ -136,7 +139,13 @@ def format_file_tokens(
             new_tokeninfo = tokeninfo
 
             if _utils.is_docstring(new_tokeninfo, tokens[index - 1]):
-                new_tokeninfo, changers = self.apply_formatters(new_tokeninfo)
+                try:
+                    new_tokeninfo, changers = self.apply_formatters(new_tokeninfo)
+                except Exception as err:
+                    start, end = new_tokeninfo.start[0], new_tokeninfo.end[0]
+                    raise RuntimeError(
+                        f"In {filename} L{start}-L{end}:\n\n{err}"
+                    ) from err
                 is_changed = is_changed or bool(changers)
 
                 # Run formatters again (3rd time) to check if the result is stable