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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 1.4.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>

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

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "1.4.0"
+version = "1.5.0"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"
@@ -168,6 +168,13 @@ disable = [
     "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}\"" },
@@ -178,7 +185,7 @@ files = [
 [tool.dfc]
 allow_undefined_sections = false
 require_docstrings = true
-check_private = false
+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="???+" },

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

@@ -414,7 +414,18 @@ def _display_results(
 
 
 def _count_errors_and_files(results: dict[str, list[DocstringError]]) -> dict[str, int]:
-    """Count total errors, functions, and files from results."""
+    """
+    !!! 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
 
@@ -422,7 +433,7 @@ def _count_errors_and_files(results: dict[str, list[DocstringError]]) -> dict[st
         total_functions += len(errors)
         for error in errors:
             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
@@ -431,17 +442,31 @@ def _count_errors_and_files(results: dict[str, list[DocstringError]]) -> dict[st
 
 
 def _display_quiet_summary(error_stats: dict[str, int]) -> None:
-    """Display summary in quiet mode."""
+    """
+    !!! note "Summary"
+        Display summary in quiet mode.
+
+    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 = "1 file" if error_stats["total_files"] == 1 else f"{error_stats['total_files']} files"
+    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}"))
 
 
 def _display_table_output(results: dict[str, list[DocstringError]]) -> None:
-    """Display results in table format."""
+    """
+    !!! 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")
@@ -464,32 +489,94 @@ def _display_table_output(results: dict[str, list[DocstringError]]) -> None:
     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:
+        return f"  {_red('Error')} - {error.item_type} '{error.item_name}':"
+
+
+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:
+        return [message.strip()]
+
+
+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:
-    """Display results in list format."""
+    """
+    !!! 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:
-            # Print header 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}':")
-
-            # Format and print error messages
-            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"    - {error.message.strip()}")
+            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:
-    """Display the final summary line."""
-    functions_text = (
+    """
+    !!! 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 = "1 file" if error_stats["total_files"] == 1 else f"{error_stats['total_files']} files"
+    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}"))
 
@@ -538,23 +625,38 @@ def check_docstrings(
             Nothing is returned.
     """
     # Validate and process input paths
-    target_paths = _validate_and_process_paths(paths)
+    target_paths: list[Path] = _validate_and_process_paths(paths)
 
     # Load and validate configuration
-    config_obj = _load_and_validate_config(config, target_paths)
+    config_obj: Config = _load_and_validate_config(config, target_paths)
 
     # Initialize checker and process all paths
     checker = DocstringChecker(config_obj)
-    all_results = _process_all_paths(checker, target_paths, exclude)
+    all_results: dict[str, list[DocstringError]] = _process_all_paths(checker, target_paths, exclude)
 
     # Display results and handle exit
-    exit_code = _display_results(all_results, quiet, output, check)
+    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]:
-    """Validate input paths and return valid paths."""
+    """
+    !!! 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()]
@@ -571,7 +673,24 @@ def _validate_and_process_paths(paths: list[str]) -> list[Path]:
 
 
 def _load_and_validate_config(config: Optional[str], target_paths: list[Path]) -> Config:
-    """Load and validate configuration from file or auto-discovery."""
+    """
+    !!! 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:
             return _load_explicit_config(config)
@@ -583,7 +702,22 @@ def _load_and_validate_config(config: Optional[str], target_paths: list[Path]) -
 
 
 def _load_explicit_config(config: str) -> Config:
-    """Load configuration from explicitly specified path."""
+    """
+    !!! 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}"))
@@ -592,9 +726,20 @@ def _load_explicit_config(config: str) -> Config:
 
 
 def _load_auto_discovered_config(target_paths: list[Path]) -> Config:
-    """Load configuration from auto-discovery or defaults."""
+    """
+    !!! 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 = first_path if first_path.is_dir() else first_path.parent
+    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:
@@ -606,17 +751,38 @@ def _load_auto_discovered_config(target_paths: list[Path]) -> Config:
 def _process_all_paths(
     checker: DocstringChecker, target_paths: list[Path], exclude: Optional[list[str]]
 ) -> dict[str, list[DocstringError]]:
-    """Process all target paths and collect docstring errors."""
+    """
+    !!! 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:
         for target_path in target_paths:
             if target_path.is_file():
-                errors = checker.check_file(target_path)
+                errors: list[DocstringError] = checker.check_file(target_path)
                 if errors:
                     all_results[str(target_path)] = errors
             else:
-                directory_results = checker.check_directory(target_path, exclude_patterns=exclude)
+                directory_results: dict[str, list[DocstringError]] = checker.check_directory(
+                    target_path, exclude_patterns=exclude
+                )
                 all_results.update(directory_results)
     except Exception as e:
         console.print(_red(f"Error during checking: {e}"))

{docstring_format_checker-1.4.0 → docstring_format_checker-1.5.0}/src/docstring_format_checker/config.py

@@ -352,7 +352,22 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> Config:
 
 
 def _resolve_config_path(config_path: Optional[Union[str, Path]]) -> Optional[Path]:
-    """Resolve configuration file path."""
+    """
+    !!! note "Summary"
+        Resolve configuration file path.
+
+    Params:
+        config_path (Optional[Union[str, Path]]):
+            Optional path to configuration file.
+
+    Raises:
+        (FileNotFoundError):
+            If specified config file does not exist.
+
+    Returns:
+        (Optional[Path]):
+            Resolved Path object or None if no config found.
+    """
     if config_path is None:
         # Look for pyproject.toml in current directory
         pyproject_path: Path = Path.cwd().joinpath("pyproject.toml")
@@ -370,7 +385,22 @@ def _resolve_config_path(config_path: Optional[Union[str, Path]]) -> Optional[Pa
 
 
 def _parse_toml_file(config_path: Path) -> dict[str, Any]:
-    """Parse TOML configuration file."""
+    """
+    !!! note "Summary"
+        Parse TOML configuration file.
+
+    Params:
+        config_path (Path):
+            Path to TOML file to parse.
+
+    Raises:
+        (InvalidConfigError):
+            If TOML parsing fails.
+
+    Returns:
+        (dict[str, Any]):
+            Parsed TOML data as dictionary.
+    """
     try:
         with open(config_path, "rb") as f:
             return tomllib.load(f)
@@ -379,7 +409,18 @@ def _parse_toml_file(config_path: Path) -> dict[str, Any]:
 
 
 def _extract_tool_config(config_data: dict[str, Any]) -> Optional[dict[str, Any]]:
-    """Extract tool configuration from TOML data."""
+    """
+    !!! note "Summary"
+        Extract tool configuration from TOML data.
+
+    Params:
+        config_data (dict[str, Any]):
+            Parsed TOML data dictionary.
+
+    Returns:
+        (Optional[dict[str, Any]]):
+            Tool configuration dictionary or None if not found.
+    """
     if "tool" not in config_data:
         return None
 
@@ -393,7 +434,18 @@ def _extract_tool_config(config_data: dict[str, Any]) -> Optional[dict[str, Any]
 
 
 def _parse_global_config(tool_config: dict[str, Any]) -> GlobalConfig:
-    """Parse global configuration flags."""
+    """
+    !!! note "Summary"
+        Parse global configuration flags.
+
+    Params:
+        tool_config (dict[str, Any]):
+            Tool configuration dictionary.
+
+    Returns:
+        (GlobalConfig):
+            Parsed global configuration object.
+    """
     return GlobalConfig(
         allow_undefined_sections=tool_config.get("allow_undefined_sections", False),
         require_docstrings=tool_config.get("require_docstrings", True),
@@ -402,7 +454,18 @@ def _parse_global_config(tool_config: dict[str, Any]) -> GlobalConfig:
 
 
 def _parse_sections_config(tool_config: dict[str, Any]) -> list[SectionConfig]:
-    """Parse sections configuration."""
+    """
+    !!! note "Summary"
+        Parse sections configuration.
+
+    Params:
+        tool_config (dict[str, Any]):
+            Tool configuration dictionary.
+
+    Returns:
+        (list[SectionConfig]):
+            List of section configuration objects or defaults.
+    """
     if "sections" not in tool_config:
         return DEFAULT_SECTIONS