CLI

docstring_format_checker.cli

Summary

Command-line interface for the docstring format checker.

main

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

check

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

Summary

Check docstrings in Python files.

Details

This command checks the docstrings in the specified Python file or directory.

Parameters:

Name	Type	Description	Default
path	str	The path to the Python file or directory to check.	Argument(..., help='Path to Python file or directory to check')
config	Optional[str]	The path to the configuration file (TOML format).	Option(None, '--config', '-c', help='Path to configuration file (TOML format)')
recursive	bool	Whether to check directories recursively.	Option('true', '--recursive', '-r', help='Check directories recursively (default: true). Accepts: true/false, t/f, yes/no, y/n, 1/0, on/off')
exclude	list[str]	Glob patterns to exclude (can be used multiple times).	Option(None, '--exclude', '-x', help='Glob patterns to exclude (can be used multiple times)')
quiet	bool	Whether to only show errors, no success messages.	Option(False, '--quiet', '-q', help='Only show errors, no success messages')
verbose	bool	Whether to show detailed output.	Option(False, '--verbose', '-n', help='Show detailed output')
examples	Optional[bool]	Show usage examples and exit.	Option(None, '--examples', '-e', callback=_show_check_examples_callback, is_eager=True, help='Show usage examples and exit')
help_flag	Optional[bool]	Show help message and exit.	Option(None, '--help', '-h', callback=_help_callback, 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.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.
        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).
        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)

config_example

config_example(
    help_flag: Optional[bool] = Option(
        None,
        "--help",
        "-h",
        callback=_help_callback,
        is_eager=True,
        help="Show this message and exit",
    )
) -> None

Summary

Show example configuration file.

Parameters:

Name	Type	Description	Default
help_flag	Optional[bool]	Show help message and exit.	Option(None, '--help', '-h', callback=_help_callback, 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.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:
        help_flag (Optional[bool]):
            Show help message and exit.

    Returns:
        (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

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

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