docstring-format-checker 1.6.0__tar.gz → 1.6.2__tar.gz

{docstring_format_checker-1.6.0 → docstring_format_checker-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 1.6.0
+Version: 1.6.2
 Summary: A CLI tool to check and validate Python docstring formatting and completeness
 Author: Chris Mahoney
 Author-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>

{docstring_format_checker-1.6.0 → docstring_format_checker-1.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "1.6.0"
+version = "1.6.2"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"

{docstring_format_checker-1.6.0 → docstring_format_checker-1.6.2}/src/docstring_format_checker/cli.py

@@ -543,8 +543,19 @@ def _format_error_output(error: DocstringError) -> list[str]:
     """
     lines: list[str] = [_create_error_header(error)]
     individual_errors: list[str] = _split_error_messages(error.message)
+
     for individual_error in individual_errors:
-        lines.append(f"    - {individual_error}")
+        # Check if this error has multi-line content (e.g., parameter type mismatches)
+        if "\n" in individual_error:
+            # Split by newlines and add 4 spaces of extra indentation to each line
+            error_lines = individual_error.split("\n")
+            lines.append(f"    - {error_lines[0]}")  # First line gets the bullet
+            for sub_line in error_lines[1:]:
+                if sub_line.strip():  # Only add non-empty lines
+                    lines.append(f"    {sub_line}")  # Continuation lines get 4 spaces
+        else:
+            lines.append(f"    - {individual_error}")
+
     return lines
 
 

{docstring_format_checker-1.6.0 → docstring_format_checker-1.6.2}/src/docstring_format_checker/core.py

@@ -559,10 +559,14 @@ class DocstringChecker:
 
         errors: list[str] = []
 
-        # Validate required sections
+        # Validate required sections are present
         required_section_errors: list[str] = self._validate_all_required_sections(docstring, item)
         errors.extend(required_section_errors)
 
+        # Validate all existing sections (required or not)
+        existing_section_errors: list[str] = self._validate_all_existing_sections(docstring, item)
+        errors.extend(existing_section_errors)
+
         # Perform comprehensive validation checks
         comprehensive_errors: list[str] = self._perform_comprehensive_validation(docstring)
         errors.extend(comprehensive_errors)
@@ -578,10 +582,33 @@ class DocstringChecker:
                 item_type=item.item_type,
             )
 
+    def _is_params_section_required(self, item: FunctionAndClassDetails) -> bool:
+        """
+        !!! note "Summary"
+            Check if params section is required for this item.
+
+        Params:
+            item (FunctionAndClassDetails):
+                The function or class details.
+
+        Returns:
+            (bool):
+                True if params section is required, False otherwise.
+        """
+
+        # For classes, params section not required (attributes handled differently)
+        if isinstance(item.node, ast.ClassDef):
+            return False
+
+        # For functions, only required if function has parameters (excluding self/cls)
+        # item.node is guaranteed to be FunctionDef or AsyncFunctionDef due to type constraints
+        params = [arg.arg for arg in item.node.args.args if arg.arg not in ("self", "cls")]
+        return len(params) > 0
+
     def _validate_all_required_sections(self, docstring: str, item: FunctionAndClassDetails) -> list[str]:
         """
         !!! note "Summary"
-            Validate all required sections are present and valid.
+            Validate all required sections are present.
 
         Params:
             docstring (str):
@@ -591,115 +618,127 @@ class DocstringChecker:
 
         Returns:
             (list[str]):
-                List of validation error messages.
+                List of validation error messages for missing required sections.
         """
 
         errors: list[str] = []
         for section in self.required_sections:
-            section_error = self._validate_single_required_section(docstring, section, item)
-            if section_error:
-                errors.append(section_error)
+            # Special handling for params section - only required if function/class has parameters
+            if section.name.lower() == "params":
+                if not self._is_params_section_required(item):
+                    continue
+
+            # Only check if the section exists, don't validate content yet
+            if not self._section_exists(docstring, section):
+                errors.append(f"Missing required section: {section.name}")
         return errors
 
-    def _validate_single_required_section(
-        self, docstring: str, section: SectionConfig, item: FunctionAndClassDetails
-    ) -> Optional[str]:
+    def _validate_all_existing_sections(self, docstring: str, item: FunctionAndClassDetails) -> list[str]:
         """
         !!! note "Summary"
-            Validate a single required section based on its type.
+            Validate content of all existing sections (required or not).
 
         Params:
             docstring (str):
                 The docstring to validate.
-            section (SectionConfig):
-                The section configuration to validate against.
             item (FunctionAndClassDetails):
                 The function or class details.
 
         Returns:
-            (Optional[str]):
-                Error message if validation fails, None otherwise.
+            (list[str]):
+                List of validation error messages for invalid section content.
         """
 
-        if section.type == "free_text":
-            return self._validate_free_text_section(docstring, section)
-        elif section.type == "list_name_and_type":
-            return self._validate_list_name_and_type_section(docstring, section, item)
-        elif section.type == "list_type":
-            return self._validate_list_type_section(docstring, section)
-        elif section.type == "list_name":
-            return self._validate_list_name_section(docstring, section)
-        return None
+        errors: list[str] = []
+        for section in self.config.sections:
+            # Only validate if the section actually exists in the docstring
+            if self._section_exists(docstring, section):
+                section_error = self._validate_single_section_content(docstring, section, item)
+                if section_error:
+                    errors.append(section_error)
+        return errors
 
-    def _validate_free_text_section(self, docstring: str, section: SectionConfig) -> Optional[str]:
+    def _section_exists(self, docstring: str, section: SectionConfig) -> bool:
         """
         !!! note "Summary"
-            Validate free text sections.
+            Check if a section exists in the docstring.
 
         Params:
             docstring (str):
-                The docstring to validate.
+                The docstring to check.
             section (SectionConfig):
                 The section configuration.
 
         Returns:
-            (Optional[str]):
-                Error message if section is missing, None otherwise.
+            (bool):
+                `True` if section exists, `False` otherwise.
         """
 
-        if not self._check_free_text_section(docstring, section):
-            return f"Missing required section: {section.name}"
-        return None
+        section_name: str = section.name.lower()
 
-    def _validate_list_name_and_type_section(
+        # For free text sections, use the existing logic from _check_free_text_section
+        if section.type == "free_text":
+            return self._check_free_text_section(docstring, section)
+
+        # Check for admonition style sections (for non-free-text types)
+        if section.admonition and isinstance(section.admonition, str):
+            if section.prefix and isinstance(section.prefix, str):
+                # e.g., "!!! note" or "???+ abstract"
+                pattern: str = rf"{re.escape(section.prefix)}\s+{re.escape(section.admonition)}"
+                if re.search(pattern, docstring, re.IGNORECASE):
+                    return True
+
+        # Check for standard sections with colons (e.g., "Params:", "Returns:")
+        pattern = rf"^[ \t]*{re.escape(section_name)}:[ \t]*$"
+        if re.search(pattern, docstring, re.IGNORECASE | re.MULTILINE):
+            return True
+
+        return False
+
+    def _validate_single_section_content(
         self, docstring: str, section: SectionConfig, item: FunctionAndClassDetails
     ) -> Optional[str]:
         """
         !!! note "Summary"
-            Validate list_name_and_type sections (params, returns).
+            Validate the content of a single section based on its type.
 
         Params:
             docstring (str):
                 The docstring to validate.
             section (SectionConfig):
-                The section configuration.
+                The section configuration to validate against.
             item (FunctionAndClassDetails):
                 The function or class details.
 
         Returns:
             (Optional[str]):
-                Error message if section is invalid, None otherwise.
+                Error message if validation fails, None otherwise.
         """
 
-        section_name: str = section.name.lower()
-
-        if section_name == "params" and isinstance(item.node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            # Check params section exists and is properly formatted
-            if not self._check_params_section(docstring, item.node):
-                return "Missing or invalid Params section"
-
-            # If validate_param_types is enabled, validate type annotations match
-            if self.config.global_config.validate_param_types:
-                type_error: Optional[str] = self._validate_param_types(docstring, item.node)
-                if type_error:
-                    return type_error
+        if section.type == "list_name_and_type":
+            return self._validate_list_name_and_type_section(docstring, section, item)
 
-        elif section_name in ["returns", "return"]:
-            if not self._check_returns_section(docstring):
-                return "Missing or invalid Returns section"
+        if section.type == "list_name":
+            return self._validate_list_name_section(docstring, section)
 
+        # For `section.type in ("free_text", "list_type")`
+        # these sections do not need content validation beyond existence
         return None
 
-    def _validate_list_type_section(self, docstring: str, section: SectionConfig) -> Optional[str]:
+    def _validate_list_name_and_type_section(
+        self, docstring: str, section: SectionConfig, item: FunctionAndClassDetails
+    ) -> Optional[str]:
         """
         !!! note "Summary"
-            Validate list_type sections (raises, yields).
+            Validate list_name_and_type sections (params, returns).
 
         Params:
             docstring (str):
                 The docstring to validate.
             section (SectionConfig):
                 The section configuration.
+            item (FunctionAndClassDetails):
+                The function or class details.
 
         Returns:
             (Optional[str]):
@@ -708,12 +747,20 @@ class DocstringChecker:
 
         section_name: str = section.name.lower()
 
-        if section_name in ["raises", "raise"]:
-            if not self._check_raises_section(docstring):
-                return "Missing or invalid Raises section"
-        elif section_name in ["yields", "yield"]:
-            if not self._check_yields_section(docstring):
-                return "Missing or invalid Yields section"
+        if section_name == "params" and isinstance(item.node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Check params section exists and is properly formatted with detailed error reporting
+            is_valid, error_message = self._check_params_section_detailed(docstring, item.node)
+            if not is_valid:
+                return error_message
+
+            # If validate_param_types is enabled, validate type annotations match
+            if self.config.global_config.validate_param_types:
+                type_error: Optional[str] = self._validate_param_types(docstring, item.node)
+                if type_error:
+                    return type_error
+
+        # For returns/return sections, no additional validation beyond existence
+        # The _section_exists check already verified the section is present
 
         return None
 
@@ -732,8 +779,8 @@ class DocstringChecker:
             (Optional[str]):
                 Error message if section is missing, None otherwise.
         """
-        if not self._check_simple_section(docstring, section.name):
-            return f"Missing required section: {section.name}"
+        # No additional validation beyond existence
+        # The _section_exists check already verified the section is present
         return None
 
     def _perform_comprehensive_validation(self, docstring: str) -> list[str]:
@@ -879,6 +926,113 @@ class DocstringChecker:
 
         return True
 
+    def _extract_documented_params(self, docstring: str) -> list[str]:
+        """
+        !!! note "Summary"
+            Extract parameter names from the Params section of a docstring.
+
+        Params:
+            docstring (str):
+                The docstring to parse.
+
+        Returns:
+            (list[str]):
+                List of parameter names found in the Params section.
+        """
+        documented_params: list[str] = []
+        param_pattern: str = r"^\s*(\w+)\s*\([^)]+\):"
+        lines: list[str] = docstring.split("\n")
+        in_params_section: bool = False
+
+        for line in lines:
+            # Check if we've entered the Params section
+            if "Params:" in line:
+                in_params_section = True
+                continue
+
+            # Check if we've left the Params section (next section starts)
+            if in_params_section and re.match(r"^[ ]{0,4}[A-Z]\w+:", line):
+                break
+
+            # Extract parameter name
+            if in_params_section:
+                match = re.match(param_pattern, line)
+                if match:
+                    documented_params.append(match.group(1))
+
+        return documented_params
+
+    def _build_param_mismatch_error(self, missing_in_docstring: list[str], extra_in_docstring: list[str]) -> str:
+        """
+        !!! note "Summary"
+            Build detailed error message for parameter mismatches.
+
+        Params:
+            missing_in_docstring (list[str]):
+                Parameters in signature but not in docstring.
+            extra_in_docstring (list[str]):
+                Parameters in docstring but not in signature.
+
+        Returns:
+            (str):
+                Formatted error message.
+        """
+        error_parts: list[str] = []
+
+        if missing_in_docstring:
+            missing_str: str = "', '".join(missing_in_docstring)
+            error_parts.append(f"  - In signature but not in docstring: '{missing_str}'")
+
+        if extra_in_docstring:
+            extra_str: str = "', '".join(extra_in_docstring)
+            error_parts.append(f"  - In docstring but not in signature: '{extra_str}'")
+
+        return "Parameter mismatch:\n" + "\n".join(error_parts)
+
+    def _check_params_section_detailed(
+        self, docstring: str, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]
+    ) -> tuple[bool, Optional[str]]:
+        """
+        !!! note "Summary"
+            Check if the Params section exists and documents all parameters, with detailed error reporting.
+
+        Params:
+            docstring (str):
+                The docstring to check.
+            node (Union[ast.FunctionDef, ast.AsyncFunctionDef]):
+                The function node to check.
+
+        Returns:
+            (tuple[bool, Optional[str]]):
+                Tuple of (is_valid, error_message). If valid, error_message is None.
+        """
+
+        # Get function parameters (excluding 'self' and 'cls' for methods)
+        signature_params: list[str] = [arg.arg for arg in node.args.args if arg.arg not in ("self", "cls")]
+
+        if not signature_params:
+            return (True, None)  # No parameters to document
+
+        # Check if Params section exists
+        if not re.search(r"Params:", docstring):
+            return (False, "Params section not found in docstring")
+
+        # Extract documented parameters from docstring
+        documented_params: list[str] = self._extract_documented_params(docstring)
+
+        # Find parameters in signature but not in docstring
+        missing_in_docstring: list[str] = [p for p in signature_params if p not in documented_params]
+
+        # Find parameters in docstring but not in signature
+        extra_in_docstring: list[str] = [p for p in documented_params if p not in signature_params]
+
+        # Build detailed error message if there are mismatches
+        if missing_in_docstring or extra_in_docstring:
+            error_message: str = self._build_param_mismatch_error(missing_in_docstring, extra_in_docstring)
+            return (False, error_message)
+
+        return (True, None)
+
     def _extract_param_types(self, node: Union[ast.FunctionDef, ast.AsyncFunctionDef]) -> dict[str, str]:
         """
         !!! note "Summary"
@@ -943,7 +1097,8 @@ class DocstringChecker:
                 continue
 
             # Check if we've left the Params section (next section starts)
-            if in_params_section and re.match(r"^\s*[A-Z]\w+:", line):
+            # Section headers have minimal indentation (0-4 spaces), not deep indentation like param descriptions
+            if in_params_section and re.match(r"^[ ]{0,4}[A-Z]\w+:", line):
                 break
 
             # Extract parameter name and type
@@ -1053,45 +1208,22 @@ class DocstringChecker:
         mismatches: list[tuple[str, str, str]] = self._compare_param_types(signature_types, docstring_types)
 
         if mismatches:
-            mismatch_details: list[str] = [
-                f"'{name}': signature has '{sig_type}', docstring has '{doc_type}'"
-                for name, sig_type, doc_type in mismatches
-            ]
-            return f"Parameter type mismatch: {'; '.join(mismatch_details)}"
-
-        return None
-
-    def _check_returns_section(self, docstring: str) -> bool:
-        """
-        !!! note "Summary"
-            Check if the Returns section exists.
-
-        Params:
-            docstring (str):
-                The docstring to check.
-
-        Returns:
-            (bool):
-                `True` if the section exists, `False` otherwise.
-        """
-
-        return bool(re.search(r"Returns:", docstring))
-
-    def _check_raises_section(self, docstring: str) -> bool:
-        """
-        !!! note "Summary"
-            Check if the Raises section exists.
+            # Format each mismatch with parameter name on one line, signature and docstring indented below
+            # Use 2 spaces for params, 4 for sig/doc (suitable for table output)
+            # List output will add additional indentation via CLI formatting
+            mismatch_blocks: list[str] = []
+            for name, sig_type, doc_type in mismatches:
+                sig_type: str = sig_type.replace("'", '"')
+                doc_type: str = doc_type.replace("'", '"')
+                param_block: str = f"""'{name}':\n    - signature: '{sig_type}'\n    - docstring: '{doc_type}' """
+                mismatch_blocks.append(param_block)
 
-        Params:
-            docstring (str):
-                The docstring to check.
+            # Join all parameter blocks with proper indentation
+            formatted_details: str = "\n  - ".join([""] + mismatch_blocks)
 
-        Returns:
-            (bool):
-                `True` if the section exists, `False` otherwise.
-        """
+            return f"Parameter type mismatch:{formatted_details}"
 
-        return bool(re.search(r"Raises:", docstring))
+        return None
 
     def _has_both_returns_and_yields(self, docstring: str) -> bool:
         """
@@ -1237,41 +1369,6 @@ class DocstringChecker:
 
         return errors
 
-    def _check_yields_section(self, docstring: str) -> bool:
-        """
-        !!! note "Summary"
-            Check if the Yields section exists.
-
-        Params:
-            docstring (str):
-                The docstring to check.
-
-        Returns:
-            (bool):
-                `True` if the section exists, `False` otherwise.
-        """
-
-        return bool(re.search(r"Yields:", docstring))
-
-    def _check_simple_section(self, docstring: str, section_name: str) -> bool:
-        """
-        !!! note "Summary"
-            Check if a simple named section exists.
-
-        Params:
-            docstring (str):
-                The docstring to check.
-            section_name (str):
-                The name of the section to check for.
-
-        Returns:
-            (bool):
-                `True` if the section exists, `False` otherwise.
-        """
-
-        pattern: str = rf"{re.escape(section_name)}:"
-        return bool(re.search(pattern, docstring, re.IGNORECASE))
-
     def _normalize_section_name(self, section_name: str) -> str:
         """
         !!! note "Summary"