robo-email 0.1.1__tar.gz

robo_email-0.1.1/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: robo-email
+Version: 0.1.1
+Summary: Reusable HTML email report rendering and local delivery utilities
+Requires-Python: >=3.12,<3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: matplotlib (==3.11.2)

robo_email-0.1.1/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "robo-email"
+version = "0.1.1"
+description = "Reusable HTML email report rendering and local delivery utilities"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "matplotlib==3.11.2",
+]
+
+[tool.poetry]
+packages = [{ include = "robo_email" }]
+exclude = ["tools/**"]
+
+[build-system]
+requires = ["poetry-core==2.5.0"]
+build-backend = "poetry.core.masonry.api"

robo_email-0.1.1/robo_email/__init__.py

@@ -0,0 +1,6 @@
+"""Reusable email report rendering and delivery utilities."""
+
+from .delivery import is_valid_email, send_powershell_email
+from .renderer import EmailReportGenerator
+
+__all__ = ["EmailReportGenerator", "is_valid_email", "send_powershell_email"]

robo_email-0.1.1/robo_email/delivery.py

@@ -0,0 +1,183 @@
+"""Generic local Windows email delivery helpers."""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import subprocess
+import threading
+from pathlib import Path
+from typing import Iterable, Optional
+
+logger = logging.getLogger(__name__)
+
+_email_sent = False
+_email_sent_lock = threading.Lock()
+_EMAIL_RE = re.compile(r"^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$")
+
+
+def is_valid_email(address: str) -> bool:
+    """Return whether an address matches the permitted email format."""
+    return bool(_EMAIL_RE.match((address or "").strip()))
+
+
+def _ps_escape(value: Optional[str]) -> str:
+    return (value or "").replace("'", "''")
+
+
+def send_powershell_email(
+    *,
+    body_path: str | Path,
+    recipients: Iterable[str],
+    subject: str,
+    smtp_server: str = "localhost",
+    smtp_port: int = 25,
+    smtp_from: str = "",
+    attachment_path: str | Path | None = None,
+    suppress_duplicates: bool = True,
+) -> bool:
+    """Send an HTML email through PowerShell ``Send-MailMessage`` on Windows.
+
+    Application code supplies recipients, subject, SMTP configuration and any
+    attachment. This function has no knowledge of application environment,
+    credentials, spreadsheets, pytest, Jenkins, or business data.
+    """
+    if os.name != "nt":
+        logger.warning("PowerShell email delivery is supported only on Windows.")
+        return False
+
+    body_path = Path(body_path).resolve()
+    if not body_path.is_file():
+        raise FileNotFoundError(f"Email body does not exist: {body_path}")
+
+    valid_recipients = sorted(
+        {str(value).strip() for value in recipients if is_valid_email(str(value))}
+    )
+    if not valid_recipients:
+        logger.warning("Email send skipped because no valid recipients were supplied.")
+        return False
+
+    global _email_sent
+    if suppress_duplicates:
+        with _email_sent_lock:
+            if _email_sent:
+                logger.info("Email already sent for this process; skipping duplicate send.")
+                return False
+            _email_sent = True
+
+    try:
+        to_list = ";".join(valid_recipients)
+        safe_body_path = _ps_escape(str(body_path))
+        has_attachment = attachment_path is not None
+        safe_attachment_path = (
+            _ps_escape(str(Path(attachment_path).resolve())) if has_attachment else ""
+        )
+
+        ps_script = f"""
+$ErrorActionPreference = 'Stop'
+$bodyPath = '{safe_body_path}'
+$attachmentPath = '{safe_attachment_path}'
+$bodyHtml = Get-Content -Path $bodyPath -Raw -Encoding UTF8
+$configuredFrom = '{_ps_escape(smtp_from)}'
+$authUpn = (whoami /upn 2>$null | Select-Object -Last 1)
+function Resolve-AdMailboxSmtp([string]$upn) {{
+    try {{
+        if ([string]::IsNullOrWhiteSpace($upn) -or -not $upn.Contains('@')) {{ return $null }}
+        $sam = $upn.Split('@')[0]
+        if ([string]::IsNullOrWhiteSpace($sam)) {{ return $null }}
+        $root = [ADSI]"LDAP://RootDSE"
+        $searchBase = "LDAP://" + $root.defaultNamingContext
+        $searcher = New-Object System.DirectoryServices.DirectorySearcher([ADSI]$searchBase)
+        $searcher.Filter = "(&(objectCategory=person)(objectClass=user)(sAMAccountName=$sam))"
+        $null = $searcher.PropertiesToLoad.Add("mail")
+        $null = $searcher.PropertiesToLoad.Add("proxyAddresses")
+        $searcher.SizeLimit = 1
+        $result = $searcher.FindOne()
+        if ($null -eq $result) {{ return $null }}
+        $props = $result.Properties
+        if ($props.Contains("proxyaddresses")) {{
+            foreach ($addr in $props["proxyaddresses"]) {{
+                if ($addr -is [string] -and $addr.StartsWith("SMTP:")) {{
+                    return $addr.Substring(5).Trim().ToLowerInvariant()
+                }}
+            }}
+        }}
+        if ($props.Contains("mail") -and $props["mail"].Count -gt 0) {{
+            $mail = [string]$props["mail"][0]
+            if (-not [string]::IsNullOrWhiteSpace($mail) -and $mail.Contains('@')) {{
+                return $mail.Trim().ToLowerInvariant()
+            }}
+        }}
+    }} catch {{}}
+    return $null
+}}
+$resolvedMailboxFromAd = $null
+$smtpFrom = $configuredFrom
+if (-not [string]::IsNullOrWhiteSpace($authUpn)) {{
+    $authUpn = $authUpn.Trim().ToLowerInvariant()
+    if ($authUpn.Contains('@')) {{
+        $resolvedMailboxFromAd = Resolve-AdMailboxSmtp $authUpn
+        if (-not [string]::IsNullOrWhiteSpace($resolvedMailboxFromAd)) {{ $smtpFrom = $resolvedMailboxFromAd }}
+        else {{ $smtpFrom = $authUpn }}
+    }}
+}}
+$toRecipients = '{_ps_escape(to_list)}'.Split(';') | Where-Object {{ -not [string]::IsNullOrWhiteSpace($_) }} | ForEach-Object {{ $_.Trim() }}
+$attachmentExists = {'$true' if has_attachment else '$false'}
+$fromCandidates = New-Object System.Collections.Generic.List[string]
+function Add-FromCandidate([string]$value) {{
+    if ([string]::IsNullOrWhiteSpace($value)) {{ return }}
+    $candidate = $value.Trim().ToLowerInvariant()
+    if (-not $candidate.Contains('@')) {{ return }}
+    if (-not $fromCandidates.Contains($candidate)) {{ $fromCandidates.Add($candidate) }}
+}}
+Add-FromCandidate $smtpFrom
+Add-FromCandidate $configuredFrom
+Add-FromCandidate $resolvedMailboxFromAd
+if ($toRecipients.Count -gt 0) {{ Add-FromCandidate $toRecipients[0] }}
+$sendSucceeded = $false
+$lastSendError = $null
+foreach ($candidateFrom in $fromCandidates) {{
+    try {{
+        if ($attachmentExists) {{
+            Send-MailMessage -From $candidateFrom -To $toRecipients -Subject '{_ps_escape(subject)}' -Body $bodyHtml -BodyAsHtml -SmtpServer '{_ps_escape(smtp_server)}' -Port {int(smtp_port)} -Attachments $attachmentPath
+        }} else {{
+            Send-MailMessage -From $candidateFrom -To $toRecipients -Subject '{_ps_escape(subject)}' -Body $bodyHtml -BodyAsHtml -SmtpServer '{_ps_escape(smtp_server)}' -Port {int(smtp_port)}
+        }}
+        $sendSucceeded = $true
+        break
+    }} catch {{ $lastSendError = $_.Exception.Message }}
+}}
+if (-not $sendSucceeded) {{ throw "All sender candidates failed. Last error: $lastSendError" }}
+"""
+        completed = subprocess.run(
+            [
+                "powershell",
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-Command",
+                ps_script,
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if completed.returncode != 0:
+            logger.error(
+                "PowerShell email delivery failed (exit=%s): %s",
+                completed.returncode,
+                (completed.stderr or completed.stdout or "").strip(),
+            )
+            if suppress_duplicates:
+                with _email_sent_lock:
+                    _email_sent = False
+            return False
+
+        logger.info("Email sent successfully to %s", ", ".join(valid_recipients))
+        return True
+    except Exception:
+        if suppress_duplicates:
+            with _email_sent_lock:
+                _email_sent = False
+        raise

robo_email-0.1.1/robo_email/renderer.py

@@ -0,0 +1,430 @@
+"""Render Outlook-compatible HTML email reports with embedded charts.
+
+The application owns its canonical report data and HTML template.
+"""
+
+import base64
+import html
+import json
+import logging
+from io import BytesIO
+from pathlib import Path
+
+# Use a non-interactive backend for matplotlib
+try:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    from matplotlib import ticker
+except Exception as exc:
+    logging.getLogger(__name__).warning(
+        "Matplotlib is unavailable for email charts: %s", exc
+    )
+    plt = None
+
+
+logger = logging.getLogger(__name__)
+
+
+class EmailReportGenerator:
+    """
+    A utility class to generate an Outlook-compatible HTML email report from test data,
+    rendering charts as embedded Base64 images.
+    """
+
+    @staticmethod
+    def _create_chart_image(plot_function, data, title, **kwargs):
+        """Render chart data as a Base64-encoded PNG data URI."""
+        if not plt:
+            return ""
+        try:
+            fig, ax = plt.subplots(figsize=(6, 4))
+            plot_function(fig, ax, data, title, **kwargs)  # Pass fig to plot function
+            buf = BytesIO()
+            fig.savefig(buf, format="png", bbox_inches="tight", pad_inches=0.1)
+            plt.close(fig)
+            buf.seek(0)
+            image_base64 = base64.b64encode(buf.read()).decode("utf-8")
+            return f"data:image/png;base64,{image_base64}"
+        except Exception as exc:
+            logger.warning("Failed to render chart '%s': %s", title, exc)
+            return ""
+
+    @staticmethod
+    def _plot_test_summary_donut(fig, ax, data, title, **kwargs):
+        """Plots the overall test summary as a donut chart with color-coded center text."""
+        status_order = ["Passed", "Failed", "Skipped"]
+        sizes = []
+        for status in status_order:
+            value = data.get(status, 0)
+            try:
+                numeric_value = int(value)
+            except (TypeError, ValueError):
+                numeric_value = 0
+            sizes.append(max(numeric_value, 0))
+
+        # Matplotlib pie raises when all values are zero/invalid.
+        if sum(sizes) == 0:
+            ax.axis("off")
+            fig.text(0.5, 0.95, title, ha="center", va="top", fontsize=12)
+            ax.text(
+                0.5,
+                0.5,
+                "No test results available",
+                ha="center",
+                va="center",
+                fontsize=11,
+                color="#666666",
+                transform=ax.transAxes,
+            )
+            return
+
+        colors = {"Passed": "#66BB6A", "Failed": "#EF5350", "Skipped": "#FFA726"}
+
+        ax.pie(
+            sizes,
+            colors=[colors[status] for status in status_order],
+            startangle=90,
+            wedgeprops=dict(width=0.4),
+        )
+        centre_circle = plt.Circle((0, 0), 0.60, fc="white")
+        ax.add_artist(centre_circle)
+
+        y_pos = 0.2
+        ax.text(
+            0,
+            y_pos,
+            f"Passed: {data.get('Passed', 0)}",
+            ha="center",
+            va="center",
+            fontsize=10,
+            color=colors["Passed"],
+            weight="bold",
+        )
+        ax.text(
+            0,
+            0,
+            f"Failed: {data.get('Failed', 0)}",
+            ha="center",
+            va="center",
+            fontsize=10,
+            color=colors["Failed"],
+            weight="bold",
+        )
+        ax.text(
+            0,
+            -y_pos,
+            f"Skipped: {data.get('Skipped', 0)}",
+            ha="center",
+            va="center",
+            fontsize=10,
+            color=colors["Skipped"],
+            weight="bold",
+        )
+
+        ax.axis("equal")
+        fig.text(0.5, 0.95, title, ha="center", va="top", fontsize=12)
+
+    @staticmethod
+    def _plot_stacked_bar(fig, ax, data, title, is_horizontal=True, **kwargs):
+        """Plot passed, failed, and skipped totals as a stacked bar chart."""
+        labels = list(data.keys())
+        passed = [v.get("passed", 0) for v in data.values()]
+        failed = [v.get("failed", 0) for v in data.values()]
+        skipped = [v.get("skipped", 0) for v in data.values()]
+
+        bar_thickness = 0.5
+        colors = ["#66BB6A", "#EF5350", "#FFA726"]
+
+        if is_horizontal:
+            y_pos = range(len(labels))
+            p_bars = ax.barh(
+                y_pos, passed, height=bar_thickness, color=colors[0], label="Passed"
+            )
+            f_bars = ax.barh(
+                y_pos,
+                failed,
+                height=bar_thickness,
+                left=passed,
+                color=colors[1],
+                label="Failed",
+            )
+            s_bars = ax.barh(
+                y_pos,
+                skipped,
+                height=bar_thickness,
+                left=[p + f for p, f in zip(passed, failed)],
+                color=colors[2],
+                label="Skipped",
+            )
+            ax.set_yticks(y_pos)
+            ax.set_yticklabels(labels)
+            ax.invert_yaxis()
+            ax.set_xlabel("Number of Tests")
+            ax.xaxis.set_major_locator(ticker.MaxNLocator(integer=True))
+        else:
+            x_pos = range(len(labels))
+            p_bars = ax.bar(
+                x_pos, passed, width=bar_thickness, color=colors[0], label="Passed"
+            )
+            f_bars = ax.bar(
+                x_pos,
+                failed,
+                width=bar_thickness,
+                bottom=passed,
+                color=colors[1],
+                label="Failed",
+            )
+            s_bars = ax.bar(
+                x_pos,
+                skipped,
+                width=bar_thickness,
+                bottom=[p + f for p, f in zip(passed, failed)],
+                color=colors[2],
+                label="Skipped",
+            )
+            ax.set_xticks(x_pos)
+            ax.set_xticklabels(labels)
+            ax.set_ylabel("Number of Tests")
+            ax.yaxis.set_major_locator(ticker.MaxNLocator(integer=True))
+
+        fig.text(0.5, 0.95, title, ha="center", va="top", fontsize=12)
+        fig.legend(loc="upper center", bbox_to_anchor=(0.5, 0.9), ncol=3, frameon=False)
+        fig.subplots_adjust(top=0.8)
+
+        for i, (p, f, s) in enumerate(zip(passed, failed, skipped)):
+            if is_horizontal:
+                if p > 0:
+                    ax.text(
+                        p / 2,
+                        i,
+                        str(p),
+                        ha="center",
+                        va="center",
+                        color="white",
+                        fontsize=8,
+                    )
+                if f > 0:
+                    ax.text(
+                        p + f / 2,
+                        i,
+                        str(f),
+                        ha="center",
+                        va="center",
+                        color="white",
+                        fontsize=8,
+                    )
+                if s > 0:
+                    ax.text(
+                        p + f + s / 2,
+                        i,
+                        str(s),
+                        ha="center",
+                        va="center",
+                        color="white",
+                        fontsize=8,
+                    )
+            else:
+                if p > 0:
+                    ax.text(
+                        i,
+                        p / 2,
+                        str(p),
+                        ha="center",
+                        va="center",
+                        color="white",
+                        fontsize=8,
+                    )
+                if f > 0:
+                    ax.text(
+                        i,
+                        p + f / 2,
+                        str(f),
+                        ha="center",
+                        va="center",
+                        color="white",
+                        fontsize=8,
+                    )
+                if s > 0:
+                    ax.text(
+                        i,
+                        p + f + s / 2,
+                        str(s),
+                        ha="center",
+                        va="center",
+                        color="white",
+                        fontsize=8,
+                    )
+
+
+    DEFAULT_PLACEHOLDERS = {
+        "title": "__ROBO_EMAIL_TITLE__",
+        "summary_chart": "__ROBO_EMAIL_SUMMARY_CHART_CELL__",
+        "chart_1": "__ROBO_EMAIL_CHART_1_CELL__",
+        "chart_2": "__ROBO_EMAIL_CHART_2_CELL__",
+        "chart_3": "__ROBO_EMAIL_CHART_3_CELL__",
+        "report_link": "__ROBO_EMAIL_REPORT_LINK__",
+        "created_on": "__ROBO_EMAIL_CREATED_ON__",
+    }
+
+    DEFAULT_CHART_SPECS = (
+        ("chart_1", "group_1_status", "Status by Group 1", True),
+        ("chart_2", "group_2_status", "Status by Group 2", False),
+        ("chart_3", "group_3_status", "Status by Group 3", True),
+    )
+
+    @classmethod
+    def _load_template(cls, template_path: Path, placeholders) -> str:
+        """Load and validate the caller-supplied Outlook-compatible template."""
+        template_path = Path(template_path)
+        template = template_path.read_text(encoding="utf-8")
+        missing = [
+            placeholder
+            for placeholder in placeholders.values()
+            if placeholder not in template
+        ]
+        if missing:
+            raise ValueError(
+                f"Email template {template_path} is missing required "
+                f"placeholder(s): {', '.join(missing)}"
+            )
+        return template
+
+    @staticmethod
+    def _chart_cell(img_src: str, alt_text: str) -> str:
+        """Return an Outlook-safe chart cell or a plain fallback cell."""
+        safe_alt = html.escape(alt_text, quote=True)
+        if img_src:
+            safe_src = html.escape(img_src, quote=True)
+            return (
+                '<td align="center" style="padding: 10px; width: 50%;">'
+                f'<img src="{safe_src}" alt="{safe_alt}" '
+                'style="max-width: 380px; height: auto;" />'
+                "</td>"
+            )
+        return (
+            '<td align="center" style="padding: 10px; width: 50%;">'
+            f"{safe_alt} chart not available"
+            "</td>"
+        )
+
+    @classmethod
+    def generate_email_content(
+        cls,
+        data,
+        *,
+        template_path: Path,
+        placeholders=None,
+        chart_specs=None,
+    ):
+        """Render an Outlook-compatible email body from canonical report data.
+
+        Applications provide their own template and can map any three grouped
+        status charts into the reusable chart slots.
+        """
+        placeholders = dict(placeholders or cls.DEFAULT_PLACEHOLDERS)
+        chart_specs = tuple(chart_specs or cls.DEFAULT_CHART_SPECS)
+        chart_data = data.get("chart_data") or {}
+        summary_data = chart_data.get(
+            "test_status_summary", {"Passed": 0, "Failed": 0, "Skipped": 0}
+        )
+
+        summary_chart_img = cls._create_chart_image(
+            cls._plot_test_summary_donut, summary_data, "Test Summary"
+        )
+
+        chart_cells = {}
+        for slot, data_key, title, is_horizontal in chart_specs:
+            image = cls._create_chart_image(
+                cls._plot_stacked_bar,
+                chart_data.get(data_key, {}),
+                title,
+                is_horizontal=is_horizontal,
+            )
+            chart_cells[slot] = cls._chart_cell(image, title)
+
+        title = html.escape(str(data.get("title", "Test Report")), quote=True)
+        report_link = html.escape(str(data.get("report_link", "#")), quote=True)
+        created_on = html.escape(
+            str(data.get("summary", {}).get("Report Created On", "N/A")),
+            quote=True,
+        )
+
+        replacements = {
+            placeholders["title"]: title,
+            placeholders["summary_chart"]: cls._chart_cell(
+                summary_chart_img, "Test Summary"
+            ),
+            placeholders["report_link"]: report_link,
+            placeholders["created_on"]: created_on,
+        }
+        for slot, _, _, _ in chart_specs:
+            replacements[placeholders[slot]] = chart_cells[slot]
+
+        rendered = cls._load_template(template_path, placeholders)
+        for placeholder, value in replacements.items():
+            rendered = rendered.replace(placeholder, value)
+        return rendered
+
+    @classmethod
+    def generate_from_json(
+        cls,
+        json_path: Path,
+        *,
+        template_path: Path,
+        placeholders=None,
+        chart_specs=None,
+    ) -> str:
+        """Render the email body from a persisted canonical JSON report."""
+        data = json.loads(Path(json_path).read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise ValueError(f"Report JSON must contain an object: {json_path}")
+        return cls.generate_email_content(
+            data,
+            template_path=template_path,
+            placeholders=placeholders,
+            chart_specs=chart_specs,
+        )
+
+    @classmethod
+    def generate_and_save(
+        cls,
+        data,
+        *,
+        template_path: Path,
+        filename="email-body.html",
+        placeholders=None,
+        chart_specs=None,
+    ):
+        """Render and save an email body from canonical report data."""
+        content = cls.generate_email_content(
+            data,
+            template_path=template_path,
+            placeholders=placeholders,
+            chart_specs=chart_specs,
+        )
+        Path(filename).write_text(content, encoding="utf-8")
+        logger.info("Email HTML report successfully saved to: %s", filename)
+        return filename
+
+    @classmethod
+    def generate_from_json_and_save(
+        cls,
+        json_path: Path,
+        *,
+        template_path: Path,
+        filename="email-body.html",
+        placeholders=None,
+        chart_specs=None,
+    ):
+        """Render and save an email body from persisted report JSON."""
+        content = cls.generate_from_json(
+            json_path,
+            template_path=template_path,
+            placeholders=placeholders,
+            chart_specs=chart_specs,
+        )
+        Path(filename).write_text(content, encoding="utf-8")
+        logger.info("Email HTML report rendered from %s and saved to %s", json_path, filename)
+        return filename