CLI

docstring_format_checker.cli

Summary

Command-line interface for the docstring format checker.

check_docstrings

check_docstrings(
    path: 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
path	str	The path to the file or directory 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(
    path: 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:
        path (str):
            The path to the file or directory 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.
    """

    target_path = Path(path)

    # Validate target path
    if not target_path.exists():
        console.print(_red(f"Error: Path does not exist: '{path}'"))
        raise Exit(1)

    # Load configuration
    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)
        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)
            if found_config:
                config_obj: Config = load_config(found_config)
            else:
                config_obj: Config = load_config()

    except Exception as e:
        console.print(_red(f"Error loading configuration: {e}"))
        raise Exit(1)

    # Initialize checker
    checker = DocstringChecker(config_obj)

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

    # Always exit with error code if issues are found, regardless of check flag
    if exit_code != 0:
        raise Exit(exit_code)

main

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",
        "-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
path	Optional[str]	Path to Python file or directory to check.	Argument(None, help='Path to Python file or directory 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,
    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",
        "-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.
        path (Optional[str]):
            Path to Python file or directory 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 path is provided, show help
    if path is None:
        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(
        path=path,
        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()