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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 1.3.0
+Version: 1.4.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.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "1.3.0"
+version = "1.4.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,25 @@ 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.bump_version.replacements]
 files = [
     { file = "src/docstring_format_checker/__init__.py", pattern = "__version__ = \"{VERSION}\"" },
@@ -157,16 +178,16 @@ files = [
 [tool.dfc]
 allow_undefined_sections = false
 require_docstrings = true
-check_private = true
+check_private = false
 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.4.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,106 @@ 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]:
+    """Count total errors, functions, and files from results."""
     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()]
                 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 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"
+    return {"total_errors": total_individual_errors, "total_functions": total_functions, "total_files": len(results)}
 
-        console.print(_red(f"{NEW_LINE}Found {total_errors} error(s) in {functions_text} over {files_text}"))
-        return 1
 
-    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)
+def _display_quiet_summary(error_stats: dict[str, int]) -> None:
+    """Display summary in quiet mode."""
+    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"
+
+    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."""
+    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 _display_list_output(results: dict[str, list[DocstringError]]) -> None:
+    """Display results in list format."""
+    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}':")
 
-    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"
+            # 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()}")
 
-    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}"))
+def _display_final_summary(error_stats: dict[str, int]) -> None:
+    """Display the final summary line."""
+    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"
 
-    return 1
+    console.print(_red(f"{NEW_LINE}Found {error_stats['total_errors']} error(s) in {functions_text} over {files_text}"))
 
 
 # ---------------------------------------------------------------------------- #
@@ -525,69 +537,92 @@ def check_docstrings(
         (None):
             Nothing is returned.
     """
+    # Validate and process input paths
+    target_paths = _validate_and_process_paths(paths)
+
+    # Load and validate configuration
+    config_obj = _load_and_validate_config(config, target_paths)
 
-    # Validate all target paths
+    # Initialize checker and process all paths
+    checker = DocstringChecker(config_obj)
+    all_results = _process_all_paths(checker, target_paths, exclude)
+
+    # Display results and handle exit
+    exit_code = _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."""
     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:
+    """Load and validate configuration from file or auto-discovery."""
     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:
+    """Load configuration from explicitly specified path."""
+    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:
+    """Load configuration from auto-discovery or defaults."""
+    first_path: Path = target_paths[0]
+    search_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]]:
+    """Process all target paths and collect docstring errors."""
     all_results: dict[str, list[DocstringError]] = {}
 
     try:
         for target_path in target_paths:
             if target_path.is_file():
-                errors: list[DocstringError] = checker.check_file(target_path)
+                errors = checker.check_file(target_path)
                 if errors:
                     all_results[str(target_path)] = errors
             else:
-                directory_results: dict[str, list[DocstringError]] = checker.check_directory(
-                    target_path, exclude_patterns=exclude
-                )
+                directory_results = 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}"))
-        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
 
 
 # ---------------------------------------------------------------------------- #

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

@@ -331,78 +331,111 @@ def load_config(config_path: Optional[Union[str, Path]] = None) -> Config:
         (Config):
             Configuration object containing global settings and section definitions.
     """
+    # Resolve config file path
+    resolved_path = _resolve_config_path(config_path)
+    if resolved_path is None:
+        return DEFAULT_CONFIG
+
+    # Parse TOML configuration
+    config_data = _parse_toml_file(resolved_path)
+
+    # Extract tool configuration
+    tool_config = _extract_tool_config(config_data)
+    if tool_config is None:
+        return DEFAULT_CONFIG
+
+    # Parse configuration components
+    global_config = _parse_global_config(tool_config)
+    sections_config = _parse_sections_config(tool_config)
+
+    return Config(global_config=global_config, sections=sections_config)
+
 
+def _resolve_config_path(config_path: Optional[Union[str, Path]]) -> Optional[Path]:
+    """Resolve configuration file path."""
     if config_path is None:
         # Look for pyproject.toml in current directory
         pyproject_path: Path = Path.cwd().joinpath("pyproject.toml")
         if pyproject_path.exists():
-            config_path = pyproject_path
+            return pyproject_path
         else:
-            return DEFAULT_CONFIG
+            return None
 
     # Convert to Path object and check existence
     config_path = Path(config_path)
     if not config_path.exists():
         raise FileNotFoundError(f"Configuration file not found: {config_path}")
 
+    return config_path
+
+
+def _parse_toml_file(config_path: Path) -> dict[str, Any]:
+    """Parse TOML configuration file."""
     try:
         with open(config_path, "rb") as f:
-            config_data: dict[str, Any] = tomllib.load(f)
+            return tomllib.load(f)
     except Exception as e:
         raise InvalidConfigError(f"Failed to parse TOML file {config_path}: {e}") from e
 
-    # Try to find configuration under [tool.dfc] or [tool.docstring-format-checker]
-    tool_config = None
-    if "tool" in config_data:
-        if "dfc" in config_data["tool"]:
-            tool_config = config_data["tool"]["dfc"]
-        elif "docstring-format-checker" in config_data["tool"]:
-            tool_config = config_data["tool"]["docstring-format-checker"]
 
-    if tool_config is None:
-        return DEFAULT_CONFIG
+def _extract_tool_config(config_data: dict[str, Any]) -> Optional[dict[str, Any]]:
+    """Extract tool configuration from TOML data."""
+    if "tool" not in config_data:
+        return None
+
+    tool_section = config_data["tool"]
+    if "dfc" in tool_section:
+        return tool_section["dfc"]
+    elif "docstring-format-checker" in tool_section:
+        return tool_section["docstring-format-checker"]
 
-    # Parse global configuration flags
-    global_config = GlobalConfig(
+    return None
+
+
+def _parse_global_config(tool_config: dict[str, Any]) -> GlobalConfig:
+    """Parse global configuration flags."""
+    return GlobalConfig(
         allow_undefined_sections=tool_config.get("allow_undefined_sections", False),
         require_docstrings=tool_config.get("require_docstrings", True),
         check_private=tool_config.get("check_private", False),
     )
 
-    # Parse sections configuration
+
+def _parse_sections_config(tool_config: dict[str, Any]) -> list[SectionConfig]:
+    """Parse sections configuration."""
+    if "sections" not in tool_config:
+        return DEFAULT_SECTIONS
+
     sections_config: list[SectionConfig] = []
-    if "sections" in tool_config:
-        sections_data = tool_config["sections"]
-        for section_data in sections_data:
-            try:
-                # Get admonition value with proper default handling
-                admonition_value: Union[str, bool] = section_data.get("admonition")
-                if admonition_value is None:
-                    admonition_value = False  # Use SectionConfig default
-
-                section = SectionConfig(
-                    order=section_data.get("order", 0),
-                    name=section_data.get("name", ""),
-                    type=section_data.get("type", ""),
-                    admonition=admonition_value,
-                    prefix=section_data.get("prefix", ""),
-                    required=section_data.get("required", False),
-                )
-                sections_config.append(section)
-            except (KeyError, TypeError, ValueError, InvalidTypeValuesError) as e:
-                raise InvalidConfigError(f"Invalid section configuration: {section_data}. Error: {e}") from e
-
-    # Use default sections if none provided, otherwise validate and sort
-    if not sections_config:
-        sections_config = DEFAULT_SECTIONS
-    else:
-        # Validate no duplicate order values
-        _validate_config_order(config_sections=sections_config)
+    sections_data = tool_config["sections"]
+
+    for section_data in sections_data:
+        try:
+            # Get admonition value with proper default handling
+            admonition_value: Union[str, bool] = section_data.get("admonition")
+            if admonition_value is None:
+                admonition_value = False  # Use SectionConfig default
+
+            section = SectionConfig(
+                order=section_data.get("order", 0),
+                name=section_data.get("name", ""),
+                type=section_data.get("type", ""),
+                admonition=admonition_value,
+                prefix=section_data.get("prefix", ""),
+                required=section_data.get("required", False),
+            )
+            sections_config.append(section)
+        except (KeyError, TypeError, ValueError, InvalidTypeValuesError) as e:
+            raise InvalidConfigError(f"Invalid section configuration: {section_data}. Error: {e}") from e
 
-        # Sort by order
+    # Validate and sort sections
+    if sections_config:
+        _validate_config_order(config_sections=sections_config)
         sections_config.sort(key=lambda x: x.order)
+    else:
+        sections_config = DEFAULT_SECTIONS
 
-    return Config(global_config=global_config, sections=sections_config)
+    return sections_config
 
 
 def find_config_file(start_path: Optional[Path] = None) -> Optional[Path]: