docstring-format-checker 1.3.0__tar.gz → 1.5.0__tar.gz

{docstring_format_checker-1.3.0 → docstring_format_checker-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 1.3.0
+Version: 1.5.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>
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
 Requires-Dist: typer>=0.9.0

{docstring_format_checker-1.3.0 → docstring_format_checker-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "1.3.0"
+version = "1.5.0"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"
@@ -23,6 +23,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Intended Audience :: Developers",
     "Environment :: Console",
 ]
@@ -83,6 +84,7 @@ test = [
     "pytest-sugar==1.*",
     "pytest-xdist==3.*",
     "requests==2.*",
+    "complexipy==4.*",
 ]
 
 [tool.black]
@@ -147,6 +149,32 @@ lines_after_imports = 2
 [tool.codespell]
 ignore-words-list = "demog"
 
+[tool.pylint.main]
+disable = [
+    "C0103",  # invalid-name
+    "C0301",  # line-too-long
+    "C0302",  # too-many-lines
+    "R0913",  # too-many-arguments
+    "R0914",  # too-many-locals
+    "R0915",  # too-many-statements
+    "R0917",  # too-many-positional-arguments
+    "R1705",  # no-else-return
+    "R1724",  # no-else-continue
+    "W0107",  # unnecessary-pass
+    "W0212",  # protected-access
+    "W0612",  # unused-variable
+    "W0613",  # unused-argument
+    "W0622",  # redefined-builtin
+    "W0718",  # broad-exception-caught
+]
+
+[tool.complexipy]
+paths = "src/docstring_format_checker"
+max-complexity-allowed = 15
+quiet = false
+ignore-complexity = false
+sort = "asc"
+
 [tool.bump_version.replacements]
 files = [
     { file = "src/docstring_format_checker/__init__.py", pattern = "__version__ = \"{VERSION}\"" },
@@ -159,14 +187,14 @@ allow_undefined_sections = false
 require_docstrings = true
 check_private = true
 sections = [
-    { order = 1, name = "summary",  type = "free_text",          required = true, admonition = "note", prefix = "!!!" },
-    { order = 2, name = "details",  type = "free_text",          required = false, admonition = "abstract", prefix = "???+" },
-    { order = 3, name = "params",   type = "list_name_and_type", required = false },
-    { order = 4, name = "raises",   type = "list_type",          required = false },
-    { order = 5, name = "returns",  type = "list_name_and_type", required = false },
-    { order = 6, name = "yields",   type = "list_type",          required = false },
-    { order = 7, name = "examples", type = "free_text",          required = false, admonition = "example", prefix = "???+" },
-    { order = 8, name = "notes",    type = "free_text",          required = false, admonition = "note", prefix = "???" },
+    { order=1, name="summary",  type="free_text",          required=true,  admonition="note",     prefix="!!!" },
+    { order=2, name="details",  type="free_text",          required=false, admonition="abstract", prefix="???+" },
+    { order=3, name="params",   type="list_name_and_type", required=false, admonition=false },
+    { order=4, name="raises",   type="list_type",          required=false, admonition=false },
+    { order=5, name="returns",  type="list_name_and_type", required=false, admonition=false },
+    { order=6, name="yields",   type="list_type",          required=false, admonition=false },
+    { order=7, name="examples", type="free_text",          required=false, admonition="example",  prefix="???+" },
+    { order=8, name="notes",    type="free_text",          required=false, admonition="note",     prefix="???" },
 ]
 
 [build-system]

{docstring_format_checker-1.3.0 → docstring_format_checker-1.5.0}/src/docstring_format_checker/cli.py

@@ -360,12 +360,18 @@ def _format_error_messages(error_message: str) -> str:
         errors: list[str] = error_message.split("; ")
         formatted_errors: list[str] = [f"- {error.strip()}" for error in errors if error.strip()]
         return ";\n".join(formatted_errors) + "."
+
+    # Single error message
     else:
-        # Single error message
         return f"- {error_message.strip()}."
 
 
-def _display_results(results: dict[str, list[DocstringError]], quiet: bool, output: str, check: bool) -> int:
+def _display_results(
+    results: dict[str, list[DocstringError]],
+    quiet: bool,
+    output: str,
+    check: bool,
+) -> int:
     """
     !!! note "Summary"
         Display the results of docstring checking.
@@ -386,100 +392,193 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, outp
     """
     if not results:
         if not quiet:
-            console.print(_green("✓ All docstrings are valid!"))
+            console.print(_green("✅ All docstrings are valid!"))
         return 0
 
-    # Count total errors (individual error messages, not error objects)
+    # Count errors and generate summary statistics
+    error_stats = _count_errors_and_files(results)
+
+    if quiet:
+        _display_quiet_summary(error_stats)
+        return 1
+
+    # Display detailed results based on output format
+    if output == "table":
+        _display_table_output(results)
+    else:
+        _display_list_output(results)
+
+    # Display final summary
+    _display_final_summary(error_stats)
+    return 1
+
+
+def _count_errors_and_files(results: dict[str, list[DocstringError]]) -> dict[str, int]:
+    """
+    !!! note "Summary"
+        Count total errors, functions, and files from results.
+
+    Params:
+        results (dict[str, list[DocstringError]]):
+            Dictionary mapping file paths to lists of errors.
+
+    Returns:
+        (dict[str, int]):
+            Dictionary containing total_errors, total_functions, and total_files.
+    """
     total_individual_errors: int = 0
     total_functions: int = 0
 
     for errors in results.values():
-        total_functions += len(errors)  # Count functions/items with errors
+        total_functions += len(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()]
+                individual_errors: list[str] = [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)
+    return {"total_errors": total_individual_errors, "total_functions": total_functions, "total_files": len(results)}
 
-    if quiet:
-        # 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"
+def _display_quiet_summary(error_stats: dict[str, int]) -> None:
+    """
+    !!! note "Summary"
+        Display summary in quiet mode.
 
-        console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {functions_text} over {files_text}"))
-        return 1
+    Params:
+        error_stats (dict[str, int]):
+            Dictionary containing total_errors, total_functions, and total_files.
+    """
+    functions_text = (
+        "1 function" if error_stats["total_functions"] == 1 else f"{error_stats['total_functions']} functions"
+    )
+    files_text: str = "1 file" if error_stats["total_files"] == 1 else f"{error_stats['total_files']} files"
 
-    if output == "table":
-        # Show detailed table
-        table = Table(show_header=True, header_style="bold magenta")
-        table.add_column("File", style="cyan", no_wrap=False)
-        table.add_column("Line", justify="right", style="white")
-        table.add_column("Item", style="yellow")
-        table.add_column("Type", style="blue")
-        table.add_column("Error", style="red")
-
-        for file_path, errors in results.items():
-            for i, error in enumerate(errors):
-                file_display: str = file_path if i == 0 else ""
-
-                # Format error message with improved formatting
-                formatted_error_message: str = _format_error_messages(error.message)
-
-                table.add_row(
-                    file_display,
-                    str(error.line_number) if error.line_number > 0 else "",
-                    error.item_name,
-                    error.item_type,
-                    formatted_error_message,
-                )
-        console.print(table)
+    console.print(_red(f"{NEW_LINE}Found {error_stats['total_errors']} error(s) in {functions_text} over {files_text}"))
 
+
+def _display_table_output(results: dict[str, list[DocstringError]]) -> None:
+    """
+    !!! note "Summary"
+        Display results in table format.
+
+    Params:
+        results (dict[str, list[DocstringError]]):
+            Dictionary mapping file paths to lists of errors.
+    """
+    table = Table(show_header=True, header_style="bold magenta")
+    table.add_column("File", style="cyan", no_wrap=False)
+    table.add_column("Line", justify="right", style="white")
+    table.add_column("Item", style="yellow")
+    table.add_column("Type", style="blue")
+    table.add_column("Error", style="red")
+
+    for file_path, errors in results.items():
+        for i, error in enumerate(errors):
+            file_display = file_path if i == 0 else ""
+            formatted_error_message = _format_error_messages(error.message)
+
+            table.add_row(
+                file_display,
+                str(error.line_number) if error.line_number > 0 else "",
+                error.item_name,
+                error.item_type,
+                formatted_error_message,
+            )
+    console.print(table)
+
+
+def _create_error_header(error: DocstringError) -> str:
+    """
+    !!! note "Summary"
+        Create formatted header for a single error.
+
+    Params:
+        error (DocstringError):
+            The error to create a header for.
+
+    Returns:
+        (str):
+            Formatted header string with line number, item type, and name.
+    """
+    if error.line_number > 0:
+        return f"  [red]Line {error.line_number}[/red] - {error.item_type} '{error.item_name}':"
     else:
-        # 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:
-                # 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}':")
-                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:
-                    # 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"
+        return f"  {_red('Error')} - {error.item_type} '{error.item_name}':"
+
 
-    if total_files == 1:
-        files_text = f"1 file"
+def _split_error_messages(message: str) -> list[str]:
+    """
+    !!! note "Summary"
+        Split compound error message into individual messages.
+
+    Params:
+        message (str):
+            The error message to split.
+
+    Returns:
+        (list[str]):
+            List of individual error messages.
+    """
+    if "; " in message:
+        return [msg.strip() for msg in message.split("; ") if msg.strip()]
     else:
-        files_text = f"{total_files} files"
+        return [message.strip()]
 
-    console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {functions_text} over {files_text}"))
 
-    return 1
+def _format_error_output(error: DocstringError) -> list[str]:
+    """
+    !!! note "Summary"
+        Format single error for display output.
+
+    Params:
+        error (DocstringError):
+            The error to format.
+
+    Returns:
+        (list[str]):
+            List of formatted lines to print.
+    """
+    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}")
+    return lines
+
+
+def _display_list_output(results: dict[str, list[DocstringError]]) -> None:
+    """
+    !!! note "Summary"
+        Display results in list format.
+
+    Params:
+        results (dict[str, list[DocstringError]]):
+            Dictionary mapping file paths to lists of errors.
+    """
+    for file_path, errors in results.items():
+        console.print(f"{NEW_LINE}{_cyan(file_path)}")
+        for error in errors:
+            output_lines: list[str] = _format_error_output(error)
+            for line in output_lines:
+                console.print(line)
+
+
+def _display_final_summary(error_stats: dict[str, int]) -> None:
+    """
+    !!! note "Summary"
+        Display the final summary line.
+
+    Params:
+        error_stats (dict[str, int]):
+            Dictionary containing total_errors, total_functions, and total_files.
+    """
+    functions_text: str = (
+        "1 function" if error_stats["total_functions"] == 1 else f"{error_stats['total_functions']} functions"
+    )
+    files_text: str = "1 file" if error_stats["total_files"] == 1 else f"{error_stats['total_files']} files"
+
+    console.print(_red(f"{NEW_LINE}Found {error_stats['total_errors']} error(s) in {functions_text} over {files_text}"))
 
 
 # ---------------------------------------------------------------------------- #
@@ -525,45 +624,153 @@ def check_docstrings(
         (None):
             Nothing is returned.
     """
+    # Validate and process input paths
+    target_paths: list[Path] = _validate_and_process_paths(paths)
+
+    # Load and validate configuration
+    config_obj: Config = _load_and_validate_config(config, target_paths)
 
-    # Validate all target paths
+    # Initialize checker and process all paths
+    checker = DocstringChecker(config_obj)
+    all_results: dict[str, list[DocstringError]] = _process_all_paths(checker, target_paths, exclude)
+
+    # Display results and handle exit
+    exit_code: int = _display_results(all_results, quiet, output, check)
+    if exit_code != 0:
+        raise Exit(exit_code)
+
+
+def _validate_and_process_paths(paths: list[str]) -> list[Path]:
+    """
+    !!! note "Summary"
+        Validate input paths and return valid paths.
+
+    Params:
+        paths (list[str]):
+            List of path strings to validate.
+
+    Raises:
+        (Exit):
+            If any paths do not exist.
+
+    Returns:
+        (list[Path]):
+            List of valid Path objects.
+    """
     path_objs: list[Path] = [Path(path) for path in paths]
     target_paths: list[Path] = [p for p in path_objs if p.exists()]
     invalid_paths: list[Path] = [p for p in path_objs if not p.exists()]
 
-    if len(invalid_paths) > 0:
+    if invalid_paths:
         console.print(
-            _red(f"[bold]Error: Paths do not exist:[/bold]"),
+            _red("[bold]Error: Paths do not exist:[/bold]"),
             NEW_LINE,
             NEW_LINE.join([f"- '{invalid_path}'" for invalid_path in invalid_paths]),
         )
         raise Exit(1)
 
-    # Load configuration (use first path for config discovery if no config specified)
+    return target_paths
+
+
+def _load_and_validate_config(config: Optional[str], target_paths: list[Path]) -> Config:
+    """
+    !!! note "Summary"
+        Load and validate configuration from file or auto-discovery.
+
+    Params:
+        config (Optional[str]):
+            Optional path to configuration file.
+        target_paths (list[Path]):
+            List of target paths for auto-discovery.
+
+    Raises:
+        (Exit):
+            If configuration loading fails.
+
+    Returns:
+        (Config):
+            Loaded configuration object.
+    """
     try:
         if config:
-            config_path = Path(config)
-            if not config_path.exists():
-                console.print(_red(f"Error: Configuration file does not exist: {config}"))
-                raise Exit(1)
-            config_obj = load_config(config_path)
+            return _load_explicit_config(config)
         else:
-            # Try to find config file automatically using the first path
-            first_path: Path = target_paths[0]
-            found_config: Optional[Path] = find_config_file(first_path if first_path.is_dir() else first_path.parent)
-            if found_config:
-                config_obj: Config = load_config(found_config)
-            else:
-                config_obj: Config = load_config()
-
+            return _load_auto_discovered_config(target_paths)
     except Exception as e:
         console.print(_red(f"Error loading configuration: {e}"))
+        raise Exit(1) from e
+
+
+def _load_explicit_config(config: str) -> Config:
+    """
+    !!! note "Summary"
+        Load configuration from explicitly specified path.
+
+    Params:
+        config (str):
+            Path to configuration file.
+
+    Raises:
+        (Exit):
+            If configuration file does not exist.
+
+    Returns:
+        (Config):
+            Loaded configuration object.
+    """
+    config_path = Path(config)
+    if not config_path.exists():
+        console.print(_red(f"Error: Configuration file does not exist: {config}"))
         raise Exit(1)
+    return load_config(config_path)
 
-    # Initialize checker
-    checker = DocstringChecker(config_obj)
 
-    # Check all paths and collect results
+def _load_auto_discovered_config(target_paths: list[Path]) -> Config:
+    """
+    !!! note "Summary"
+        Load configuration from auto-discovery or defaults.
+
+    Params:
+        target_paths (list[Path]):
+            List of target paths to search for configuration.
+
+    Returns:
+        (Config):
+            Loaded configuration object from found config or defaults.
+    """
+    first_path: Path = target_paths[0]
+    search_path: Path = first_path if first_path.is_dir() else first_path.parent
+    found_config: Optional[Path] = find_config_file(search_path)
+
+    if found_config:
+        return load_config(found_config)
+    else:
+        return load_config()
+
+
+def _process_all_paths(
+    checker: DocstringChecker, target_paths: list[Path], exclude: Optional[list[str]]
+) -> dict[str, list[DocstringError]]:
+    """
+    !!! note "Summary"
+        Process all target paths and collect docstring errors.
+
+    Params:
+        checker (DocstringChecker):
+            The checker instance to use.
+        target_paths (list[Path]):
+            List of paths to check (files or directories).
+        exclude (Optional[list[str]]):
+            Optional list of exclusion patterns.
+
+    Raises:
+        (Exit):
+            If an error occurs during checking.
+
+    Returns:
+        (dict[str, list[DocstringError]]):
+            Dictionary mapping file paths to lists of errors.
+    """
     all_results: dict[str, list[DocstringError]] = {}
 
     try:
@@ -577,17 +784,11 @@ def check_docstrings(
                     target_path, exclude_patterns=exclude
                 )
                 all_results.update(directory_results)
-
     except Exception as e:
         console.print(_red(f"Error during checking: {e}"))
-        raise Exit(1)
+        raise Exit(1) from e
 
-    # Display results
-    exit_code: int = _display_results(all_results, quiet, output, check)
-
-    # Always exit with error code if issues are found, regardless of check flag
-    if exit_code != 0:
-        raise Exit(exit_code)
+    return all_results
 
 
 # ---------------------------------------------------------------------------- #