docstring-format-checker 0.5.0__tar.gz → 0.7.0__tar.gz

{docstring_format_checker-0.5.0 → docstring_format_checker-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 0.5.0
+Version: 0.7.0
 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-0.5.0 → docstring_format_checker-0.7.0}/pyproject.toml

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

{docstring_format_checker-0.5.0 → docstring_format_checker-0.7.0}/src/docstring_format_checker/__init__.py

@@ -4,7 +4,7 @@ Docstring Format Checker.
 A CLI tool to check and validate Python docstring formatting and completeness.
 """
 
-__version__ = "v0.5.0"
+__version__ = "v0.7.0"
 __author__ = "Chris Mahoney"
 __email__ = "docstring-format-checker@data-science-extensions.com"
 

{docstring_format_checker-0.5.0 → docstring_format_checker-0.7.0}/src/docstring_format_checker/cli.py

@@ -376,13 +376,36 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, outp
             console.print(_green("✓ All docstrings are valid!"))
         return 0
 
-    # Count total errors
-    total_errors: int = sum(len(errors) for errors in results.values())
+    # Count total errors (individual error messages, not error objects)
+    total_individual_errors: int = 0
+    total_functions: int = 0
+
+    for errors in results.values():
+        total_functions += len(errors)  # Count functions/items with errors
+        for error in errors:
+            # Count individual error messages within each error object
+            if "; " in error.message:
+                individual_errors = [msg.strip() for msg in error.message.split("; ") if msg.strip()]
+                total_individual_errors += len(individual_errors)
+            else:
+                total_individual_errors += 1
+
+    total_errors: int = total_individual_errors
     total_files: int = len(results)
 
     if quiet:
-        # In quiet mode, only show summary
-        console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {total_files} file(s)"))
+        # In quiet mode, only show summary with improved format
+        if total_functions == 1:
+            functions_text = f"1 function"
+        else:
+            functions_text = f"{total_functions} functions"
+
+        if total_files == 1:
+            files_text = f"1 file"
+        else:
+            files_text = f"{total_files} files"
+
+        console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {functions_text} over {files_text}"))
         return 1
 
     if output == "table":
@@ -411,22 +434,37 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, outp
         console.print(table)
 
     else:
-        # Show compact output
+        # Show compact output with grouped errors under function/class headers
         for file_path, errors in results.items():
             console.print(f"{NEW_LINE}{_cyan(file_path)}")
             for error in errors:
-                # Format error message with improved formatting
-                formatted_error_message: str = _format_error_messages(error.message)
-
+                # Print the header line with line number, item type and name
                 if error.line_number > 0:
-                    console.print(
-                        f"  [red]Line {error.line_number}[/red] - {error.item_type} '{error.item_name}': {formatted_error_message}"
-                    )
+                    console.print(f"  [red]Line {error.line_number}[/red] - {error.item_type} '{error.item_name}':")
+                else:
+                    console.print(f"  {_red('Error')} - {error.item_type} '{error.item_name}':")
+
+                # Split error message into individual errors and indent them
+                if "; " in error.message:
+                    individual_errors = [msg.strip() for msg in error.message.split("; ") if msg.strip()]
+                    for individual_error in individual_errors:
+                        console.print(f"    - {individual_error}")
                 else:
-                    console.print(f"  {_red('Error')}: {formatted_error_message}")
+                    # Single error message
+                    console.print(f"    - {error.message.strip()}")
+
+    # Summary - more descriptive message
+    if total_functions == 1:
+        functions_text = f"1 function"
+    else:
+        functions_text = f"{total_functions} functions"
+
+    if total_files == 1:
+        files_text = f"1 file"
+    else:
+        files_text = f"{total_files} files"
 
-    # Summary
-    console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {total_files} file(s)"))
+    console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {functions_text} over {files_text}"))
 
     return 1
 
@@ -439,7 +477,7 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, outp
 
 
 # This will be the default behavior when no command is specified
-def _check_docstrings(
+def check_docstrings(
     path: str,
     config: Optional[str] = None,
     exclude: Optional[list[str]] = None,
@@ -456,14 +494,19 @@ def _check_docstrings(
             The path to the file or directory to check.
         config (Optional[str]):
             The path to the configuration file.
+            Default: `None`.
         exclude (Optional[list[str]]):
             List of glob patterns to exclude from checking.
+            Default: `None`.
         quiet (bool):
             Whether to suppress output.
+            Default: `False`.
         output (str):
             Output format: 'table' or 'list'.
+            Default: `'list'`.
         check (bool):
             Whether to throw error if issues are found.
+            Default: `False`.
 
     Returns:
         (None):
@@ -626,7 +669,7 @@ def main(
         console.print(_red(f"Error: Invalid output format '{output}'. Use 'table' or 'list'."))
         raise Exit(1)
 
-    _check_docstrings(
+    check_docstrings(
         path=path,
         config=config,
         exclude=exclude,

{docstring_format_checker-0.5.0 → docstring_format_checker-0.7.0}/src/docstring_format_checker/core.py

@@ -924,6 +924,7 @@ class DocstringChecker:
         # Check each line in the docstring
         lines: list[str] = docstring.split("\n")
         current_section = None
+        type_line_indent = None  # Track indentation of type definition lines
 
         for i, line in enumerate(lines):
             stripped_line: str = line.strip()
@@ -938,6 +939,7 @@ class DocstringChecker:
                 current_section: Optional[SectionConfig] = next(
                     (s for s in parentheses_sections if s.name.lower() == section_name), None
                 )
+                type_line_indent = None  # Reset for new section
                 continue
 
             # Non-admonition sections - only match actual section headers, not indented content
@@ -955,6 +957,7 @@ class DocstringChecker:
                         current_section = next(
                             (s for s in parentheses_sections if s.name.lower() == section_name), None
                         )
+                        type_line_indent = None  # Reset for new section
                         continue
                     # If it doesn't match a known section, fall through to content processing
 
@@ -962,19 +965,66 @@ class DocstringChecker:
             if current_section and stripped_line and not stripped_line.startswith(("!", "?", "#")):
                 # Look for parameter/type definitions
                 if ":" in stripped_line:
+                    # Calculate current line indentation
+                    current_indent = len(line) - len(line.lstrip())
+
+                    # Skip description lines that start with common description words
+                    description_prefixes = [
+                        "default:",
+                        "note:",
+                        "example:",
+                        "see:",
+                        "warning:",
+                        "info:",
+                        "tip:",
+                        "returns:",
+                    ]
+                    is_description_line = any(
+                        stripped_line.lower().startswith(prefix) for prefix in description_prefixes
+                    )
+
+                    # Skip lines that are clearly descriptions (containing "Default:", etc.)
+                    if (
+                        is_description_line
+                        or "Default:" in stripped_line
+                        or "Output format:" in stripped_line
+                        or "Show examples:" in stripped_line
+                    ):
+                        continue
+
+                    # For list_type sections, we need special handling
+                    if current_section.type == "list_type":
+                        # Check if this line has parentheses at the beginning
+                        if re.search(r"^\s*\([^)]+\):", stripped_line):
+                            # This is a valid type definition line, remember its indentation
+                            type_line_indent = current_indent
+                            continue
+                        else:
+                            # If no type definition has been found yet, allow lines with colons as possible descriptions
+                            if type_line_indent is None:
+                                continue
+                            # Check if this is a description line (more indented than type line)
+                            if current_indent > type_line_indent:
+                                # This is a description line, skip validation
+                                continue
+                            else:
+                                # This should be a type definition but doesn't have proper format
+                                errors.append(
+                                    f"Section '{current_section.name}' (type: '{current_section.type}') requires "
+                                    f"parenthesized types, see: '{stripped_line}'"
+                                )
                     # For list_name_and_type sections, check format like "name (type):" or "(type):"
-                    if current_section.type == "list_name_and_type":
+                    elif current_section.type == "list_name_and_type":
                         # Pattern: name (type): or (type):
-                        if not re.search(r"\([^)]+\):", stripped_line):
-                            errors.append(
-                                f"Section '{current_section.name}' (type: '{current_section.type}') requires "
-                                f"parenthesized types, see: '{stripped_line}'"
-                            )
+                        # But skip if it doesn't look like a parameter definition (e.g., has multiple words before the colon)
+                        colon_part = stripped_line.split(":")[0].strip()
+                        # Skip if it contains phrases that indicate it's a description, not a parameter
+                        if any(
+                            word in colon_part.lower() for word in ["default", "output", "format", "show", "example"]
+                        ):
+                            continue
 
-                    # For list_type sections, check format like "(Type):"
-                    elif current_section.type == "list_type":
-                        # Pattern: (Type):
-                        if not re.search(r"^\s*\([^)]+\):", stripped_line):
+                        if not re.search(r"\([^)]+\):", stripped_line):
                             errors.append(
                                 f"Section '{current_section.name}' (type: '{current_section.type}') requires "
                                 f"parenthesized types, see: '{stripped_line}'"