pdfblox 1.0.0__py3-none-any.whl

pdfblox/__init__.py

@@ -0,0 +1,127 @@
+# Copyright (c) 2026 Aleksey Suvorov
+# SPDX-License-Identifier: MIT
+"""
+pdfblox — composable PDF building blocks.
+
+A dependency-light library (ReportLab only) for assembling PDF reports from
+declarative building blocks: styled tables, key/value tables, text and
+headings, images, layout primitives (spacers, dividers, KPI callouts), page
+headers/footers, title pages, and tile grids — composed via a fluent
+``Report`` builder.
+
+pdfblox knows nothing about where data or images come from. Callers pass in
+plain Python data (``list[dict]`` rows), image *bytes* or ready-made
+ReportLab flowables, and configuration objects. Fetching data, rendering
+charts, and loading environment/credentials are the responsibility of the
+integration layer that sits above this library.
+"""
+
+from .tables import (
+    ColumnConfig,
+    TableConfig,
+    create_table,
+    KeyValueConfig,
+    create_keyvalue_table,
+)
+from .text import TextConfig, paragraph, heading
+from .lists import ListConfig, bullet_list, numbered_list
+from .images import make_image
+from .layout import CalloutConfig, spacer, divider, kpi_callout
+from .charts import (
+    ChartConfig, bar_chart, line_chart, pie_chart, scatter_chart,
+)
+from .header import HeaderConfig, draw_page_header
+from .footer import FooterConfig, draw_page_footer
+from .document import (
+    PdfConfig,
+    TitlePageConfig,
+    TileGridConfig,
+    build_pdf,
+    build_paginated_pdf,
+    build_tile_grid,
+)
+from .report import Report
+from .theme import Theme
+from .fonts import register_font, use_unicode_fonts
+from .themes import (
+    corporate_blue,
+    slate_gray,
+    forest_green,
+    burgundy,
+    teal,
+    graphite,
+    get_theme,
+    available_themes,
+)
+from .utils import (
+    parse_timestamp,
+    normalize_date,
+    blank_to_none,
+    open_file_in_windows,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Tables
+    "ColumnConfig",
+    "TableConfig",
+    "create_table",
+    "KeyValueConfig",
+    "create_keyvalue_table",
+    # Text
+    "TextConfig",
+    "paragraph",
+    "heading",
+    # Lists
+    "ListConfig",
+    "bullet_list",
+    "numbered_list",
+    # Images
+    "make_image",
+    # Layout primitives
+    "CalloutConfig",
+    "spacer",
+    "divider",
+    "kpi_callout",
+    # Charts (native vector)
+    "ChartConfig",
+    "bar_chart",
+    "line_chart",
+    "pie_chart",
+    "scatter_chart",
+    # Header
+    "HeaderConfig",
+    "draw_page_header",
+    # Footer
+    "FooterConfig",
+    "draw_page_footer",
+    # Document assembly
+    "PdfConfig",
+    "TitlePageConfig",
+    "TileGridConfig",
+    "build_pdf",
+    "build_paginated_pdf",
+    "build_tile_grid",
+    # Fluent builder
+    "Report",
+    # Theme
+    "Theme",
+    # Fonts (Unicode support)
+    "register_font",
+    "use_unicode_fonts",
+    # Theme presets
+    "corporate_blue",
+    "slate_gray",
+    "forest_green",
+    "burgundy",
+    "teal",
+    "graphite",
+    "get_theme",
+    "available_themes",
+    # Utilities
+    "parse_timestamp",
+    "normalize_date",
+    "blank_to_none",
+    "open_file_in_windows",
+]

pdfblox/charts.py

