CLI

docstring_format_checker.cli 🔗

Summary

Command-line interface for the docstring format checker.

NEW_LINE `module-attribute` 🔗

NEW_LINE = '\n'

_colour 🔗

_colour(text: str, colour: str) -> str

Summary

Apply Rich colour markup to text.

Parameters:

Name	Type	Description	Default
`text`	`str`	The text to colour.	required
`colour`	`str`	The colour to apply, e.g., 'red', 'green', 'blue'.	required

Returns:

Type	Description
`str`	The text wrapped in Rich colour markup.

Source code in src/docstring_format_checker/cli.py

def _colour(text: str, colour: str) -> str:
    """
    !!! note "Summary"
        Apply Rich colour markup to text.

    Params:
        text (str):
            The text to colour.
        colour (str):
            The colour to apply, e.g., 'red', 'green', 'blue'.

    Returns:
        (str):
            The text wrapped in Rich colour markup.
    """
    return f"[{colour}]{text}[/{colour}]"

_green `module-attribute` 🔗

_green = partial(_colour, colour='green')

_red `module-attribute` 🔗

_red = partial(_colour, colour='red')

_cyan `module-attribute` 🔗

_cyan = partial(_colour, colour='cyan')

_blue `module-attribute` 🔗

_blue = partial(_colour, colour='blue')

app `module-attribute` 🔗

app = Typer(
    name="docstring-format-checker",
    help="A CLI tool to check and validate Python docstring formatting and completeness.",
    add_completion=False,
    rich_markup_mode="rich",
    add_help_option=False,
)

console `module-attribute` 🔗

console = Console()

_version_callback 🔗

_version_callback(
    ctx: Context, param: CallbackParam, value: bool
) -> None

Summary

Print version and exit.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The context object.	required
`param`	`CallbackParam`	The parameter object.	required
`value`	`bool`	The boolean value indicating if the flag was set.	required

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

def _version_callback(ctx: Context, param: CallbackParam, value: bool) -> None:
    """
    !!! note "Summary"
        Print version 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 value:
        echo(f"docstring-format-checker version {__version__}")
        raise Exit()

_example_callback 🔗

_example_callback(
    ctx: Context, param: CallbackParam, value: Optional[str]
) -> None

Summary

Handle example flag and show appropriate example content.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The context object.	required
`param`	`CallbackParam`	The parameter object.	required
`value`	`Optional[str]`	The example type to show: 'config' or 'usage'.	required

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

def _example_callback(ctx: Context, param: CallbackParam, value: Optional[str]) -> None:
    """
    !!! note "Summary"
        Handle example flag and show appropriate example content.

    Params:
        ctx (Context):
            The context object.
        param (CallbackParam):
            The parameter object.
        value (Optional[str]):
            The example type to show: 'config' or 'usage'.

    Returns:
        (None):
            Nothing is returned.
    """

    if not value or ctx.resilient_parsing:
        return

    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)
    raise Exit()

_show_usage_examples_callback 🔗

_show_usage_examples_callback() -> None

Summary

Show examples and exit.

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

def _show_usage_examples_callback() -> None:
    """
    !!! note "Summary"
        Show examples and exit.

    Returns:
        (None):
            Nothing is returned.
    """

    examples_content: str = dedent(
        f"""
        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="Usage Examples",
        title_align="left",
        border_style="dim",
        padding=(0, 1),
    )

    console.print(panel)

_show_config_example_callback 🔗

_show_config_example_callback() -> None

Summary

Show configuration example and exit.

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

def _show_config_example_callback() -> None:
    """
    !!! note "Summary"
        Show configuration example and exit.

    Returns:
        (None):
            Nothing is returned.
    """

    example_config: str = dedent(
        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]validate_param_types = true[/blue]
        [blue]optional_style = "validate"[/blue]  [green]# "silent", "validate", or "strict"[/green]
        [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(panel)

_help_callback_main 🔗

_help_callback_main(
    ctx: Context, param: CallbackParam, value: bool
) -> None

Summary

Show help and exit.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The context object.	required
`param`	`CallbackParam`	The parameter object.	required
`value`	`bool`	The boolean value indicating if the flag was set.	required

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

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()

_format_error_messages 🔗

_format_error_messages(error_message: str) -> str

!!! note "Summary"
    Format error messages for better readability in CLI output.

Params:
    error_message (str):
        The raw error message that may contain semicolon-separated errors

Returns:
    (str):
        Formatted error message with each error prefixed with "- " and separated by ";

"

Source code in src/docstring_format_checker/cli.py

def _format_error_messages(error_message: str) -> str:
    """
    !!! note "Summary"
        Format error messages for better readability in CLI output.

    Params:
        error_message (str):
            The raw error message that may contain semicolon-separated errors

    Returns:
        (str):
            Formatted error message with each error prefixed with "- " and separated by ";\n"
    """
    if "; " in error_message:
        # Split by semicolon and rejoin with proper formatting
        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:
        return f"- {error_message.strip()}."

_display_results 🔗

_display_results(
    results: dict[str, list[DocstringError]],
    quiet: bool,
    output: str,
    check: bool,
) -> int

Summary

Display the results of docstring checking.

Parameters:

Name	Type	Description	Default
`results`	`dict[str, list[DocstringError]]`	Dictionary mapping file paths to lists of errors	required
`quiet`	`bool`	Whether to suppress success messages and error details	required
`output`	`str`	Output format: 'table' or 'list'	required
`check`	`bool`	Whether this is a check run (affects quiet behavior)	required

Returns:

Type	Description
`int`	Exit code (`0` for success, `1` for errors found)

Source code in src/docstring_format_checker/cli.py

def _display_results(
    results: dict[str, list[DocstringError]],
    quiet: bool,
    output: str,
    check: bool,
) -> int:
    """
    !!! note "Summary"
        Display the results of docstring checking.

    Params:
        results (dict[str, list[DocstringError]]):
            Dictionary mapping file paths to lists of errors
        quiet (bool):
            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):
            Exit code (`0` for success, `1` for errors found)
    """
    if not results:
        if not quiet:
            console.print(_green("✅ All docstrings are valid!"))
        return 0

    # 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

_count_errors_and_files 🔗

_count_errors_and_files(
    results: dict[str, list[DocstringError]],
) -> dict[str, int]

Summary

Count total errors, functions, and files from results.

Parameters:

Name	Type	Description	Default
`results`	`dict[str, list[DocstringError]]`	Dictionary mapping file paths to lists of errors.	required

Returns:

Type	Description
`dict[str, int]`	Dictionary containing total_errors, total_functions, and total_files.

Source code in src/docstring_format_checker/cli.py

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)
        for error in errors:
            if "; " in error.message:
                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

    return {"total_errors": total_individual_errors, "total_functions": total_functions, "total_files": len(results)}

_display_quiet_summary 🔗

_display_quiet_summary(error_stats: dict[str, int]) -> None

Summary

Display summary in quiet mode.

Parameters:

Name	Type	Description	Default
`error_stats`	`dict[str, int]`	Dictionary containing total_errors, total_functions, and total_files.	required

Source code in src/docstring_format_checker/cli.py

