Reporters API Reference

Overview

Reporters in tfsumpy are responsible for formatting and displaying the results of plan analysis. Each reporter implements a specific output format (e.g., CLI, Markdown, JSON). The primary built-in reporter is the PlanReporter, which provides multiple output formats for Terraform plan summaries.

Base Reporter Interface

All reporters must implement the ReporterInterface:

from abc import ABC, abstractmethod

class ReporterInterface(ABC):
    @property
    @abstractmethod
    def category(self) -> str:
        """Return the reporter category (e.g., 'plan')."""
        pass

    @abstractmethod
    def print_report(self, data: Any, **kwargs) -> None:
        """
        Format and print the analysis results.

        Args:
            data: The analysis results (typically a dict)
            **kwargs: Additional display options (e.g., show_changes, show_details)
        """
        pass

PlanReporter

The PlanReporter is the default reporter for plan summaries. It supports three output formats: - Console output (default) - Markdown output (template-based) - JSON output (structured)

Example usage:

from tfsumpy.plan.reporter import PlanReporter

reporter = PlanReporter()

# Console output
reporter.print_report(plan_results, show_changes=True)

# Markdown output
reporter.print_report_markdown(plan_results, show_changes=True)

# JSON output
reporter.print_report_json(plan_results, show_changes=True)

Parameters: - data: The analysis results (from PlanAnalyzer) - show_changes: Show detailed attribute changes (bool) - show_details: Show full resource details (bool)

Output Formats:

1. Console Output:
2. Color-coded text
3. Human-readable format

4. Interactive terminal display

5. Markdown Output:

6. Template-based formatting
7. Summary statistics
8. Resource changes
9. Detailed information (if enabled)

10. Timestamp and metadata

11. JSON Output:

12. Structured data format
13. Metadata (timestamp, version)
14. Summary statistics
15. Resource changes
16. Detailed information (if enabled)
17. Analysis results (if available)

Extending: Custom Reporters

You can create your own reporter by subclassing ReporterInterface (optionally inheriting from BaseReporter for convenience):

from tfsumpy.reporter import ReporterInterface
from tfsumpy.reporters.base_reporter import BaseReporter

class MyCustomReporter(BaseReporter, ReporterInterface):
    @property
    def category(self) -> str:
        return "custom"

    def print_report(self, data: Any, **kwargs) -> None:
        # Custom formatting logic here
        self._write("My Custom Report\n")
        self._write("=================\n")
        # ...

Register your custom reporter with the tfsumpy Context to use it in your workflow.

Notes

• The PlanReporter supports three output formats: console, markdown, and JSON.
• You can direct output to a file or stream by passing a custom output to BaseReporter.
• Markdown output uses Jinja2 templates for consistent formatting.
• JSON output provides a structured format suitable for integration with other tools.
• See the Models API for details on the data structures passed to reporters.