@@ -0,0 +1,381 @@
+# Copyright (c) 2026 Aleksey Suvorov
+# SPDX-License-Identifier: MIT
+"""
+pdfblox.charts
+Native vector chart blocks built on ReportLab's own graphics engine
+(``reportlab.graphics``) — no external charting or rendering dependency.
+
+Each function takes in-memory numeric data and returns a ``Drawing`` flowable
+that renders as crisp vectors directly in the PDF. This is the right tool for
+the standard reporting charts (bar, line, pie/donut, scatter).
+
+For charts that must reproduce a figure rendered elsewhere (Plotly, matplotlib,
+a server-side SVG/PNG), use :func:`pdfblox.images.make_image` with the rendered
+bytes instead — rendering stays outside this library.
+
+Data shapes:
+    * bar / line: a single series ``[1, 2, 3]`` or multiple series
+      ``[[1, 2, 3], [4, 5, 6]]``.
+    * pie / donut: a flat list of values ``[30, 50, 20]``.
+    * scatter: one series of points ``[(x, y), ...]`` or several
+      ``[[(x, y), ...], [(x, y), ...]]``.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from reportlab.lib import colors
+from reportlab.graphics.shapes import Drawing, String, Rect, Group
+from reportlab.graphics.charts.barcharts import VerticalBarChart, HorizontalBarChart
+from reportlab.graphics.charts.linecharts import HorizontalLineChart
+from reportlab.graphics.charts.lineplots import LinePlot
+from reportlab.graphics.charts.piecharts import Pie
+from reportlab.graphics.charts.doughnut import Doughnut
+from reportlab.graphics.charts.legends import Legend
+from reportlab.graphics.widgets.markers import makeMarker
+
+
+# Fallback qualitative palette used when no theme/config supplies colours.
+_DEFAULT_COLORS = [
+    colors.HexColor(c) for c in (
+        "#1F4E79", "#E08E45", "#6A8D73", "#8E7CC3",
+        "#C25B56", "#4E79A7", "#9C755F", "#BAB0AC",
+    )
+]
+
+
+@dataclass
+class ChartConfig:
+    """Styling shared by all chart blocks.
+
+    Args:
+        width: Drawing width in points.
+        height: Drawing height in points.
+        colors: Series colour sequence (cycled if there are more series).
+        background: Optional drawing background fill.  *None* = transparent.
+        font: Font for axis/value labels.
+        font_size: Label font size.
+        label_color: Axis label text colour.
+        axis_color: Axis line colour.
+        grid_color: Value-axis gridline colour.  *None* hides the grid.
+        show_legend: Draw a legend (needs series/slice names).
+        legend_font_size: Legend font size.
+        title: Optional chart title drawn centred at the top.
+        title_font: Title font.
+        title_font_size: Title font size.
+        title_color: Title colour.
+        x_title: Optional label drawn under the x axis.
+        y_title: Optional label drawn (rotated) beside the y axis.
+        marker_size: Marker diameter for line/scatter points.
+    """
+    width: float = 400
+    height: float = 220
+    colors: list = field(default_factory=lambda: list(_DEFAULT_COLORS))
+    background: Optional[Any] = None
+    font: str = "Helvetica"
+    font_size: int = 8
+    label_color: Any = field(default_factory=lambda: colors.black)
+    axis_color: Any = field(default_factory=lambda: colors.HexColor("#666666"))
+    grid_color: Optional[Any] = field(default_factory=lambda: colors.HexColor("#DDDDDD"))
+    show_legend: bool = False
+    legend_font_size: int = 7
+    title: str = ""
+    title_font: str = "Helvetica-Bold"
+    title_font_size: int = 10
+    title_color: Any = field(default_factory=lambda: colors.black)
+    x_title: str = ""
+    y_title: str = ""
+    marker_size: float = 4
+
+
+# =========================================================================
+# Internal helpers
+# =========================================================================
+
+def _is_number(x) -> bool:
+    return isinstance(x, (int, float)) and not isinstance(x, bool)
+
+
+def _normalize_series(data) -> list:
+    """Coerce a single series or a list of series into a list of series."""
+    if data and _is_number(data[0]):
+        return [list(data)]
+    return [list(s) for s in data]
+
+
+def _margins(cfg: ChartConfig) -> tuple:
+    """(left, right, top, bottom) padding reserved for labels/title/legend."""
+    left = 45 + (cfg.font_size + 6 if cfg.y_title else 0)
+    right = 15
+    top = 8 + (cfg.title_font_size + 6 if cfg.title else 0)
+    bottom = 22  # category tick labels
+    bottom += _legend_band(cfg)  # legend sits in its own band at the very bottom
+    bottom += cfg.font_size + 6 if cfg.x_title else 0
+    return left, right, top, bottom
+
+
+def _legend_band(cfg: ChartConfig) -> float:
+    """Vertical space reserved for the legend at the bottom of the drawing."""
+    return (cfg.legend_font_size + 14) if cfg.show_legend else 0
+
+
+def _add_axis_titles(d: Drawing, cfg: ChartConfig, plot) -> None:
+    """Draw optional x/y axis titles around a placed chart/plot.
+
+    The x-axis title sits in a band just above the legend band, so the two
+    never overlap when both are enabled.
+    """
+    if cfg.x_title:
+        s = String(plot.x + plot.width / 2, _legend_band(cfg) + 4, cfg.x_title)
+        s.fontName = cfg.font
+        s.fontSize = cfg.font_size
+        s.fillColor = cfg.label_color
+        s.textAnchor = "middle"
+        d.add(s)
+    if cfg.y_title:
+        # String has no angle attr; rotate via a Group transform instead.
+        s = String(0, 0, cfg.y_title)
+        s.fontName = cfg.font
+        s.fontSize = cfg.font_size
+        s.fillColor = cfg.label_color
+        s.textAnchor = "middle"
+        g = Group(s)
+        g.translate(12, plot.y + plot.height / 2)
+        g.rotate(90)
+        d.add(g)
+
+
+def _new_drawing(cfg: ChartConfig) -> Drawing:
+    d = Drawing(cfg.width, cfg.height)
+    if cfg.background is not None:
+        d.add(Rect(0, 0, cfg.width, cfg.height,
+                   fillColor=cfg.background, strokeColor=None))
+    return d
+
+
+def _add_title(d: Drawing, cfg: ChartConfig) -> None:
+    if cfg.title:
+        s = String(cfg.width / 2, cfg.height - cfg.title_font_size - 2, cfg.title)
+        s.fontName = cfg.title_font
+        s.fontSize = cfg.title_font_size
+        s.fillColor = cfg.title_color
+        s.textAnchor = "middle"
+        d.add(s)
+
+
+def _add_legend(d: Drawing, cfg: ChartConfig, names) -> None:
+    if not (cfg.show_legend and names):
+        return
+    leg = Legend()
+    leg.colorNamePairs = [
+        (cfg.colors[i % len(cfg.colors)], str(n)) for i, n in enumerate(names)
+    ]
+    leg.fontName = cfg.font
+    leg.fontSize = cfg.legend_font_size
+    leg.x = cfg.width / 2
+    leg.boxAnchor = "s"
+    leg.dx = 6
+    leg.dy = 6
+    leg.dxTextSpace = 4
+    leg.columnMaximum = 1          # one item per column -> single horizontal row
+    leg.alignment = "right"
+    leg.deltax = 70
+    # Anchor the legend box to the very bottom: measure at y=0, then shift so
+    # its bounding-box bottom lands at y=4. (Legend.y maps 1:1 to bounds.)
+    leg.y = 0
+    bottom = leg.getBounds()[1]
+    leg.y = 4 - bottom
+    d.add(leg)
+
+
+def _style_cartesian(chart, cfg: ChartConfig, categories) -> None:
+    """Apply fonts, colours, and grid to a category/value chart."""
+    if categories:
+        chart.categoryAxis.categoryNames = [str(c) for c in categories]
+    for ax in (chart.categoryAxis, chart.valueAxis):
+        ax.labels.fontName = cfg.font
+        ax.labels.fontSize = cfg.font_size
+        ax.labels.fillColor = cfg.label_color
+        ax.strokeColor = cfg.axis_color
+    if cfg.grid_color is not None:
+        chart.valueAxis.visibleGrid = 1
+        chart.valueAxis.gridStrokeColor = cfg.grid_color
+
+
+# =========================================================================
+# Chart blocks
+# =========================================================================
+
+def bar_chart(data, categories=None, series_names=None, *,
+              config: Optional[ChartConfig] = None, horizontal: bool = False) -> Drawing:
+    """Vertical (default) or horizontal bar chart.
+
+    Args:
+        data: One series or a list of series of numbers.
+        categories: Category (x) axis labels.
+        series_names: Names for the legend (one per series).
+        config: Optional :class:`ChartConfig`.
+        horizontal: Draw horizontal bars when true.
+
+    Returns:
+        A ReportLab ``Drawing`` flowable.
+    """
+    cfg = config or ChartConfig()
+    series = _normalize_series(data)
+    d = _new_drawing(cfg)
+
+    chart = HorizontalBarChart() if horizontal else VerticalBarChart()
+    left, right, top, bottom = _margins(cfg)
+    chart.x, chart.y = left, bottom
+    chart.width = cfg.width - left - right
+    chart.height = cfg.height - top - bottom
+    chart.data = series
+    # Anchor the axis at zero only when all values are non-negative; otherwise
+    # let it auto-scale so negative bars (variance/deltas) render correctly.
+    flat = [v for s in series for v in s]
+    if flat and min(flat) >= 0:
+        chart.valueAxis.valueMin = 0
+    _style_cartesian(chart, cfg, categories)
+
+    for i in range(len(series)):
+        chart.bars[i].fillColor = cfg.colors[i % len(cfg.colors)]
+        chart.bars[i].strokeColor = None
+
+    d.add(chart)
+    _add_title(d, cfg)
+    _add_axis_titles(d, cfg, chart)
+    _add_legend(d, cfg, series_names)
+    return d
+
+
+def line_chart(data, categories=None, series_names=None, *,
+               config: Optional[ChartConfig] = None, markers: bool = True) -> Drawing:
+    """Category-based line chart (trends over ordered categories).
+
+    Args:
+        data: One series or a list of series of numbers.
+        categories: Category (x) axis labels.
+        series_names: Names for the legend (one per series).
+        config: Optional :class:`ChartConfig`.
+        markers: Draw a point marker at each value.
+
+    Returns:
+        A ReportLab ``Drawing`` flowable.
+    """
+    cfg = config or ChartConfig()
+    series = _normalize_series(data)
+    d = _new_drawing(cfg)
+
+    chart = HorizontalLineChart()
+    left, right, top, bottom = _margins(cfg)
+    chart.x, chart.y = left, bottom
+    chart.width = cfg.width - left - right
+    chart.height = cfg.height - top - bottom
+    chart.data = series
+    _style_cartesian(chart, cfg, categories)
+
+    for i in range(len(series)):
+        color = cfg.colors[i % len(cfg.colors)]
+        chart.lines[i].strokeColor = color
+        chart.lines[i].strokeWidth = 1.5
+        if markers:
+            chart.lines[i].symbol = makeMarker("FilledCircle")
+            chart.lines[i].symbol.size = cfg.marker_size
+            chart.lines[i].symbol.fillColor = color
+
+    d.add(chart)
+    _add_title(d, cfg)
+    _add_axis_titles(d, cfg, chart)
+    _add_legend(d, cfg, series_names)
+    return d
+
+
+def pie_chart(values, labels=None, *,
+              config: Optional[ChartConfig] = None, donut: bool = False) -> Drawing:
+    """Pie or donut chart of part-to-whole values.
+
+    Args:
+        values: Flat list of slice values.
+        labels: Slice labels (shown on slices, or in the legend when
+            ``show_legend`` is set).
+        config: Optional :class:`ChartConfig`.
+        donut: Render a donut (ring) instead of a full pie.
+
+    Returns:
+        A ReportLab ``Drawing`` flowable.
+    """
+    cfg = config or ChartConfig()
+    d = _new_drawing(cfg)
+
+    pie = Doughnut() if donut else Pie()
+    left, right, top, bottom = _margins(cfg)
+    avail_h = cfg.height - top - bottom
+    size = max(10, min(cfg.width - left - right, avail_h))
+    pie.width = pie.height = size
+    pie.x = (cfg.width - size) / 2
+    pie.y = bottom
+    pie.data = list(values)
+    if labels and not cfg.show_legend:
+        pie.labels = [str(l) for l in labels]
+    pie.slices.strokeColor = colors.white
+    pie.slices.strokeWidth = 0.5
+    for i in range(len(values)):
+        pie.slices[i].fillColor = cfg.colors[i % len(cfg.colors)]
+
+    d.add(pie)
+    _add_title(d, cfg)
+    _add_legend(d, cfg, labels)
+    return d
+
+
+def scatter_chart(series, series_names=None, *,
+                  config: Optional[ChartConfig] = None) -> Drawing:
+    """XY scatter plot.
+
+    Args:
+        series: One series of ``(x, y)`` points, or a list of such series.
+        series_names: Names for the legend (one per series).
+        config: Optional :class:`ChartConfig`.
+
+    Returns:
+        A ReportLab ``Drawing`` flowable.
+    """
+    cfg = config or ChartConfig()
+
+    # One series of points -> wrap; otherwise treat as list of series.
+    if (series and isinstance(series[0], (tuple, list))
+            and len(series[0]) == 2 and _is_number(series[0][0])):
+        data = [[tuple(p) for p in series]]
+    else:
+        data = [[tuple(p) for p in s] for s in series]
+
+    d = _new_drawing(cfg)
+    plot = LinePlot()
+    left, right, top, bottom = _margins(cfg)
+    plot.x, plot.y = left, bottom
+    plot.width = cfg.width - left - right
+    plot.height = cfg.height - top - bottom
+    plot.data = data
+    plot.joinedLines = 0  # points only
+
+    for i in range(len(data)):
+        color = cfg.colors[i % len(cfg.colors)]
+        plot.lines[i].strokeColor = color
+        plot.lines[i].symbol = makeMarker("FilledCircle")
+        plot.lines[i].symbol.size = cfg.marker_size
+        plot.lines[i].symbol.fillColor = color
+
+    for ax in (plot.xValueAxis, plot.yValueAxis):
+        ax.labels.fontName = cfg.font
+        ax.labels.fontSize = cfg.font_size
+        ax.labels.fillColor = cfg.label_color
+        ax.strokeColor = cfg.axis_color
+    if cfg.grid_color is not None:
+        plot.yValueAxis.visibleGrid = 1
+        plot.yValueAxis.gridStrokeColor = cfg.grid_color
+
+    d.add(plot)
+    _add_title(d, cfg)
+    _add_axis_titles(d, cfg, plot)
+    _add_legend(d, cfg, series_names)
+    return d