CLI

docstring_format_checker.cli

Summary

Command-line interface for the docstring format checker.

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)

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