Automation Report
=================

Using the :class:`~.ReportBuilder`, you can create a HTML report that can be sent via email or saved as a standalone documentation file.
It helps you to document the outcome of the automation process and provides a way to share the results with others.
It allows you to organize messages into sections and categorize them by status (success, warning, error, etc.).


Migration Guide
---------------
Since the version ``3.30.0``, the report builder is the recommended way to create and send reports.
The :class:`~.EmailNotifier` is deprecated and will be removed in future version.

For creating the report builder, preferably use the :meth:`~.BaseScenario.report_builder` method, located in the :class:`~.BaseScenario` class.
See the example below for the differences between the old and new approach.

.. code-block:: python

    import aiviro

    class NewReportScenario(aiviro.BaseScenario):
        def __init__(self, config: "YAMLConfig"):
            super().__init__(config)
            self.report = self.report_builder()

        def _run(self):
            try:
                # Your automation logic here
                self.report.successful("Task completed successfully")
            except Exception as e:
                self.report.error(f"Task failed: {str(e)}")

        def section_example(self):
            """Example of creating a new section and adding messages to it."""
            with self.report.create_section("Section Title", "Sub-title") as section:
                section.successful("Task completed successfully")

        def last_section_example(self):
            """Example of adding messages to the last created section."""
            with self.report.last_section as section:
                section.successful("Task completed successfully")

        def message_styling_example(self):
            """Example of using Markdown in the messages."""
            self.report.successful("Task completed successfully with **bold** and *italic* text")
            self.report.warning("Task completed with warning, check [link](https://example.com) for more details")

        def _after_run(self):
            """Example of sending the report via email client."""
            self.send_report_via_email_client(self.config.recipients)


.. code-block:: python

    import aiviro
    from aiviro.modules.notifier import Style, Item

    class DeprecatedNotifierScenario(aiviro.BaseScenario):
        def __init__(self, config: "YAMLConfig"):
            super().__init__(config)
            self.email_notifier = self.email_notifier()

        def _run(self):
            try:
                # Your automation logic here
                self.email_notifier.successful("Task completed successfully")
            except Exception as e:
                self.email_notifier.error(f"Task failed: {str(e)}")

        def block_example(self):
            """Example of creating a new block and adding messages to it."""
            notification_block = self.email_notifier.create_block("Block Title")
            notification_block.successful("Task completed successfully")

        def message_styling_example(self):
            """Example of using Style object to format the messages."""
            self.email_notifier.default_block.item_style = Style(bold=True)
            self.email_notifier.successful(Item("Task", "completed successfully"))

        def last_block_example(self):
            """Example of adding messages to the last created block."""
            self.email_notifier.last_block.successful("Task completed successfully")

        def _after_run(self):
            """Example of sending the report via email client."""
            if self.email_notifier.blocks:
                self.email_notifier.send_report(self.config.recipients)


Report Builder
--------------

.. automodule:: aiviro.core.services.report_service
    :members: ReportBuilder, ReportSectionManager, ReportSection, LogStatus, LogEntry, PerformanceMetrics, PerformanceSubMetric

.. autoclass:: aiviro.core.utils.metrics.constants.MetricsNames
    :members: