Config Reports

api

Public API for generating configuration reports.

generate_config_report

generate_config_report(
    config: object,
    format: ConfigReportFormat | str = "markdown",
    output: str | PathLike[str] | None = None,
    *,
    entrypoint: str | None = None,
    verbosity: ConfigReportVerbosity = "default",
) -> str

Collect and render one nested configuration report.

PARAMETER	DESCRIPTION
config	Root config object or config bundle to collect. TYPE: object
format	Output format name or enum accepted by the renderer registry. TYPE: ConfigReportFormat | str DEFAULT: 'markdown'
output	Optional filesystem path where the rendered report should also be written. TYPE: str | PathLike[str] | None DEFAULT: None
entrypoint	Optional source label to record in the report header. TYPE: str | None DEFAULT: None
verbosity	Visibility level used to filter the collected document before rendering. TYPE: ConfigReportVerbosity DEFAULT: 'default'

RETURNS	DESCRIPTION
str	The rendered config report as a string, even when output is supplied.

RAISES	DESCRIPTION
KeyError	If no renderer is registered for the requested format.
OSError	If output is supplied and the rendered report cannot be written to disk.

Source code in themis/config_report/api.py

def generate_config_report(
    config: object,
    format: ConfigReportFormat | str = "markdown",
    output: str | PathLike[str] | None = None,
    *,
    entrypoint: str | None = None,
    verbosity: ConfigReportVerbosity = "default",
) -> str:
    """Collect and render one nested configuration report.

    Args:
        config: Root config object or config bundle to collect.
        format: Output format name or enum accepted by the renderer registry.
        output: Optional filesystem path where the rendered report should also be
            written.
        entrypoint: Optional source label to record in the report header.
        verbosity: Visibility level used to filter the collected document before
            rendering.

    Returns:
        The rendered config report as a string, even when `output` is supplied.

    Raises:
        KeyError: If no renderer is registered for the requested format.
        OSError: If `output` is supplied and the rendered report cannot be
            written to disk.
    """

    document = build_config_report_document(config, entrypoint=entrypoint)
    rendered = render_config_report(document, format=format, verbosity=verbosity)
    if output is not None:
        Path(output).write_text(rendered, encoding="utf-8")
    return rendered

render_config_report

render_config_report(
    document: ConfigReportDocument,
    *,
    format: ConfigReportFormat | str = "markdown",
    verbosity: ConfigReportVerbosity = "default",
) -> str

Render one config report document into the requested format.

PARAMETER	DESCRIPTION
document	The collected config-report document to render. TYPE: ConfigReportDocument
format	Output format name or enum accepted by the renderer registry. TYPE: ConfigReportFormat | str DEFAULT: 'markdown'
verbosity	Visibility level used to filter the collected document before rendering. TYPE: ConfigReportVerbosity DEFAULT: 'default'

RETURNS	DESCRIPTION
str	The rendered config report as a string.

RAISES	DESCRIPTION
KeyError	If no renderer is registered for the requested format.

Source code in themis/config_report/api.py

def render_config_report(
    document: ConfigReportDocument,
    *,
    format: ConfigReportFormat | str = "markdown",
    verbosity: ConfigReportVerbosity = "default",
) -> str:
    """Render one config report document into the requested format.

    Args:
        document: The collected config-report document to render.
        format: Output format name or enum accepted by the renderer registry.
        verbosity: Visibility level used to filter the collected document before
            rendering.

    Returns:
        The rendered config report as a string.

    Raises:
        KeyError: If no renderer is registered for the requested format.
    """

    renderer = get_config_report_renderer(format)
    return renderer.render(apply_verbosity(document, verbosity=verbosity))