reportlab-json-renderer 0.1.0__py3-none-any.whl

reportlab_json_renderer/__init__.py

@@ -0,0 +1,56 @@
+"""reportlab-json-renderer: JSON-driven PDF generation over ReportLab."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from reportlab_json_renderer.renderer import build_pdf
+
+__version__ = "0.1.0"
+
+
+def render_pdf(
+    spec: dict[str, Any],
+    output_path: str | None = None,
+    *,
+    allow_partial: bool = False,
+    asset_root: str | Path | None = None,
+) -> dict[str, Any]:
+    """Render a PDF from a validated JSON specification.
+
+    Args:
+        spec: The JSON document specification conforming to the report schema.
+        output_path: Optional filesystem path for the generated PDF.
+            If ``None``, the PDF is returned as bytes only.
+        allow_partial: If ``True``, continue after block-level render errors and
+            return them as warnings. If ``False``, raise on the first block-level
+            render failure.
+        asset_root: Directory boundary for local assets such as images. Relative
+            image paths are resolved under this root, and traversal outside it is
+            rejected. Defaults to the current working directory.
+
+    Returns:
+        A result dictionary containing:
+            - ``success`` (bool): Whether rendering completed without errors.
+            - ``path`` (str | None): The output file path, if written.
+            - ``bytes`` (bytes | None): Raw PDF bytes when no output_path given.
+            - ``pages`` (int): Number of pages in the generated PDF.
+            - ``warnings`` (list[str]): Non-fatal warnings collected during render.
+            - ``metadata`` (dict): Echo of template and theme used.
+
+    Raises:
+        reportlab_json_renderer.utils.errors.ValidationError:
+            If the spec fails schema validation.
+        reportlab_json_renderer.utils.errors.RenderError:
+            If a block cannot be rendered.
+    """
+    return build_pdf(
+        spec,
+        output_path=output_path,
+        allow_partial=allow_partial,
+        asset_root=asset_root,
+    )
+
+
+__all__ = ["__version__", "render_pdf"]

reportlab_json_renderer/assets/__init__.py

@@ -0,0 +1 @@
+"""Static assets: fonts, logos, and other embedded resources."""

reportlab_json_renderer/blocks/__init__.py

@@ -0,0 +1,82 @@
+"""Block renderers.
+
+Each module in this package implements one block type (title, table, chart, …)
+and is registered with the block registry so the renderer can dispatch by type.
+
+Usage::
+
+    from reportlab_json_renderer.blocks import get_renderer, render_block
+
+    renderer = get_renderer("title")
+    flowables = renderer.render(block_data, theme=theme, template=tpl, available_width=500)
+"""
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.blocks.registry import (
+    get_renderer,
+    list_registered,
+    register,
+    render_block,
+)
+
+__all__ = [
+    "BaseBlock",
+    "get_renderer",
+    "list_registered",
+    "register",
+    "render_block",
+]
+
+# ── Auto-register all built-in block renderers ──────────────────────
+
+
+def _register_builtins() -> None:
+    """Register all built-in block renderers on first import."""
+    from reportlab_json_renderer.blocks.badge import BadgeBlock
+    from reportlab_json_renderer.blocks.callout import CalloutBlock
+    from reportlab_json_renderer.blocks.callout_group import CalloutGroupBlock
+    from reportlab_json_renderer.blocks.chart import ChartBlock
+    from reportlab_json_renderer.blocks.divider import DividerBlock
+    from reportlab_json_renderer.blocks.image import ImageBlock
+    from reportlab_json_renderer.blocks.insight_list import InsightListBlock
+    from reportlab_json_renderer.blocks.kpi_grid import KPIGridBlock
+    from reportlab_json_renderer.blocks.layout import TwoColumnBlock
+    from reportlab_json_renderer.blocks.matrix_table import MatrixTableBlock
+    from reportlab_json_renderer.blocks.page_break import PageBreakBlock
+    from reportlab_json_renderer.blocks.paragraph import ParagraphBlock
+    from reportlab_json_renderer.blocks.recommendations import RecommendationsBlock
+    from reportlab_json_renderer.blocks.registry import _REGISTRY
+    from reportlab_json_renderer.blocks.rich_text import RichTextBlock
+    from reportlab_json_renderer.blocks.section import SectionHeaderBlock
+    from reportlab_json_renderer.blocks.spacer import SpacerBlock
+    from reportlab_json_renderer.blocks.summary_box import SummaryBoxBlock
+    from reportlab_json_renderer.blocks.table import TableBlock
+    from reportlab_json_renderer.blocks.title import TitleBlock
+
+    for renderer_cls in (
+        TitleBlock,
+        SectionHeaderBlock,
+        ParagraphBlock,
+        RichTextBlock,
+        KPIGridBlock,
+        CalloutBlock,
+        CalloutGroupBlock,
+        TableBlock,
+        MatrixTableBlock,
+        InsightListBlock,
+        RecommendationsBlock,
+        ImageBlock,
+        ChartBlock,
+        TwoColumnBlock,
+        SpacerBlock,
+        PageBreakBlock,
+        DividerBlock,
+        BadgeBlock,
+        SummaryBoxBlock,
+    ):
+        r = renderer_cls()
+        if r.block_type not in _REGISTRY:
+            _REGISTRY[r.block_type] = r
+
+
+_register_builtins()

reportlab_json_renderer/blocks/badge.py

@@ -0,0 +1,45 @@
+"""Badge block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.lib import colors
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.platypus import Flowable, Paragraph
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.utils.text import safe_paragraph_text
+
+
+class BadgeBlock(BaseBlock):
+    """Render a small inline badge label."""
+
+    block_type = "badge"
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        label = safe_paragraph_text(str(block.get("label", "")))
+        tone = block.get("tone", "primary")
+
+        bg_color = theme.resolve_tone(tone) if theme else "#7CB518"
+        text_color = "#FFFFFF"
+
+        html = f'<font size="8" color="{text_color}">' f"<b>{label}</b>" f"</font>"
+
+        style = ParagraphStyle(
+            "Badge",
+            fontName=theme.font_bold if theme else "Helvetica-Bold",
+            fontSize=8,
+            textColor=colors.HexColor(text_color),
+            backColor=colors.HexColor(bg_color),
+            spaceAfter=4,
+        )
+
+        return [Paragraph(html, style)]