def _display_quiet_summary(error_stats: dict[str, int]) -> None:
    """
    !!! 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: 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}"))

_display_table_output 🔗

_display_table_output(
    results: dict[str, list[DocstringError]],
) -> None

Summary

Display results in table format.

Parameters:

Name	Type	Description	Default
`results`	`dict[str, list[DocstringError]]`	Dictionary mapping file paths to lists of errors.	required

Source code in src/docstring_format_checker/cli.py

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,
                f"[red]{formatted_error_message}[/red]",
            )
    console.print(table)

_create_error_header 🔗

_create_error_header(error: DocstringError) -> str

Summary

Create formatted header for a single error.

Parameters:

Name	Type	Description	Default
`error`	`DocstringError`	The error to create a header for.	required

Returns:

Type	Description
`str`	Formatted header string with line number, item type, and name.

Source code in src/docstring_format_checker/cli.py

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}':"

_split_error_messages 🔗

_split_error_messages(message: str) -> list[str]

Summary

Split compound error message into individual messages.

Parameters:

Name	Type	Description	Default
`message`	`str`	The error message to split.	required

Returns:

Type	Description
`list[str]`	List of individual error messages.

Source code in src/docstring_format_checker/cli.py

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()]

_format_error_output 🔗

_format_error_output(error: DocstringError) -> list[str]

Summary

Format single error for display output.

Parameters:

Name	Type	Description	Default
`error`	`DocstringError`	The error to format.	required

Returns:

Type	Description
`list[str]`	List of formatted lines to print.

Source code in src/docstring_format_checker/cli.py

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:
        # Escape square brackets for Rich markup using Rich's escape function
        individual_error: str = escape(individual_error)

        # Check if this error has multi-line content (e.g., parameter type mismatches)
        if "\n" in individual_error:
            # Split by newlines and add 4 spaces of extra indentation to each line
            error_lines: list[str] = individual_error.split("\n")
            lines.append(f"    - {error_lines[0]}")  # First line gets the bullet
            for sub_line in error_lines[1:]:
                if sub_line.strip():  # Only add non-empty lines
                    lines.append(f"    {sub_line}")  # Continuation lines get 4 spaces
        else:
            lines.append(f"    - {individual_error}")

    return lines

_display_list_output 🔗

_display_list_output(
    results: dict[str, list[DocstringError]],
) -> None

Summary

Display results in list format.

Parameters:

Name	Type	Description	Default
`results`	`dict[str, list[DocstringError]]`	Dictionary mapping file paths to lists of errors.	required

Source code in src/docstring_format_checker/cli.py

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)

_display_final_summary 🔗

_display_final_summary(error_stats: dict[str, int]) -> None

Summary

Display the final summary line.

Parameters:

Name	Type	Description	Default
`error_stats`	`dict[str, int]`	Dictionary containing total_errors, total_functions, and total_files.	required

Source code in src/docstring_format_checker/cli.py

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}"))

check_docstrings 🔗

check_docstrings(
    paths: list[str],
    config: Optional[str] = None,
    exclude: Optional[list[str]] = None,
    quiet: bool = False,
    output: str = "list",
    check: bool = False,
) -> None

Summary

Core logic for checking docstrings.

Parameters:

Name	Type	Description	Default
`paths`	`list[str]`	The path(s) to the file(s) or directory(ies) to check.	required
`config`	`Optional[str]`	The path to the configuration file. Default: `None`.	`None`
`exclude`	`Optional[list[str]]`	List of glob patterns to exclude from checking. Default: `None`.	`None`
`quiet`	`bool`	Whether to suppress output. Default: `False`.	`False`
`output`	`str`	Output format: 'table' or 'list'. Default: `'list'`.	`'list'`
`check`	`bool`	Whether to throw error if issues are found. Default: `False`.	`False`

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

def check_docstrings(
    paths: list[str],
    config: Optional[str] = None,
    exclude: Optional[list[str]] = None,
    quiet: bool = False,
    output: str = "list",
    check: bool = False,
) -> None:
    """
    !!! note "Summary"
        Core logic for checking docstrings.

    Params:
        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`.
        exclude (Optional[list[str]]):
            List of glob patterns to exclude from checking.
            Default: `None`.
        quiet (bool):
            Whether to suppress 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):
            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)

    # 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)

_validate_and_process_paths 🔗

_validate_and_process_paths(paths: list[str]) -> list[Path]

Summary

Validate input paths and return valid paths.

Parameters:

Name	Type	Description	Default
`paths`	`list[str]`	List of path strings to validate.	required

Raises:

Type	Description
`Exit`	If any paths do not exist.

Returns:

Type	Description
`list[Path]`	List of valid Path objects.

Source code in src/docstring_format_checker/cli.py

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 invalid_paths:
        console.print(
            _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)

    return target_paths

_load_and_validate_config 🔗

_load_and_validate_config(
    config: Optional[str], target_paths: list[Path]
) -> Config

Summary

Load and validate configuration from file or auto-discovery.

Parameters:

Name	Type	Description	Default
`config`	`Optional[str]`	Optional path to configuration file.	required
`target_paths`	`list[Path]`	List of target paths for auto-discovery.	required

Raises:

Type	Description
`Exit`	If configuration loading fails.

Returns:

Type	Description
`Config`	Loaded configuration object.

Source code in src/docstring_format_checker/cli.py

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:
            return _load_explicit_config(config)
        else:
            return _load_auto_discovered_config(target_paths)
    except Exception as e:
        console.print(_red(f"Error loading configuration: {e}"))
        raise Exit(1) from e

_load_explicit_config 🔗

_load_explicit_config(config: str) -> Config

Summary

Load configuration from explicitly specified path.

Parameters:

Name	Type	Description	Default
`config`	`str`	Path to configuration file.	required

Raises:

Type	Description
`Exit`	If configuration file does not exist.

Returns:

Type	Description
`Config`	Loaded configuration object.

Source code in src/docstring_format_checker/cli.py

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)

_load_auto_discovered_config 🔗

_load_auto_discovered_config(
    target_paths: list[Path],
) -> Config

Summary

Load configuration from auto-discovery or defaults.

Parameters:

Name	Type	Description	Default
`target_paths`	`list[Path]`	List of target paths to search for configuration.	required

Returns:

Type	Description
`Config`	Loaded configuration object from found config or defaults.

Source code in src/docstring_format_checker/cli.py

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()

_process_all_paths 🔗

_process_all_paths(
    checker: DocstringChecker,
    target_paths: list[Path],
    exclude: Optional[list[str]],
) -> dict[str, list[DocstringError]]

Summary

Process all target paths and collect docstring errors.

Parameters:

Name	Type	Description	Default
`checker`	`DocstringChecker`	The checker instance to use.	required
`target_paths`	`list[Path]`	List of paths to check (files or directories).	required
`exclude`	`Optional[list[str]]`	Optional list of exclusion patterns.	required

Raises:

Type	Description
`Exit`	If an error occurs during checking.

Returns:

Type	Description
`dict[str, list[DocstringError]]`	Dictionary mapping file paths to lists of errors.

Source code in src/docstring_format_checker/cli.py

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:
        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) from e

    return all_results

main 🔗

main(
    ctx: Context,
    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,
        "--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",
        "-v",
        callback=_version_callback,
        is_eager=True,
        help="Show version and exit",
    ),
    help_flag: Optional[bool] = Option(
        None,
        "--help",
        "-h",
        callback=_help_callback_main,
        is_eager=True,
        help="Show this message and exit",
    ),
) -> None

Summary

Check Python docstring formatting and completeness.

Details

This tool analyzes Python files and validates that functions, methods, and classes have properly formatted docstrings according to the configured sections.

Parameters:

Name	Type	Description	Default
`ctx`	`Context`	The context object for the command.	required
`paths`	`Optional[list[str]]`	Path(s) to Python file(s) or directory(ies) to check.	`Argument(None, help='Path(s) to Python file(s) or directory(s) for DFC to check')`
`config`	`Optional[str]`	Path to configuration file (TOML format).	`Option(None, '--config', '-f', help='Path to configuration file (TOML format)')`
`exclude`	`Optional[list[str]]`	Glob patterns to exclude.	`Option(None, '--exclude', '-x', help='Glob patterns to exclude (can be used multiple times)')`
`output`	`str`	Output format: 'table' or 'list'.	`Option('list', '--output', '-o', help="Output format: 'table' or 'list'", show_default=True)`
`check`	`bool`	Throw error if any issues are found.	`Option(False, '--check', '-c', help='Throw error (exit 1) if any issues are found')`
`quiet`	`bool`	Only output pass/fail confirmation.	`Option(False, '--quiet', '-q', help='Only output pass/fail confirmation, suppress errors unless failing')`
`example`	`Optional[str]`	Show examples: 'config' or 'usage'.	`Option(None, '--example', '-e', callback=_example_callback, is_eager=True, help="Show examples: 'config' for configuration example, 'usage' for usage examples")`
`version`	`Optional[bool]`	Show version and exit.	`Option(None, '--version', '-v', callback=_version_callback, is_eager=True, help='Show version and exit')`
`help_flag`	`Optional[bool]`	Show help message and exit.	`Option(None, '--help', '-h', callback=_help_callback_main, is_eager=True, help='Show this message and exit')`

Returns:

Type	Description
`None`	Nothing is returned.

Source code in src/docstring_format_checker/cli.py

@app.callback(invoke_without_command=True)
def main(
    ctx: Context,
    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,
        "--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",
        "-v",
        callback=_version_callback,
        is_eager=True,
        help="Show version and exit",
    ),
    help_flag: Optional[bool] = Option(
        None,
        "--help",
        "-h",
        callback=_help_callback_main,
        is_eager=True,
        help="Show this message and exit",
    ),
) -> None:
    """
    !!! note "Summary"
        Check Python docstring formatting and completeness.

    ???+ abstract "Details"
        This tool analyzes Python files and validates that functions, methods, and classes have properly formatted docstrings according to the configured sections.

    Params:
        ctx (Context):
            The context object for the command.
        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]]):
            Glob patterns to exclude.
        output (str):
            Output format: 'table' or 'list'.
        check (bool):
            Throw error if any issues are found.
        quiet (bool):
            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.

    Returns:
        (None):
            Nothing is returned.
    """

    # If no paths are provided, show help
    if not paths:
        echo(ctx.get_help())
        raise Exit(0)

    # 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)

    check_docstrings(
        paths=paths,
        config=config,
        exclude=exclude,
        quiet=quiet,
        output=output,
        check=check,
    )

entry_point 🔗

entry_point() -> None

Summary

Entry point for the CLI scripts defined in pyproject.toml.

Source code in src/docstring_format_checker/cli.py

def entry_point() -> None:
    """
    !!! note "Summary"
        Entry point for the CLI scripts defined in pyproject.toml.
    """
    app()

CLI

docstring_format_checker.cli 🔗

NEW_LINE module-attribute 🔗

_colour 🔗

_green module-attribute 🔗

_red module-attribute 🔗

_cyan module-attribute 🔗

_blue module-attribute 🔗

app module-attribute 🔗

console module-attribute 🔗

_version_callback 🔗

_example_callback 🔗

_show_usage_examples_callback 🔗

_show_config_example_callback 🔗

_help_callback_main 🔗

_format_error_messages 🔗

_display_results 🔗

_count_errors_and_files 🔗

_display_quiet_summary 🔗

_display_table_output 🔗

_create_error_header 🔗

_split_error_messages 🔗

_format_error_output 🔗

_display_list_output 🔗

_display_final_summary 🔗

check_docstrings 🔗

_validate_and_process_paths 🔗

_load_and_validate_config 🔗

_load_explicit_config 🔗

_load_auto_discovered_config 🔗

_process_all_paths 🔗

main 🔗

entry_point 🔗

NEW_LINE `module-attribute` 🔗

_green `module-attribute` 🔗

_red `module-attribute` 🔗

_cyan `module-attribute` 🔗

_blue `module-attribute` 🔗

app `module-attribute` 🔗

console `module-attribute` 🔗