docstring-format-checker 0.4.0__tar.gz → 0.6.0__tar.gz

{docstring_format_checker-0.4.0 → docstring_format_checker-0.6.0}/PKG-INFO

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

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

{docstring_format_checker-0.4.0 → docstring_format_checker-0.6.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.4.0"
+__version__ = "v0.6.0"
 __author__ = "Chris Mahoney"
 __email__ = "docstring-format-checker@data-science-extensions.com"
 

{docstring_format_checker-0.4.0 → docstring_format_checker-0.6.0}/src/docstring_format_checker/cli.py

@@ -43,25 +43,16 @@
 
 
 # ## Python StdLib Imports ----
+from functools import partial
 from pathlib import Path
 from textwrap import dedent
-from typing import Optional, Union
+from typing import Optional
 
 # ## Python Third Party Imports ----
 from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
-from toolbox_python.bools import strtobool
-from typer import (
-    Argument,
-    BadParameter,
-    CallbackParam,
-    Context,
-    Exit,
-    Option,
-    Typer,
-    echo,
-)
+from typer import Argument, CallbackParam, Context, Exit, Option, Typer, echo
 
 # ## Local First Party Imports ----
 from docstring_format_checker import __version__
@@ -76,8 +67,6 @@ from docstring_format_checker.core import DocstringChecker, DocstringError
 
 __all__: list[str] = [
     "main",
-    "config_example",
-    "check",
     "entry_point",
 ]
 
@@ -90,6 +79,22 @@ __all__: list[str] = [
 NEW_LINE = "\n"
 
 
+## --------------------------------------------------------------------------- #
+##  Helpers                                                                 ####
+## --------------------------------------------------------------------------- #
+
+
+### Colours ----
+def _colour(text: str, colour: str) -> str:
+    return f"[{colour}]{text}[/{colour}]"
+
+
+_green = partial(_colour, colour="green")
+_red = partial(_colour, colour="red")
+_cyan = partial(_colour, colour="cyan")
+_blue = partial(_colour, colour="blue")
+
+
 # ---------------------------------------------------------------------------- #
 #                                                                              #
 #     Main Application                                                      ####
@@ -136,7 +141,7 @@ def _version_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
         raise Exit()
 
 
-def _help_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
+def _help_callback_main(ctx: Context, param: CallbackParam, value: bool) -> None:
     """
     !!! note "Summary"
         Show help and exit.
@@ -159,10 +164,10 @@ def _help_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
     raise Exit()
 
 
-def _parse_boolean_flag(ctx: Context, param: CallbackParam, value: Optional[str]) -> Optional[bool]:
+def _example_callback(ctx: Context, param: CallbackParam, value: Optional[str]) -> None:
     """
     !!! note "Summary"
-        Parse boolean flag that accepts various true/false values.
+        Handle example flag and show appropriate example content.
 
     Params:
         ctx (Context):
@@ -170,51 +175,26 @@ def _parse_boolean_flag(ctx: Context, param: CallbackParam, value: Optional[str]
         param (CallbackParam):
             The parameter object.
         value (Optional[str]):
-            The string value of the flag.
+            The example type to show: 'config' or 'usage'.
 
     Returns:
-        (Optional[bool]):
-            The parsed boolean value or `None` if not provided.
-    """
-
-    # Handle the case where the flag is provided without a value (e.g., just --recursive or -r)
-    # In this case, Typer doesn't call the callback, so we need to handle it differently
-    if value is None:
-        # This means the flag wasn't provided at all, use default
-        return True
-
-    # If value is an empty string, it means the flag was provided without a value
-    if value == "":
-        return True
-
-    try:
-        return strtobool(value)
-    except ValueError as e:
-        raise BadParameter(
-            message=(
-                f"Invalid boolean value: '{value}'.{NEW_LINE}"
-                "Use one of: true/false, t/f, yes/no, y/n, 1/0, or on/off."
-            )
-        ) from e
-
-
-def _parse_recursive_flag(value: str) -> bool:
+        (None):
+            Nothing is returned.
     """
-    !!! note "Summary"
-        Parse recursive flag using `strtobool()` utility.
 
-    Params:
-        value (str):
-            The string value of the flag.
+    if not value or ctx.resilient_parsing:
+        return
 
-    Returns:
-        (bool):
-            The parsed boolean value.
-    """
-    return strtobool(value)
+    if value == "config":
+        _show_config_example_callback()
+    elif value == "usage":
+        _show_usage_examples_callback()
+    else:
+        console.print(_red(f"Error: Invalid example type '{value}'. Use 'config' or 'usage'."))
+        raise Exit(1)
 
 
-def _show_examples_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
+def _show_usage_examples_callback() -> None:
     """
     !!! note "Summary"
         Show examples and exit.
@@ -232,17 +212,19 @@ def _show_examples_callback(ctx: Context, param: CallbackParam, value: bool) ->
             Nothing is returned.
     """
 
-    if not value or ctx.resilient_parsing:
-        return
-
     examples_content: str = dedent(
-        """
-        [green]dfc check myfile.py[/green]                    Check a single Python file
-        [green]dfc check src/[/green]                         Check all Python files in src/ directory
-        [green]dfc check . --exclude "*/tests/*"[/green]      Check current directory, excluding tests
-        [green]dfc check . -c custom.toml[/green]             Use custom configuration file
-        [green]dfc check . --verbose[/green]                  Show detailed validation output
-        [green]dfc config-example[/green]                     Show example configuration
+        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)
         """
     ).strip()
 
@@ -258,10 +240,10 @@ def _show_examples_callback(ctx: Context, param: CallbackParam, value: bool) ->
     raise Exit()
 
 
-def _show_check_examples_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
+def _show_config_example_callback() -> None:
     """
     !!! note "Summary"
-        Show check command examples and exit.
+        Show configuration example and exit.
 
     Params:
         ctx (Context):
@@ -276,29 +258,74 @@ def _show_check_examples_callback(ctx: Context, param: CallbackParam, value: boo
             Nothing is returned.
     """
 
-    if not value or ctx.resilient_parsing:
-        return
-
-    examples_content: str = dedent(
-        """
-        [green]dfc check myfile.py[/green]                    Check a single Python file
-        [green]dfc check src/[/green]                         Check all Python files in src/ directory
-        [green]dfc check . --exclude "*/tests/*"[/green]      Check current directory, excluding tests
-        [green]dfc check . --config custom.toml[/green]       Use custom configuration file
-        [green]dfc check . --verbose --recursive[/green]      Show detailed output for all subdirectories
-        [green]dfc check . --quiet[/green]                    Only show errors, suppress success messages
+    example_config: str = dedent(
         """
-    )
+        # Example configuration for docstring-format-checker
+        # Place this in your pyproject.toml file
 
-    panel = Panel(
-        examples_content,
-        title="Check Command Examples",
-        title_align="left",
-        border_style="dim",
-        padding=(0, 1),
-    )
+        [tool.dfc]
+        # or [tool.docstring-format-checker]
 
-    console.print(panel)
+        [[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
+        """
+    ).strip()
+
+    # Print without Rich markup processing to avoid bracket interpretation
+    console.print(example_config, markup=False)
     raise Exit()
 
 
@@ -325,7 +352,7 @@ def _format_error_messages(error_message: str) -> str:
         return f"- {error_message.strip()}."
 
 
-def _display_results(results: dict[str, list[DocstringError]], quiet: bool, verbose: 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.
@@ -334,9 +361,11 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, verb
         results (dict[str, list[DocstringError]]):
             Dictionary mapping file paths to lists of errors
         quiet (bool):
-            Whether to suppress success messages
-        verbose (bool):
-            Whether to show detailed output
+            Whether to suppress success messages and error details
+        output (str):
+            Output format: 'table' or 'list'
+        check (bool):
+            Whether this is a check run (affects quiet behavior)
 
     Returns:
         (int):
@@ -344,14 +373,42 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, verb
     """
     if not results:
         if not quiet:
-            console.print("[green]✓ All docstrings are valid![/green]")
+            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 verbose:
+    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"
+
+        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)
@@ -377,22 +434,43 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, verb
         console.print(table)
 
     else:
-        # Show compact output
+        # Show compact output - each individual error on its own line
         for file_path, errors in results.items():
-            console.print(f"{NEW_LINE}[cyan]{file_path}[/cyan]")
+            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)
-
-                if error.line_number > 0:
-                    console.print(
-                        f"  [red]Line {error.line_number}[/red] - {error.item_type} '{error.item_name}': {formatted_error_message}"
-                    )
+                # Split error message into individual errors for list mode
+                if "; " in error.message:
+                    individual_errors = [msg.strip() for msg in error.message.split("; ") if msg.strip()]
+                    for individual_error in individual_errors:
+                        formatted_error = f"- {individual_error}"
+                        if error.line_number > 0:
+                            console.print(
+                                f"  [red]Line {error.line_number}[/red] - {error.item_type} '{error.item_name}': {formatted_error}"
+                            )
+                        else:
+                            console.print(f"  {_red('Error')}: {formatted_error}")
                 else:
-                    console.print(f"  [red]Error[/red]: {formatted_error_message}")
+                    # Single error message
+                    formatted_error = f"- {error.message.strip()}"
+                    if error.line_number > 0:
+                        console.print(
+                            f"  [red]Line {error.line_number}[/red] - {error.item_type} '{error.item_name}': {formatted_error}"
+                        )
+                    else:
+                        console.print(f"  {_red('Error')}: {formatted_error}")
+
+    # Summary - more descriptive message
+    if total_functions == 1:
+        functions_text = f"1 function"
+    else:
+        functions_text = f"{total_functions} functions"
 
-    # Summary
-    console.print(f"{NEW_LINE}[red]Found {total_errors} error(s) in {total_files} file(s)[/red]")
+    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
 
@@ -405,13 +483,13 @@ def _display_results(results: dict[str, list[DocstringError]], quiet: bool, verb
 
 
 # This will be the default behavior when no command is specified
-def _check_docstrings(
+def check_docstrings(
     path: str,
     config: Optional[str] = None,
-    recursive: bool = True,
     exclude: Optional[list[str]] = None,
     quiet: bool = False,
-    verbose: bool = False,
+    output: str = "list",
+    check: bool = False,
 ) -> None:
     """
     !!! note "Summary"
@@ -422,14 +500,19 @@ def _check_docstrings(
             The path to the file or directory to check.
         config (Optional[str]):
             The path to the configuration file.
-        recursive (bool):
-            Whether to check files recursively.
+            Default: `None`.
         exclude (Optional[list[str]]):
             List of glob patterns to exclude from checking.
+            Default: `None`.
         quiet (bool):
             Whether to suppress output.
-        verbose (bool):
-            Whether to show detailed 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):
@@ -440,7 +523,7 @@ def _check_docstrings(
 
     # Validate target path
     if not target_path.exists():
-        console.print(f"[red]Error: Path does not exist: {path}[/red]")
+        console.print(_red(f"Error: Path does not exist: '{path}'"))
         raise Exit(1)
 
     # Load configuration
@@ -448,25 +531,19 @@ def _check_docstrings(
         if config:
             config_path = Path(config)
             if not config_path.exists():
-                console.print(f"[red]Error: Configuration file does not exist: {config}[/red]")
+                console.print(_red(f"Error: Configuration file does not exist: {config}"))
                 raise Exit(1)
             sections_config = load_config(config_path)
         else:
             # Try to find config file automatically
-            found_config: Union[Path, None] = find_config_file(
-                target_path if target_path.is_dir() else target_path.parent
-            )
+            found_config: Optional[Path] = find_config_file(target_path if target_path.is_dir() else target_path.parent)
             if found_config:
-                if verbose:
-                    console.print(f"[blue]Using configuration from: {found_config}[/blue]")
                 sections_config: list[SectionConfig] = load_config(found_config)
             else:
-                if verbose:
-                    console.print("[blue]Using default configuration[/blue]")
                 sections_config: list[SectionConfig] = load_config()
 
     except Exception as e:
-        console.print(f"[red]Error loading configuration: {e}[/red]")
+        console.print(_red(f"Error loading configuration: {e}"))
         raise Exit(1)
 
     # Initialize checker
@@ -475,23 +552,18 @@ def _check_docstrings(
     # Check files
     try:
         if target_path.is_file():
-            if verbose:
-                console.print(f"[blue]Checking file: {target_path}[/blue]")
             errors: list[DocstringError] = checker.check_file(target_path)
             results: dict[str, list[DocstringError]] = {str(target_path): errors} if errors else {}
         else:
-            if verbose:
-                console.print(f"[blue]Checking directory: {target_path} (recursive={recursive})[/blue]")
-            results: dict[str, list[DocstringError]] = checker.check_directory(
-                target_path, recursive=recursive, exclude_patterns=exclude
-            )
+            results: dict[str, list[DocstringError]] = checker.check_directory(target_path, exclude_patterns=exclude)
     except Exception as e:
-        console.print(f"[red]Error during checking: {e}[/red]")
+        console.print(_red(f"Error during checking: {e}"))
         raise Exit(1)
 
     # Display results
-    exit_code: int = _display_results(results, quiet, verbose)
+    exit_code: int = _display_results(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)
 
@@ -507,6 +579,41 @@ 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"),
+    config: Optional[str] = Option(None, "--config", "-f", help="Path to configuration file (TOML format)"),
+    exclude: Optional[list[str]] = Option(
+        None,
+        "--exclude",
+        "-x",
+        help="Glob patterns to exclude (can be used multiple times)",
+    ),
+    output: str = Option(
+        "list",
+        "--output",
+        "-o",
+        help="Output format: 'table' or 'list'",
+        show_default=True,
+    ),
+    check: bool = Option(
+        False,
+        "--check",
+        "-c",
+        help="Throw error (exit 1) if any issues are found",
+    ),
+    quiet: bool = Option(
+        False,
+        "--quiet",
+        "-q",
+        help="Only output pass/fail confirmation, suppress errors unless failing",
+    ),
+    example: Optional[str] = Option(
+        None,
+        "--example",
+        "-e",
+        callback=_example_callback,
+        is_eager=True,
+        help="Show examples: 'config' for configuration example, 'usage' for usage examples",
+    ),
     version: Optional[bool] = Option(
         None,
         "--version",
@@ -515,19 +622,11 @@ def main(
         is_eager=True,
         help="Show version and exit",
     ),
-    examples: Optional[bool] = Option(
-        None,
-        "--examples",
-        "-e",
-        callback=_show_examples_callback,
-        is_eager=True,
-        help="Show usage examples and exit",
-    ),
     help_flag: Optional[bool] = Option(
         None,
         "--help",
         "-h",
-        callback=_help_callback,
+        callback=_help_callback_main,
         is_eager=True,
         help="Show this message and exit",
     ),
@@ -542,122 +641,22 @@ def main(
     Params:
         ctx (Context):
             The context object for the command.
-        version (Optional[bool]):
-            Show version and exit.
-        examples (Optional[bool]):
-            Show usage examples and exit.
-        help_flag (Optional[bool]):
-            Show help message and exit.
-
-    Returns:
-        (None):
-            Nothing is returned.
-    """
-    # If no subcommand is provided, show help
-    if ctx.invoked_subcommand is None:
-        echo(ctx.get_help())
-        raise Exit()
-
-
-@app.command(
-    rich_help_panel="Commands",
-    add_help_option=False,  # Disable automatic help so we can add our own with -h
-)
-def check(
-    path: str = Argument(..., help="Path to Python file or directory to check"),
-    config: Optional[str] = Option(None, "--config", "-c", help="Path to configuration file (TOML format)"),
-    recursive: str = Option(
-        "true",
-        "--recursive",
-        "-r",
-        help="Check directories recursively (default: true). Accepts: true/false, t/f, yes/no, y/n, 1/0, on/off",
-    ),
-    exclude: Optional[list[str]] = Option(
-        None,
-        "--exclude",
-        "-x",
-        help="Glob patterns to exclude (can be used multiple times)",
-    ),
-    quiet: bool = Option(False, "--quiet", "-q", help="Only show errors, no success messages"),
-    verbose: bool = Option(False, "--verbose", "-n", help="Show detailed output"),
-    examples: Optional[bool] = Option(
-        None,
-        "--examples",
-        "-e",
-        callback=_show_check_examples_callback,
-        is_eager=True,
-        help="Show usage examples and exit",
-    ),
-    help_flag: Optional[bool] = Option(
-        None,
-        "--help",
-        "-h",
-        callback=_help_callback,
-        is_eager=True,
-        help="Show this message and exit",
-    ),
-) -> None:
-    """
-    !!! note "Summary"
-        Check docstrings in Python files.
-
-    ???+ abstract "Details"
-        This command checks the docstrings in the specified Python file or directory.
-
-    Params:
-        path (str):
-            The path to the Python file or directory to check.
+        path (Optional[str]):
+            Path to Python file or directory to check.
         config (Optional[str]):
-            The path to the configuration file (TOML format).
-        recursive (bool):
-            Whether to check directories recursively.
-        exclude (list[str]):
-            Glob patterns to exclude (can be used multiple times).
+            Path to configuration file (TOML format).
+        exclude (Optional[list[str]]):
+            Glob patterns to exclude.
+        output (str):
+            Output format: 'table' or 'list'.
+        check (bool):
+            Throw error if any issues are found.
         quiet (bool):
-            Whether to only show errors, no success messages.
-        verbose (bool):
-            Whether to show detailed output.
-        examples (Optional[bool]):
-            Show usage examples and exit.
-        help_flag (Optional[bool]):
-            Show help message and exit.
-
-    Returns:
-        (None):
-            Nothing is returned.
-    """
-    # Parse the recursive string value into a boolean
-    try:
-        recursive_bool: bool = _parse_recursive_flag(recursive)
-    except ValueError as e:
-        raise BadParameter(
-            message=(
-                f"Invalid value for --recursive: '{recursive}'.{NEW_LINE}"
-                "Use one of: true/false, t/f, yes/no, y/n, 1/0, or on/off."
-            )
-        ) from e
-    _check_docstrings(path, config, recursive_bool, exclude, quiet, verbose)
-
-
-@app.command(
-    rich_help_panel="Commands",
-    add_help_option=False,  # Disable automatic help so we can add our own with -h
-)
-def config_example(
-    help_flag: Optional[bool] = Option(
-        None,
-        "--help",
-        "-h",
-        callback=_help_callback,
-        is_eager=True,
-        help="Show this message and exit",
-    ),
-) -> None:
-    """
-    !!! note "Summary"
-        Show example configuration file.
-
-    Params:
+            Only output pass/fail confirmation.
+        example (Optional[str]):
+            Show examples: 'config' or 'usage'.
+        version (Optional[bool]):
+            Show version and exit.
         help_flag (Optional[bool]):
             Show help message and exit.
 
@@ -665,74 +664,26 @@ def config_example(
         (None):
             Nothing is returned.
     """
-    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
+    # If no path is provided, show help
+    if path is None:
+        echo(ctx.get_help())
+        raise Exit(0)
 
-        [[tool.dfc.sections]]
-        order = 7
-        name = "examples"
-        type = "free_text"
-        admonition = "example"
-        prefix = "???+"
-        required = false
+    # Validate output format
+    if output not in ["table", "list"]:
+        console.print(_red(f"Error: Invalid output format '{output}'. Use 'table' or 'list'."))
+        raise Exit(1)
 
-        [[tool.dfc.sections]]
-        order = 8
-        name = "notes"
-        type = "free_text"
-        admonition = "note"
-        prefix = "???"
-        required = false
-        """.strip()
+    check_docstrings(
+        path=path,
+        config=config,
+        exclude=exclude,
+        quiet=quiet,
+        output=output,
+        check=check,
     )
 
-    print(example_config)
-
 
 def entry_point() -> None:
     """

{docstring_format_checker-0.4.0 → docstring_format_checker-0.6.0}/src/docstring_format_checker/core.py

@@ -167,18 +167,15 @@ class DocstringChecker:
     def check_directory(
         self,
         directory_path: Union[str, Path],
-        recursive: bool = True,
         exclude_patterns: Optional[list[str]] = None,
     ) -> dict[str, list[DocstringError]]:
         """
         !!! note "Summary"
-            Check docstrings in all Python files in a directory.
+            Check docstrings in all Python files in a directory recursively.
 
         Params:
             directory_path (Union[str, Path]):
                 Path to the directory to check.
-            recursive (bool):
-                Whether to check subdirectories recursively.
             exclude_patterns (Optional[list[str]]):
                 List of glob patterns to exclude.
 
@@ -200,13 +197,7 @@ class DocstringChecker:
         if not directory_path.is_dir():
             raise DirectoryNotFoundError(f"Path is not a directory: {directory_path}")
 
-        # Find all Python files
-        if recursive:
-            pattern = "**/*.py"
-        else:
-            pattern = "*.py"
-
-        python_files: list[Path] = list(directory_path.glob(pattern))
+        python_files: list[Path] = list(directory_path.glob("**/*.py"))
 
         # Filter out excluded patterns
         if exclude_patterns:
@@ -971,9 +962,41 @@ class DocstringChecker:
             if current_section and stripped_line and not stripped_line.startswith(("!", "?", "#")):
                 # Look for parameter/type definitions
                 if ":" in stripped_line:
+                    # 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_name_and_type sections, check format like "name (type):" or "(type):"
                     if current_section.type == "list_name_and_type":
                         # Pattern: name (type): or (type):
+                        # 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
+
                         if not re.search(r"\([^)]+\):", stripped_line):
                             errors.append(
                                 f"Section '{current_section.name}' (type: '{current_section.type}') requires "