reportlab_json_renderer/blocks/base.py

@@ -0,0 +1,61 @@
+"""Abstract base class for block renderers.
+
+Every block type (title, paragraph, table, …) must subclass
+:class:`BaseBlock` and implement :meth:`render`.
+
+Block renderers receive the parsed block data, the active theme, and
+the active template.  They return a list of ReportLab ``Flowable``
+objects that the PDF builder assembles into the document.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from reportlab.platypus import Flowable
+
+
+class BaseBlock(ABC):
+    """Abstract base for all block renderers.
+
+    Subclasses must set ``block_type`` as a class attribute and
+    implement :meth:`render`.
+
+    Class Attributes:
+        block_type: The JSON ``"type"`` value this renderer handles.
+    """
+
+    block_type: str
+
+    @abstractmethod
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        """Render a single block to ReportLab flowables.
+
+        Args:
+            block: The parsed block dictionary from the JSON spec.
+            theme: The active :class:`Theme` instance.
+            template: The active :class:`Template` instance.
+            available_width: Usable width in points (page width minus margins).
+
+        Returns:
+            List of ReportLab :class:`Flowable` objects.
+        """
+
+    def validate(self, block: dict[str, Any]) -> list[str]:
+        """Optional pre-render validation.
+
+        Args:
+            block: The raw block dictionary.
+
+        Returns:
+            List of warning strings. Empty if valid.
+        """
+        return []

reportlab_json_renderer/blocks/callout.py

@@ -0,0 +1,75 @@
+"""Callout block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.lib import colors
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.platypus import Flowable, Paragraph, Spacer, Table, TableStyle
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.utils.colors import tone_tint
+from reportlab_json_renderer.utils.text import safe_paragraph_text
+
+
+class CalloutBlock(BaseBlock):
+    """Render a coloured callout box with optional title and text."""
+
+    block_type = "callout"
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        tone = block.get("tone", "primary")
+        title = safe_paragraph_text(str(block.get("title", "")))
+        text = safe_paragraph_text(str(block.get("text", ""))).replace("\n", "<br/>")
+
+        border_color = theme.resolve_tone(tone) if theme else "#7CB518"
+        bg_color = tone_tint(tone, theme.tones if theme else None)
+        border_width = theme.callout_border_width if theme else 3.0
+
+        # Build inner content.
+        inner_parts: list[str] = []
+        if title:
+            inner_parts.append(f'<b><font size="10">{title}</font></b><br/>')
+        inner_parts.append(f'<font size="9">{text}</font>')
+        html = "".join(inner_parts)
+
+        text_style = ParagraphStyle(
+            "CalloutText",
+            fontName=theme.font_body if theme else "Helvetica",
+            fontSize=9,
+            leading=13,
+            textColor=colors.HexColor(theme.resolve_tone("dark") if theme else "#2D2D2D"),
+        )
+
+        para = Paragraph(html, text_style)
+
+        # Wrap in a table for the left-border effect.
+        table = Table([[para]], colWidths=[available_width - border_width - 12])
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (-1, -1), colors.HexColor(bg_color)),
+                    ("LEFTPADDING", (0, 0), (-1, -1), 10),
+                    ("RIGHTPADDING", (0, 0), (-1, -1), 8),
+                    ("TOPPADDING", (0, 0), (-1, -1), 6),
+                    ("BOTTOMPADDING", (0, 0), (-1, -1), 6),
+                    (
+                        "LINEBEFORETABLE",
+                        (0, 0),
+                        (0, -1),
+                        border_width,
+                        colors.HexColor(border_color),
+                    ),
+                ]
+            )
+        )
+
+        return [Spacer(1, 4), table, Spacer(1, 6)]

