docstring-format-checker 1.0.1__tar.gz → 1.2.0__tar.gz

{docstring_format_checker-1.0.1 → docstring_format_checker-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docstring-format-checker
-Version: 1.0.1
+Version: 1.2.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>
@@ -23,6 +23,7 @@ Requires-Dist: typer>=0.9.0
 Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
 Requires-Dist: rich>=13.0.0
 Requires-Dist: toolbox-python==1.*
+Requires-Dist: pyfiglet==1.*
 Maintainer: Chris Mahoney
 Maintainer-email: Chris Mahoney <docstring-format-checker@data-science-extensions.com>
 Requires-Python: >=3.9

{docstring_format_checker-1.0.1 → docstring_format_checker-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docstring-format-checker"
-version = "1.0.1"
+version = "1.2.0"
 description = "A CLI tool to check and validate Python docstring formatting and completeness"
 readme = "README.md"
 license = "MIT"
@@ -32,6 +32,7 @@ dependencies = [
     "tomli>=2.0.0;python_version<'3.11'",
     "rich>=13.0.0",
     "toolbox-python==1.*",
+    "pyfiglet==1.*",
 ]
 
 [project.urls]

{docstring_format_checker-1.0.1 → docstring_format_checker-1.2.0}/src/docstring_format_checker/cli.py

@@ -43,12 +43,14 @@
 
 
 # ## Python StdLib Imports ----
+import os
 from functools import partial
 from pathlib import Path
 from textwrap import dedent
 from typing import Optional
 
 # ## Python Third Party Imports ----
+import pyfiglet
 from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
@@ -160,29 +162,6 @@ def _version_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
         raise Exit()
 
 
-def _help_callback_main(ctx: Context, param: CallbackParam, value: bool) -> None:
-    """
-    !!! note "Summary"
-        Show help and exit.
-
-    Params:
-        ctx (Context):
-            The context object.
-        param (CallbackParam):
-            The parameter object.
-        value (bool):
-            The boolean value indicating if the flag was set.
-
-    Returns:
-        (None):
-            Nothing is returned.
-    """
-    if not value or ctx.resilient_parsing:
-        return
-    echo(ctx.get_help())
-    raise Exit()
-
-
 def _example_callback(ctx: Context, param: CallbackParam, value: Optional[str]) -> None:
     """
     !!! note "Summary"
@@ -211,6 +190,7 @@ def _example_callback(ctx: Context, param: CallbackParam, value: Optional[str])
     else:
         console.print(_red(f"Error: Invalid example type '{value}'. Use 'config' or 'usage'."))
         raise Exit(1)
+    raise Exit()
 
 
 def _show_usage_examples_callback() -> None:
@@ -233,30 +213,33 @@ def _show_usage_examples_callback() -> None:
 
     examples_content: str = dedent(
         f"""
-        {_green("dfc myfile.py")}                   Check a single Python file (list output)
-        {_green("dfc src/")}                        Check all Python files in src/ directory
-        {_green("dfc --output=table myfile.py")}    Check with table output format
-        {_green("dfc -o list myfile.py")}           Check with list output format (default)
-        {_green("dfc --check myfile.py")}           Check and exit with error if issues found
-        {_green("dfc --quiet myfile.py")}           Check quietly, only show pass/fail
-        {_green("dfc --quiet --check myfile.py")}   Check quietly and exit with error if issues found
-        {_green("dfc . --exclude '*/tests/*'")}     Check current directory, excluding tests
-        {_green("dfc . -c custom.toml")}            Use custom configuration file
-        {_green("dfc --example=config")}            Show example configuration
-        {_green("dfc -e usage")}                    Show usage examples (this help)
+        Execute the below commands in any terminal after installing the package.
+
+        {_blue("dfc myfile.py")}                   {_green("# Check a single Python file (list output)")}
+        {_blue("dfc myfile.py other_file.py")}     {_green("# Check multiple Python files")}
+        {_blue("dfc src/")}                        {_green("# Check all Python files in src/ directory")}
+        {_blue("dfc -x src/app/__init__.py src/")} {_green("# Check all Python files in src/ directory, excluding one init file")}
+        {_blue("dfc --output=table myfile.py")}    {_green("# Check with table output format")}
+        {_blue("dfc -o list myfile.py")}           {_green("# Check with list output format (default)")}
+        {_blue("dfc --check myfile.py")}           {_green("# Check and exit with error if issues found")}
+        {_blue("dfc --quiet myfile.py")}           {_green("# Check quietly, only show pass/fail")}
+        {_blue("dfc --quiet --check myfile.py")}   {_green("# Check quietly and exit with error if issues found")}
+        {_blue("dfc . --exclude '*/tests/*'")}     {_green("# Check current directory, excluding tests")}
+        {_blue("dfc . -c custom.toml")}            {_green("# Use custom configuration file")}
+        {_blue("dfc --example=config")}            {_green("# Show example configuration")}
+        {_blue("dfc -e usage")}                    {_green("# Show usage examples (this help)")}
         """
     ).strip()
 
     panel = Panel(
         examples_content,
-        title="Examples",
+        title="Usage Examples",
         title_align="left",
         border_style="dim",
         padding=(0, 1),
     )
 
     console.print(panel)
-    raise Exit()
 
 
 def _show_config_example_callback() -> None:
@@ -278,73 +261,84 @@ def _show_config_example_callback() -> None:
     """
 
     example_config: str = dedent(
-        """
-        # Example configuration for docstring-format-checker
-        # Place this in your pyproject.toml file
-
-        [tool.dfc]
-        # or [tool.docstring-format-checker]
-
-        [[tool.dfc.sections]]
-        order = 1
-        name = "summary"
-        type = "free_text"
-        admonition = "note"
-        prefix = "!!!"
-        required = true
-
-        [[tool.dfc.sections]]
-        order = 2
-        name = "details"
-        type = "free_text"
-        admonition = "info"
-        prefix = "???+"
-        required = false
-
-        [[tool.dfc.sections]]
-        order = 3
-        name = "params"
-        type = "list_name_and_type"
-        required = true
-
-        [[tool.dfc.sections]]
-        order = 4
-        name = "returns"
-        type = "list_name_and_type"
-        required = false
-
-        [[tool.dfc.sections]]
-        order = 5
-        name = "yields"
-        type = "list_type"
-        required = false
-
-        [[tool.dfc.sections]]
-        order = 6
-        name = "raises"
-        type = "list_type"
-        required = false
-
-        [[tool.dfc.sections]]
-        order = 7
-        name = "examples"
-        type = "free_text"
-        admonition = "example"
-        prefix = "???+"
-        required = false
-
-        [[tool.dfc.sections]]
-        order = 8
-        name = "notes"
-        type = "free_text"
-        admonition = "note"
-        prefix = "???"
-        required = false
+        r"""
+        Place the below config in your `pyproject.toml` file.
+
+        [blue]\[tool.dfc][/blue]
+        [green]# or \[tool.docstring-format-checker][/green]
+        [blue]allow_undefined_sections = false[/blue]
+        [blue]require_docstrings = true[/blue]
+        [blue]check_private = true[/blue]
+        [blue]sections = [[/blue]
+            [blue]{ order = 1, name = "summary",  type = "free_text",          required = true, admonition = "note", prefix = "!!!" },[/blue]
+            [blue]{ order = 2, name = "details",  type = "free_text",          required = false, admonition = "abstract", prefix = "???+" },[/blue]
+            [blue]{ order = 3, name = "params",   type = "list_name_and_type", required = false },[/blue]
+            [blue]{ order = 4, name = "raises",   type = "list_type",          required = false },[/blue]
+            [blue]{ order = 5, name = "returns",  type = "list_name_and_type", required = false },[/blue]
+            [blue]{ order = 6, name = "yields",   type = "list_type",          required = false },[/blue]
+            [blue]{ order = 7, name = "examples", type = "free_text",          required = false, admonition = "example", prefix = "???+" },[/blue]
+            [blue]{ order = 8, name = "notes",    type = "free_text",          required = false, admonition = "note", prefix = "???" },[/blue]
+        [blue]][/blue]
         """
     ).strip()
 
+    panel = Panel(
+        example_config,
+        title="Configuration Example",
+        title_align="left",
+        border_style="dim",
+        padding=(0, 1),
+    )
+
     # Print without Rich markup processing to avoid bracket interpretation
-    console.print(example_config, markup=False)
+    console.print(panel)
+
+
+def _help_callback_main(ctx: Context, param: CallbackParam, value: bool) -> None:
+    """
+    !!! note "Summary"
+        Show help and exit.
+
+    Params:
+        ctx (Context):
+            The context object.
+        param (CallbackParam):
+            The parameter object.
+        value (bool):
+            The boolean value indicating if the flag was set.
+
+    Returns:
+        (None):
+            Nothing is returned.
+    """
+
+    # Early exit if help flag is set
+    if not value or ctx.resilient_parsing:
+        return
+
+    # Determine terminal width for ASCII art
+    try:
+        terminal_width: int = os.get_terminal_size().columns
+    except OSError:
+        terminal_width = 80
+
+    # Determine title based on terminal width
+    title: str = "dfc" if terminal_width < 130 else "docstring-format-checker"
+
+    # Print ASCII art title
+    console.print(
+        pyfiglet.figlet_format(title, font="standard", justify="left", width=140),
+        style="magenta",
+        markup=False,
+    )
+
+    # Show help message
+    echo(ctx.get_help())
+
+    # Show usage and config examples
+    _show_usage_examples_callback()
+    _show_config_example_callback()
+
     raise Exit()
 
 
@@ -497,7 +491,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(
-    path: str,
+    paths: list[str],
     config: Optional[str] = None,
     exclude: Optional[list[str]] = None,
     quiet: bool = False,
@@ -509,8 +503,8 @@ def check_docstrings(
         Core logic for checking docstrings.
 
     Params:
-        path (str):
-            The path to the file or directory to check.
+        paths (list[str]):
+            The path(s) to the file(s) or directory(ies) to check.
         config (Optional[str]):
             The path to the configuration file.
             Default: `None`.
@@ -532,14 +526,20 @@ def check_docstrings(
             Nothing is returned.
     """
 
-    target_path = Path(path)
-
-    # Validate target path
-    if not target_path.exists():
-        console.print(_red(f"Error: Path does not exist: '{path}'"))
+    # Validate all target 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:
+        console.print(
+            _red(f"[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
+    # Load configuration (use first path for config discovery if no config specified)
     try:
         if config:
             config_path = Path(config)
@@ -548,8 +548,9 @@ def check_docstrings(
                 raise Exit(1)
             config_obj = load_config(config_path)
         else:
-            # Try to find config file automatically
-            found_config: Optional[Path] = find_config_file(target_path if target_path.is_dir() else target_path.parent)
+            # 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:
@@ -562,19 +563,27 @@ def check_docstrings(
     # Initialize checker
     checker = DocstringChecker(config_obj)
 
-    # Check files
+    # Check all paths and collect results
+    all_results: dict[str, list[DocstringError]] = {}
+
     try:
-        if target_path.is_file():
-            errors: list[DocstringError] = checker.check_file(target_path)
-            results: dict[str, list[DocstringError]] = {str(target_path): errors} if errors else {}
-        else:
-            results: dict[str, list[DocstringError]] = checker.check_directory(target_path, exclude_patterns=exclude)
+        for target_path in target_paths:
+            if target_path.is_file():
+                errors: list[DocstringError] = 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
+                )
+                all_results.update(directory_results)
+
     except Exception as e:
         console.print(_red(f"Error during checking: {e}"))
         raise Exit(1)
 
     # Display results
-    exit_code: int = _display_results(results, quiet, output, check)
+    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:
@@ -592,7 +601,7 @@ def check_docstrings(
 @app.callback(invoke_without_command=True)
 def main(
     ctx: Context,
-    path: Optional[str] = Argument(None, help="Path to Python file or directory to check"),
+    paths: Optional[list[str]] = Argument(None, help="Path(s) to Python file(s) or directory(s) for DFC to check"),
     config: Optional[str] = Option(None, "--config", "-f", help="Path to configuration file (TOML format)"),
     exclude: Optional[list[str]] = Option(
         None,
@@ -654,8 +663,8 @@ def main(
     Params:
         ctx (Context):
             The context object for the command.
-        path (Optional[str]):
-            Path to Python file or directory to check.
+        paths (Optional[list[str]]):
+            Path(s) to Python file(s) or directory(ies) to check.
         config (Optional[str]):
             Path to configuration file (TOML format).
         exclude (Optional[list[str]]):
@@ -678,8 +687,8 @@ def main(
             Nothing is returned.
     """
 
-    # If no path is provided, show help
-    if path is None:
+    # If no paths are provided, show help
+    if not paths:
         echo(ctx.get_help())
         raise Exit(0)
 
@@ -689,7 +698,7 @@ def main(
         raise Exit(1)
 
     check_docstrings(
-        path=path,
+        paths=paths,
         config=config,
         exclude=exclude,
         quiet=quiet,
@@ -704,7 +713,3 @@ def entry_point() -> None:
         Entry point for the CLI scripts defined in pyproject.toml.
     """
     app()
-
-
-if __name__ == "__main__":
-    app()