reportlab_json_renderer/blocks/callout_group.py

@@ -0,0 +1,56 @@
+"""Callout group block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.platypus import Flowable, Paragraph
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.blocks.callout import CalloutBlock
+from reportlab_json_renderer.utils.text import safe_paragraph_text
+
+
+class CalloutGroupBlock(BaseBlock):
+    """Render a group of callouts under a shared title."""
+
+    block_type = "callout_group"
+
+    def __init__(self) -> None:
+        self._callout_renderer = CalloutBlock()
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        title = safe_paragraph_text(str(block.get("title", "")))
+        items = block.get("items", [])
+        flowables: list[Flowable] = []
+
+        if title:
+            from reportlab.lib import colors
+            from reportlab.lib.styles import ParagraphStyle
+
+            title_style = ParagraphStyle(
+                "CalloutGroupTitle",
+                fontName=theme.font_bold if theme else "Helvetica-Bold",
+                fontSize=12,
+                textColor=colors.HexColor(theme.resolve_tone("dark") if theme else "#2D2D2D"),
+                spaceAfter=6,
+            )
+            flowables.append(Paragraph(title, title_style))
+
+        for item in items:
+            callout_flowables = self._callout_renderer.render(
+                item,
+                theme=theme,
+                template=template,
+                available_width=available_width,
+            )
+            flowables.extend(callout_flowables)
+
+        return flowables

reportlab_json_renderer/blocks/chart.py

@@ -0,0 +1,68 @@
+"""Chart block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.lib import colors
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.platypus import Flowable, Paragraph, Spacer
+from reportlab.platypus import Image as RLImage
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.utils.charts import render_chart
+from reportlab_json_renderer.utils.errors import RenderError
+from reportlab_json_renderer.utils.text import safe_paragraph_text
+
+
+class ChartBlock(BaseBlock):
+    """Render a chart as an embedded PNG image."""
+
+    block_type = "chart"
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        chart_type = block.get("chart_type", "bar")
+        title = safe_paragraph_text(str(block.get("title", "")))
+        labels = block.get("labels", [])
+        values = block.get("values", [])
+        series = block.get("series")
+        tone = block.get("tone")
+        flowables: list[Flowable] = []
+
+        if title:
+            title_style = ParagraphStyle(
+                "ChartTitle",
+                fontName=theme.font_bold if theme else "Helvetica-Bold",
+                fontSize=11,
+                textColor=colors.HexColor(theme.resolve_tone("dark") if theme else "#2D2D2D"),
+                spaceAfter=6,
+            )
+            flowables.append(Paragraph(title, title_style))
+
+        try:
+            theme_palette = theme.tones if theme else None
+            buf = render_chart(
+                chart_type=chart_type,
+                labels=labels,
+                values=values,
+                series=series,
+                tone=tone,
+                theme_palette=theme_palette,
+            )
+            img_width = available_width * 0.9
+            img_height = img_width * 0.5
+            img = RLImage(buf, width=img_width, height=img_height)
+            img.hAlign = "CENTER"
+            flowables.append(img)
+        except Exception as exc:
+            raise RenderError(f"Chart render failed: {exc}") from exc
+
+        flowables.append(Spacer(1, 8))
+        return flowables

reportlab_json_renderer/blocks/divider.py

@@ -0,0 +1,45 @@
+"""Divider block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.lib import colors
+from reportlab.platypus import Flowable, Spacer
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+
+
+class DividerBlock(BaseBlock):
+    """Render a horizontal divider line."""
+
+    block_type = "divider"
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        tone = block.get("tone", "primary")
+        thickness = block.get("thickness", 1.0)
+        line = _DividerLine(available_width, tone, thickness, theme)
+        return [Spacer(1, 4), line, Spacer(1, 4)]
+
+
+class _DividerLine(Flowable):
+    def __init__(self, width: float, tone: str, thickness: float, theme: Any = None) -> None:
+        super().__init__()
+        self.width = width
+        self.height = thickness
+        self._tone = tone
+        self._thickness = thickness
+        self._theme = theme
+
+    def draw(self) -> None:
+        hex_color = self._theme.resolve_tone(self._tone) if self._theme else "#7CB518"
+        self.canv.setStrokeColor(colors.HexColor(hex_color))
+        self.canv.setLineWidth(self._thickness)
+        self.canv.line(0, 0, self.width, 0)

reportlab_json_renderer/blocks/image.py

@@ -0,0 +1,58 @@
+"""Image block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.lib import colors
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.platypus import Flowable, Paragraph, Spacer
+from reportlab.platypus import Image as RLImage
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.utils.images import load_local_image
+from reportlab_json_renderer.utils.text import safe_paragraph_text
+from reportlab_json_renderer.utils.units import cm_to_pt
+
+
+class ImageBlock(BaseBlock):
+    """Render an image block from a local file path."""
+
+    block_type = "image"
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        title = safe_paragraph_text(str(block.get("title", "")))
+        src = block.get("src", "")
+        width_cm = block.get("width_cm")
+        height_cm = block.get("height_cm")
+        align = block.get("align", "center")
+        flowables: list[Flowable] = []
+
+        if title:
+            title_style = ParagraphStyle(
+                "ImageTitle",
+                fontName=theme.font_bold if theme else "Helvetica-Bold",
+                fontSize=10,
+                textColor=colors.HexColor(theme.resolve_tone("dark") if theme else "#2D2D2D"),
+                spaceAfter=4,
+            )
+            flowables.append(Paragraph(title, title_style))
+
+        # Resolve dimensions.
+        w = cm_to_pt(width_cm) if width_cm else available_width * 0.8
+        h = cm_to_pt(height_cm) if height_cm else w * 0.5
+
+        image_path = load_local_image(src)
+        img = RLImage(str(image_path), width=w, height=h)
+        img.hAlign = align.upper()
+        flowables.append(img)
+
+        flowables.append(Spacer(1, 8))
+        return flowables

reportlab_json_renderer/blocks/insight_list.py

@@ -0,0 +1,62 @@
+"""Insight list block renderer."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from reportlab.lib import colors
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.platypus import Flowable, Paragraph
+
+from reportlab_json_renderer.blocks.base import BaseBlock
+from reportlab_json_renderer.utils.text import safe_paragraph_text
+
+
+class InsightListBlock(BaseBlock):
+    """Render a numbered/bulleted insight list."""
+
+    block_type = "insight_list"
+
+    def render(
+        self,
+        block: dict[str, Any],
+        *,
+        theme: Any,
+        template: Any,
+        available_width: float,
+    ) -> list[Flowable]:
+        title = safe_paragraph_text(str(block.get("title", "")))
+        items = block.get("items", [])
+        flowables: list[Flowable] = []
+
+        if title:
+            title_style = ParagraphStyle(
+                "InsightTitle",
+                fontName=theme.font_bold if theme else "Helvetica-Bold",
+                fontSize=12,
+                textColor=colors.HexColor(theme.resolve_tone("dark") if theme else "#2D2D2D"),
+                spaceAfter=8,
+            )
+            flowables.append(Paragraph(title, title_style))
+
+        for idx, item in enumerate(items, 1):
+            item_title = safe_paragraph_text(str(item.get("title", "")))
+            item_text = safe_paragraph_text(str(item.get("text", ""))).replace("\n", "<br/>")
+
+            html_parts = [f"<b>{idx}. {item_title}</b>"]
+            if item_text:
+                html_parts.append(f"<br/>{item_text}")
+            html = "".join(html_parts)
+
+            style = ParagraphStyle(
+                "InsightItem",
+                fontName=theme.font_body if theme else "Helvetica",
+                fontSize=10,
+                leading=14,
+                textColor=colors.HexColor(theme.resolve_tone("dark") if theme else "#2D2D2D"),
+                spaceBefore=4,
+                spaceAfter=4,
+            )
+            flowables.append(Paragraph(html, style))
+
+        return flowables