table-renderer 0.4.0__tar.gz → 0.5.0__tar.gz

{table_renderer-0.4.0 → table_renderer-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: table-renderer
-Version: 0.4.0
+Version: 0.5.0
 Summary: A Python library for rendering structured tables as high-quality images or HTML.
 Keywords: table,renderer,rendering,image,html,weasyprint,pdfium,report
 Author: pTaunium
@@ -17,6 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: jinja2~=3.0
 Requires-Dist: pillow~=12.0
 Requires-Dist: pypdfium2~=5.0
+Requires-Dist: typing-extensions>=4.5.0
 Requires-Dist: weasyprint>=68.1
 Requires-Python: >=3.12, <3.15
 Description-Content-Type: text/markdown
@@ -83,6 +84,7 @@ from table_renderer import Table
 # 1. Initialize a 3x3 table
 table = Table(3, 3)
 table.set_border(width=1, color="black", style="solid")
+table.set_width(400)
 
 # 2. Set header style (Row 0)
 header = table.get_row(0)
@@ -94,7 +96,7 @@ table.cell(0, 1).set_text("Category")
 table.cell(0, 2).set_text("Price")
 
 # 3. Add content and demonstrate merging
-table.cell(1, 0).set_text("MacBook Pro").span(rows=1, cols=2)
+table.cell(1, 0).set_text("MacBook Pro").set_span(rows=1, cols=2)
 table.cell(1, 2).set_text("$2,000")
 
 table.cell(2, 0).set_text("Magic Mouse")
@@ -118,7 +120,7 @@ Use the anchor-based design to merge cells by specifying the starting cell and t
 
 ```python
 # Merge first row, first two columns (1 row, 2 columns)
-table.cell(0, 0).span(rows=1, cols=2).set_text("Merged Header")
+table.cell(0, 0).set_span(rows=1, cols=2).set_text("Merged Header")
 ```
 
 ### 2. Font Management
@@ -148,12 +150,13 @@ table.cell(1, 1).set_image("https://example.com/image.jpg", width=100)
 
 ### 4. Layout & Sizing
 
-Mix fixed widths, percentages, and auto-sizing.
+Mix fixed widths, heights, percentages, and auto-sizing.
 
 ```python
 table.set_width(800)                  # Total table width
-table.get_column(0).set_width(200)    # Fixed 200px
+table.get_column(0).set_width(200)    # Fixed column width (200px)
 table.get_column(1).set_width("auto") # Distribute remaining space
+table.get_row(0).set_height(100)      # Fixed row height (100px)
 ```
 
 **Handling Extremely Wide Tables:**

{table_renderer-0.4.0 → table_renderer-0.5.0}/README.md

@@ -60,6 +60,7 @@ from table_renderer import Table
 # 1. Initialize a 3x3 table
 table = Table(3, 3)
 table.set_border(width=1, color="black", style="solid")
+table.set_width(400)
 
 # 2. Set header style (Row 0)
 header = table.get_row(0)
@@ -71,7 +72,7 @@ table.cell(0, 1).set_text("Category")
 table.cell(0, 2).set_text("Price")
 
 # 3. Add content and demonstrate merging
-table.cell(1, 0).set_text("MacBook Pro").span(rows=1, cols=2)
+table.cell(1, 0).set_text("MacBook Pro").set_span(rows=1, cols=2)
 table.cell(1, 2).set_text("$2,000")
 
 table.cell(2, 0).set_text("Magic Mouse")
@@ -95,7 +96,7 @@ Use the anchor-based design to merge cells by specifying the starting cell and t
 
 ```python
 # Merge first row, first two columns (1 row, 2 columns)
-table.cell(0, 0).span(rows=1, cols=2).set_text("Merged Header")
+table.cell(0, 0).set_span(rows=1, cols=2).set_text("Merged Header")
 ```
 
 ### 2. Font Management
@@ -125,12 +126,13 @@ table.cell(1, 1).set_image("https://example.com/image.jpg", width=100)
 
 ### 4. Layout & Sizing
 
-Mix fixed widths, percentages, and auto-sizing.
+Mix fixed widths, heights, percentages, and auto-sizing.
 
 ```python
 table.set_width(800)                  # Total table width
-table.get_column(0).set_width(200)    # Fixed 200px
+table.get_column(0).set_width(200)    # Fixed column width (200px)
 table.get_column(1).set_width("auto") # Distribute remaining space
+table.get_row(0).set_height(100)      # Fixed row height (100px)
 ```
 
 **Handling Extremely Wide Tables:**

{table_renderer-0.4.0 → table_renderer-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "table-renderer"
-version = "0.4.0"
+version = "0.5.0"
 description = "A Python library for rendering structured tables as high-quality images or HTML."
 readme = "README.md"
 license = "MIT"
@@ -27,6 +27,7 @@ dependencies = [
   "jinja2~=3.0",
   "pillow~=12.0",
   "pypdfium2~=5.0",
+  "typing-extensions>=4.5.0",
   "weasyprint>=68.1",
 ]
 

{table_renderer-0.4.0 → table_renderer-0.5.0}/src/table_renderer/__init__.py

@@ -6,6 +6,6 @@ try:
     __version__ = importlib.metadata.version("table-renderer")
 except importlib.metadata.PackageNotFoundError:
     # Package is not installed (e.g. during local development without pip install -e .)
-    __version__ = "0.4.0"
+    __version__ = "0.5.0"
 
 __all__ = ["Cell", "Column", "Row", "Style", "StyledObject", "Table", "__version__"]

table_renderer-0.5.0/src/table_renderer/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Rendering backends for table-renderer."""
+
+from .base import ImageRenderer
+from .weasyprint_renderer import WeasyPrintRenderer
+
+__all__ = ["ImageRenderer", "WeasyPrintRenderer"]

table_renderer-0.5.0/src/table_renderer/backends/base.py

@@ -0,0 +1,44 @@
+"""Protocol defining the image rendering backend interface."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+    from table_renderer.models.table import Table
+
+
+class ImageRenderer(Protocol):
+    """Interface for rendering a Table model to an image.
+
+    All rendering backends must implement this interface. This allows
+    swapping the underlying rendering engine (e.g., WeasyPrint, Blitz)
+    without changing the public API or HTML generation logic.
+    """
+
+    def render(
+        self,
+        table: Table,
+        *,
+        dpi: int = 144,
+        padding: int = 10,
+        background_color: str = "transparent",
+    ) -> Image:
+        """Render a Table to a tightly-cropped PIL Image.
+
+        The returned image should be cropped to content bounds
+        (plus the specified padding). It is the backend's
+        responsibility to ensure no excess whitespace.
+
+        Args:
+            table: The Table data model to render.
+            dpi: Target resolution in dots per inch.
+            padding: Pixels of padding around content.
+            background_color: Background color.
+
+        Returns:
+            A PIL Image (RGBA mode) tightly cropped to the table.
+        """
+        ...

table_renderer-0.5.0/src/table_renderer/backends/weasyprint_renderer.py

@@ -0,0 +1,271 @@
+"""WeasyPrint-based rendering backend."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from weasyprint import HTML
+
+from table_renderer.html_generator import render_to_html
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+    from table_renderer.models.cell import Cell
+    from table_renderer.models.table import Table
+
+_DEFAULT_COL_WIDTH = 100
+_DEFAULT_FONT_SIZE = 16
+_CELL_PADDING = 8
+_LINE_HEIGHT_RATIO = 1.4
+_MIN_PAGE_WIDTH = 200
+_MIN_PAGE_HEIGHT = 200
+_PAGE_PADDING = 60  # body padding (20px * 2) + safety margin
+
+
+class WeasyPrintRenderer:
+    """Renders tables via WeasyPrint (HTML → PDF → raster image).
+
+    This is the default rendering backend. It converts HTML to PDF
+    via WeasyPrint, rasterizes the PDF pages to bitmaps via pypdfium2,
+    and auto-crops excess whitespace from the PDF page.
+    """
+
+    def render(
+        self,
+        table: Table,
+        *,
+        dpi: int = 144,
+        padding: int = 10,
+        background_color: str = "transparent",
+    ) -> Image:
+        """Render a Table to a tightly-cropped PIL Image.
+
+        Args:
+            table: The Table data model to render.
+            dpi: Target resolution in dots per inch.
+            padding: Pixels of padding around content.
+            background_color: Background color.
+
+        Returns:
+            A PIL Image (RGBA mode) tightly cropped to the table.
+        """
+        page_css = _estimate_page_css(table)
+        html = render_to_html(
+            table, background_color=background_color, extra_css=page_css
+        )
+
+        # WeasyPrint v53+ removed write_png, so we render to PDF then convert
+        pdf_bytes = HTML(string=html).write_pdf()
+        full_page_image = _pdf_to_image(pdf_bytes, dpi=dpi)
+        return _auto_crop(full_page_image, padding=padding)
+
+
+def _estimate_page_css(table: Table) -> str:
+    """Generate ``@page`` CSS rules with estimated canvas size.
+
+    Estimates the PDF page dimensions based on the actual table
+    content — column widths, font sizes, text line counts, and
+    embedded image heights — rather than fixed magic numbers.
+
+    Args:
+        table: The Table object to estimate dimensions for.
+
+    Returns:
+        A CSS string containing the ``@page`` rule.
+    """
+    estimated_width = _estimate_width(table)
+    estimated_height = _estimate_height(table)
+
+    return (
+        "@page {\n"
+        f"    size: {estimated_width}px {estimated_height}px;"
+        " /* Dynamically estimated size */\n"
+        "    margin: 0;\n"
+        "}"
+    )
+
+
+def _estimate_width(table: Table) -> int:
+    """Estimate the required page width in pixels.
+
+    Uses explicit column widths where available and falls back
+    to a default per-column width for unset columns.
+
+    Args:
+        table: The Table to estimate width for.
+
+    Returns:
+        Estimated width in pixels.
+    """
+    if not table._cells:
+        return _MIN_PAGE_WIDTH
+
+    # If the table has an explicit pixel width, use it directly
+    if isinstance(table.width, int):
+        return max(_MIN_PAGE_WIDTH, table.width + _PAGE_PADDING)
+
+    # Sum column widths: use explicit value or default
+    total_width = 0
+    for col in table._col_objects:
+        if isinstance(col.width, int):
+            total_width += col.width
+        else:
+            total_width += _DEFAULT_COL_WIDTH
+
+    return max(_MIN_PAGE_WIDTH, total_width + _PAGE_PADDING)
+
+
+def _estimate_height(table: Table) -> int:
+    """Estimate the required page height in pixels.
+
+    Calculates a per-row height based on the tallest cell in
+    each row, considering font size, number of text lines, and
+    embedded image height.
+
+    Args:
+        table: The Table to estimate height for.
+
+    Returns:
+        Estimated height in pixels.
+    """
+    if not table._cells:
+        return _MIN_PAGE_HEIGHT
+
+    # Resolve the table-level default font size
+    table_font_size = table.style.font_size or _DEFAULT_FONT_SIZE
+
+    total_height = 0
+    for row_idx, row_cells in enumerate(table._cells):
+        row_obj = table._row_objects[row_idx]
+
+        # If an explicit integer height is provided, use it
+        if isinstance(row_obj.height, int):
+            total_height += row_obj.height
+            continue
+
+        # Resolve row-level font size
+        row_font_size = row_obj.style.font_size or table_font_size
+
+        row_height = 0
+        for cell in row_cells:
+            if cell.is_merged:
+                continue
+
+            cell_height = _estimate_cell_height(cell, default_font_size=row_font_size)
+            row_height = max(row_height, cell_height)
+
+        total_height += row_height
+
+    return max(_MIN_PAGE_HEIGHT, total_height + _PAGE_PADDING)
+
+
+def _estimate_cell_height(cell: Cell, *, default_font_size: int) -> int:
+    """Estimate the height of a single cell in pixels.
+
+    Accounts for font size, number of text lines (split by newlines),
+    cell padding, and embedded image height.
+
+    Args:
+        cell: The Cell to estimate.
+        default_font_size: Inherited font size if the cell has none set.
+
+    Returns:
+        Estimated cell height in pixels.
+    """
+    font_size = cell.style.font_size or default_font_size
+
+    # Text height: number of lines * font_size * line-height + padding
+    line_count = max(1, cell.value.count("\n") + 1) if cell.value else 1
+    text_height = int(line_count * font_size * _LINE_HEIGHT_RATIO) + _CELL_PADDING * 2
+
+    # Image height (if present)
+    image_height = (cell.image_height or 0) + (_CELL_PADDING if cell.image_path else 0)
+
+    return text_height + image_height
+
+
+def _pdf_to_image(pdf_bytes: bytes, *, dpi: int) -> Image:
+    """Convert PDF bytes to a single stitched PIL Image.
+
+    Renders each page of the PDF at the specified DPI and
+    stitches them vertically into one tall image.
+
+    Args:
+        pdf_bytes: Raw PDF bytes.
+        dpi: Target resolution in dots per inch.
+
+    Returns:
+        A PIL RGBA Image with all pages stitched vertically.
+    """
+    import pypdfium2 as pdfium
+    from PIL import Image
+
+    with pdfium.PdfDocument(pdf_bytes) as pdf:
+        rendered_pages = []
+        scale_factor = dpi / 72  # PDF standard resolution is 72 DPI
+
+        # Render each page to a PIL Image
+        for page in pdf:
+            # fill_color=(255, 255, 255, 0) ensures transparent background
+            bitmap = page.render(scale=scale_factor, fill_color=(255, 255, 255, 0))
+            page_image = bitmap.to_pil()
+            rendered_pages.append(page_image)
+            bitmap.close()
+
+        if not rendered_pages:
+            return Image.new("RGBA", (1, 1), (255, 255, 255, 0))
+
+        # Stitch all pages vertically into one long image
+        total_width = max(img.width for img in rendered_pages)
+        total_height = sum(img.height for img in rendered_pages)
+        stitched = Image.new("RGBA", (total_width, total_height), (255, 255, 255, 0))
+
+        y_offset = 0
+        for img in rendered_pages:
+            stitched.paste(img, (0, y_offset))
+            y_offset += img.height
+
+    return stitched
+
+
+def _auto_crop(image: Image, *, padding: int) -> Image:
+    """Crop excess PDF page whitespace around the table.
+
+    WeasyPrint renders to a full PDF page, so the rendered image
+    typically has large margins that need to be trimmed.
+
+    Args:
+        image: The source PIL Image.
+        padding: Pixels of padding to preserve around content.
+
+    Returns:
+        The cropped image.
+    """
+    import PIL.ImageOps
+    from PIL import Image
+
+    # Find the bounding box of non-transparent/non-white content.
+    # Use 'L' (grayscale) mode to reduce memory usage (1 byte per pixel vs 3).
+    if image.mode == "RGBA":
+        # Flatten RGBA onto a white grayscale background
+        grayscale = Image.new("L", image.size, 255)
+        grayscale.paste(image.convert("L"), mask=image.getchannel("A"))
+    else:
+        # For RGB or other modes, just convert to grayscale
+        grayscale = image.convert("L")
+
+    # Invert and find bbox of "ink" (non-white pixels)
+    inverted = PIL.ImageOps.invert(grayscale)
+    bbox = inverted.getbbox()
+
+    if bbox:
+        # Expand crop region by the requested padding, clamped to image bounds
+        left, top, right, bottom = bbox
+        left = max(0, left - padding)
+        top = max(0, top - padding)
+        right = min(image.width, right + padding)
+        bottom = min(image.height, bottom + padding)
+        image = image.crop((left, top, right, bottom))
+
+    return image

table_renderer-0.5.0/src/table_renderer/html_generator.py

@@ -0,0 +1,126 @@
+"""HTML generation from Table models.
+
+This module converts Table data models into HTML document strings.
+It provides shared utilities that rendering backends can use, but
+is not tied to any specific rendering engine.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from jinja2 import Environment, FileSystemLoader, Template
+
+if TYPE_CHECKING:
+    from .models.table import Table
+
+# HTML template loaded from templates/table.html.j2
+_JINJA_ENV: Environment | None = None
+
+
+def _get_template() -> Template:
+    """Return the cached Jinja2 table template, initializing the environment on first call."""
+    global _JINJA_ENV
+    if _JINJA_ENV is None:
+        template_dir = Path(__file__).parent / "templates"
+        _JINJA_ENV = Environment(loader=FileSystemLoader(template_dir))  # noqa: S701
+    return _JINJA_ENV.get_template("table.html.j2")
+
+
+def _format_length(value: int | str) -> str:
+    """Format an integer as pixels, or return a string CSS value as is."""
+    return f"{value}px" if isinstance(value, int) else value
+
+
+def _prepare_render_context(
+    table: Table, *, background_color: str = "transparent"
+) -> dict[str, Any]:
+    """Prepare the Jinja2 template context from a Table model.
+
+    Handles merge-flag setup, font-face resolution, image URL
+    resolution, and extraction of column/row/cell data.
+
+    Args:
+        table: The Table object to prepare.
+        background_color: The background color of the body.
+
+    Returns:
+        A dict suitable for passing to ``Template.render()``.
+    """
+    table._prepare_render()
+
+    font_faces = []
+    for font_path in table.font_files:
+        font_name = os.path.splitext(os.path.basename(font_path))[0]
+        # Convert path to absolute file URL for rendering engines
+        absolute_font_path = os.path.abspath(font_path)
+        font_faces.append({"name": font_name, "path": f"file://{absolute_font_path}"})
+
+    cell_matrix = []
+    for row_index in range(len(table._cells)):
+        cell_row = []
+        for col_index in range(len(table._cells[0])):
+            cell = table._cells[row_index][col_index]
+
+            # Handle Image URL resolution
+            cell.image_url = ""
+            if cell.image_path:
+                if cell.image_path.startswith(("http://", "https://")):
+                    cell.image_url = cell.image_path
+                else:
+                    absolute_image_path = os.path.abspath(cell.image_path)
+                    cell.image_url = f"file://{absolute_image_path}"
+
+            cell_row.append(cell)
+        cell_matrix.append(cell_row)
+
+    return {
+        "background_color": background_color,
+        "table_width": _format_length(table.width),
+        "table_style": table.style.to_css(),
+        "font_faces": font_faces,
+        "columns": [
+            {
+                "index": c.index,
+                "width": _format_length(c.width),
+                "style": c.style.to_css(),
+            }
+            for c in table._col_objects
+        ],
+        "rows": [
+            {
+                "index": r.index,
+                "height": _format_length(r.height),
+                "style": r.style.to_css(),
+            }
+            for r in table._row_objects
+        ],
+        "cells": cell_matrix,
+    }
+
+
+def render_to_html(
+    table: Table,
+    *,
+    background_color: str = "transparent",
+    extra_css: str = "",
+) -> str:
+    """Generate the HTML representation of the table.
+
+    Args:
+        table: The Table object to render.
+        background_color: The background color of the body.
+        extra_css: Additional CSS to inject into the document head.
+            Used by backends to add engine-specific rules
+            (e.g., ``@page`` rules for WeasyPrint).
+
+    Returns:
+        A string containing the complete HTML document.
+    """
+    context = _prepare_render_context(table, background_color=background_color)
+    context["extra_css"] = extra_css
+    template = _get_template()
+
+    return template.render(**context)

{table_renderer-0.4.0 → table_renderer-0.5.0}/src/table_renderer/models/cell.py

@@ -1,5 +1,7 @@
 from typing import Self
 
+from typing_extensions import deprecated
+
 from .style import StyledObject
 
 
@@ -56,9 +58,8 @@ class Cell(StyledObject):
         self.image_height = height
         return self
 
-    def span(self, *, rows: int = 1, cols: int = 1) -> Self:
-        """
-        Set the row and column span for merging.
+    def set_span(self, *, rows: int = 1, cols: int = 1) -> Self:
+        """Set the row and column span for merging.
 
         Args:
             rows: Number of rows to span.
@@ -70,3 +71,26 @@ class Cell(StyledObject):
         self.row_span = rows
         self.col_span = cols
         return self
+
+    @deprecated("Use `set_span` instead.")
+    def span(self, *, rows: int = 1, cols: int = 1) -> Self:
+        """Set the row and column span for merging.
+
+        .. deprecated::
+            Use :meth:`set_span` instead.
+
+        Args:
+            rows: Number of rows to span.
+            cols: Number of columns to span.
+
+        Returns:
+            The cell itself for chaining.
+        """
+        import warnings
+
+        warnings.warn(
+            "Cell.span() is deprecated, use Cell.set_span() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.set_span(rows=rows, cols=cols)

table_renderer-0.5.0/src/table_renderer/models/row.py

@@ -0,0 +1,31 @@
+from typing import Self
+
+from .style import StyledObject
+
+
+class Row(StyledObject):
+    """Represents a row in a table."""
+
+    def __init__(self, index: int) -> None:
+        """
+        Initialize a row.
+
+        Args:
+            index: The 0-based index of the row.
+        """
+        super().__init__()
+        self.index = index
+        self.height: int | str = "auto"
+
+    def set_height(self, height: int | str) -> Self:
+        """
+        Set the height of the row.
+
+        Args:
+            height: Height in pixels (int) or CSS value (str, e.g., '50px', '2em').
+
+        Returns:
+            The row itself for chaining.
+        """
+        self.height = height
+        return self

{table_renderer-0.4.0 → table_renderer-0.5.0}/src/table_renderer/models/style.py

@@ -10,7 +10,7 @@ class Style:
     font_color: str | None = None
     font_family: str | None = None
     font_weight: Literal["normal", "bold"] | None = None
-    bg_color: str | None = None
+    background_color: str | None = None
     text_align: Literal["left", "center", "right"] | None = None
     vertical_align: Literal["top", "middle", "bottom"] | None = None
     border_width: int | None = None
@@ -72,8 +72,8 @@ class Style:
             css.append(f"font-family: {', '.join(families)};")
         if self.font_weight:
             css.append(f"font-weight: {self.font_weight};")
-        if self.bg_color:
-            css.append(f"background-color: {self.bg_color};")
+        if self.background_color:
+            css.append(f"background-color: {self.background_color};")
         if self.text_align:
             css.append(f"text-align: {self.text_align};")
         if self.vertical_align:
@@ -150,7 +150,7 @@ class StyledObject:
         Returns:
             The object itself for chaining.
         """
-        self.style.bg_color = color
+        self.style.background_color = color
         return self
 
     def set_align(

{table_renderer-0.4.0 → table_renderer-0.5.0}/src/table_renderer/models/table.py

@@ -1,6 +1,6 @@
 from typing import Self
 
-from table_renderer.renderer import render_to_image, save_html
+from table_renderer.renderer import save_html, save_image
 
 from .cell import Cell
 from .column import Column
@@ -20,8 +20,6 @@ class Table(StyledObject):
             cols: Initial number of columns.
         """
         super().__init__()
-        self._rows_count = rows
-        self._cols_count = cols
         self._cells = [[Cell() for _ in range(cols)] for _ in range(rows)]
         self._row_objects = [Row(i) for i in range(rows)]
         self._col_objects = [Column(i) for i in range(cols)]
@@ -39,10 +37,7 @@ class Table(StyledObject):
         Returns:
             The Cell object.
         """
-        while row_index >= len(self._cells):
-            self._add_row()
-        while col_index >= len(self._cells[0]):
-            self._add_col()
+        self._ensure_capacity(row_index, col_index)
         return self._cells[row_index][col_index]
 
     def get_row(self, row_index: int) -> Row:
@@ -55,8 +50,8 @@ class Table(StyledObject):
         Returns:
             The Row object.
         """
-        while row_index >= len(self._row_objects):
-            self._add_row()
+        current_cols = len(self._cells[0]) if self._cells else 0
+        self._ensure_capacity(row_index, max(0, current_cols - 1))
         return self._row_objects[row_index]
 
     def get_column(self, col_index: int) -> Column:
@@ -69,22 +64,34 @@ class Table(StyledObject):
         Returns:
             The Column object.
         """
-        while col_index >= len(self._col_objects):
-            self._add_col()
+        current_rows = len(self._cells)
+        self._ensure_capacity(max(0, current_rows - 1), col_index)
         return self._col_objects[col_index]
 
-    def _add_row(self) -> None:
-        """Internal helper to add a row."""
-        new_row_idx = len(self._cells)
-        cols_count = len(self._cells[0]) if self._cells else self._cols_count
-        self._cells.append([Cell() for _ in range(cols_count)])
-        self._row_objects.append(Row(new_row_idx))
-
-    def _add_col(self) -> None:
-        """Internal helper to add a column."""
-        for row in self._cells:
-            row.append(Cell())
-        self._col_objects.append(Column(len(self._col_objects)))
+    def _ensure_capacity(self, target_row: int, target_col: int) -> None:
+        """Efficiently grow the table to ensure it has at least target_row+1 rows and target_col+1 cols."""
+        current_rows = len(self._cells)
+        current_cols = len(self._cells[0]) if current_rows > 0 else 0
+
+        target_rows = max(current_rows, target_row + 1)
+        target_cols = max(current_cols, target_col + 1)
+
+        # 1. Expand existing rows with new columns if needed
+        cols_to_add = target_cols - current_cols
+        if cols_to_add > 0:
+            for row in self._cells:
+                row.extend(Cell() for _ in range(cols_to_add))
+            self._col_objects.extend(
+                Column(i) for i in range(current_cols, target_cols)
+            )
+
+        # 2. Add new rows with the full target_cols capacity
+        rows_to_add = target_rows - current_rows
+        if rows_to_add > 0:
+            self._cells.extend(
+                [Cell() for _ in range(target_cols)] for _ in range(rows_to_add)
+            )
+            self._row_objects.extend(Row(i) for i in range(current_rows, target_rows))
 
     def set_width(self, width: int | str) -> Self:
         """
@@ -129,7 +136,7 @@ class Table(StyledObject):
             padding: Padding around the table in pixels.
             background_color: Background color of the image.
         """
-        render_to_image(
+        save_image(
             self,
             output_path,
             dpi=dpi,

table_renderer-0.5.0/src/table_renderer/renderer.py

@@ -0,0 +1,122 @@
+"""High-level rendering facade.
+
+Orchestrates HTML generation, image rendering, and post-processing.
+Re-exports ``render_to_html`` from ``html_generator`` and delegates
+image rendering to a pluggable ``ImageRenderer`` backend.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import deprecated
+
+from .backends.base import ImageRenderer
+from .backends.weasyprint_renderer import WeasyPrintRenderer
+from .html_generator import render_to_html
+
+if TYPE_CHECKING:
+    from PIL.Image import Image
+
+    from .models.table import Table
+
+# Default backend instance, lazily initialized on first use.
+_DEFAULT_RENDERER: ImageRenderer | None = None
+
+
+def _get_default_renderer() -> ImageRenderer:
+    """Return the default renderer, creating a WeasyPrintRenderer on first call."""
+    global _DEFAULT_RENDERER
+    if _DEFAULT_RENDERER is None:
+        _DEFAULT_RENDERER = WeasyPrintRenderer()
+    return _DEFAULT_RENDERER
+
+
+def save_image(
+    table: Table,
+    output_path: str,
+    *,
+    dpi: int = 144,
+    padding: int = 10,
+    background_color: str = "transparent",
+    renderer: ImageRenderer | None = None,
+) -> None:
+    """Render the table and save to an image file.
+
+    Args:
+        table: The Table object to render.
+        output_path: Destination path for the image.
+        dpi: Target resolution.
+        padding: Margin around the table.
+        background_color: Background color of the image.
+        renderer: Optional custom rendering backend. Defaults to WeasyPrint.
+    """
+    renderer = renderer or _get_default_renderer()
+    image = renderer.render(
+        table, dpi=dpi, padding=padding, background_color=background_color
+    )
+    _write_pil_image(image, output_path)
+
+
+@deprecated("Use `save_image` instead.")
+def render_to_image(
+    table: Table,
+    output_path: str,
+    *,
+    dpi: int = 144,
+    padding: int = 10,
+    background_color: str = "transparent",
+    renderer: ImageRenderer | None = None,
+) -> None:
+    """Render the table and save to an image file.
+
+    .. deprecated::
+        Use :func:`save_image` instead.
+    """
+    import warnings
+
+    warnings.warn(
+        "render_to_image() is deprecated, use save_image() instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    save_image(
+        table,
+        output_path,
+        dpi=dpi,
+        padding=padding,
+        background_color=background_color,
+        renderer=renderer,
+    )
+
+
+def save_html(
+    table: Table, output_path: str, *, background_color: str = "transparent"
+) -> None:
+    """Save the table's HTML representation to a file.
+
+    Args:
+        table: The Table object to export.
+        output_path: Path to the destination HTML file.
+        background_color: Background color of the HTML body.
+    """
+    html_content = render_to_html(table, background_color=background_color)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(html_content)
+
+
+def _write_pil_image(image: Image, output_path: str) -> None:
+    """Handle format-specific saving (e.g., JPG alpha flattening).
+
+    Args:
+        image: A PIL Image to save.
+        output_path: Destination file path (format inferred from extension).
+    """
+    from PIL import Image
+
+    if output_path.lower().endswith((".jpg", ".jpeg")) and image.mode == "RGBA":
+        rgb_image = Image.new("RGB", image.size, (255, 255, 255))
+        rgb_image.paste(image, mask=image.split()[3])
+        image = rgb_image
+
+    image.save(output_path)

table_renderer-0.5.0/src/table_renderer/templates/table.html.j2

@@ -0,0 +1,69 @@
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+{{ extra_css }}
+{% for font in font_faces %}
+@font-face {
+  font-family: '{{ font.name }}';
+  src: url('{{ font.path }}');
+}
+{% endfor %}
+body {
+  margin: 0;
+  padding: 20px;
+  background-color: {{ background_color }};
+}
+
+table {
+  border-collapse: collapse;
+  width: {{ table_width }};
+  {{ table_style }}
+}
+
+td {
+  padding: 8px;
+  box-sizing: border-box;
+  {{ table_style }}
+}
+{% for col in columns %}
+.col-{{ col.index }} {
+  width: {{ col.width }};
+  {{ col.style }}
+}
+{% endfor %}
+{% for row in rows %}
+.row-{{ row.index }} {
+  height: {{ row.height }};
+  {{ row.style }}
+}
+{% endfor %}
+</style>
+</head>
+
+<body>
+  <table>
+    {% for r_idx in range(cells|length) %}
+    <tr class="row-{{ r_idx }}">
+      {% for c_idx in range(cells[r_idx]|length) %}
+        {% set cell = cells[r_idx][c_idx] %}
+        {% if not cell.is_merged %}
+        <td class="row-{{ r_idx }} col-{{ c_idx }}"
+          rowspan="{{ cell.row_span }}"
+          colspan="{{ cell.col_span }}"
+          style="{{ cell.style.to_css() }}">
+          {% if cell.image_url %}
+          <img src="{{ cell.image_url }}"
+             style="{% if cell.image_width %}width: {{ cell.image_width }}px;{% endif %}
+                    {% if cell.image_height %}height: {{ cell.image_height }}px;{% endif %}">
+          <br>
+          {% endif %}
+          {{ cell.value | replace('\n', '<br>') }}
+        </td>
+        {% endif %}
+      {% endfor %}
+    </tr>
+    {% endfor %}
+  </table>
+</body>
+</html>

table_renderer-0.4.0/src/table_renderer/models/row.py

@@ -1,15 +0,0 @@
-from .style import StyledObject
-
-
-class Row(StyledObject):
-    """Represents a row in a table."""
-
-    def __init__(self, index: int) -> None:
-        """
-        Initialize a row.
-
-        Args:
-            index: The 0-based index of the row.
-        """
-        super().__init__()
-        self.index = index

table_renderer-0.4.0/src/table_renderer/renderer.py

@@ -1,267 +0,0 @@
-import os
-from typing import TYPE_CHECKING
-
-from jinja2 import Template
-from weasyprint import HTML
-
-if TYPE_CHECKING:
-    from .models.table import Table
-
-HTML_TEMPLATE = """
-<!DOCTYPE html>
-<html>
-<head>
-<style>
-@page {
-    size: {{ page_width }}px {{ page_height }}px; /* Dynamically estimated size */
-    margin: 0;
-}
-body {
-    margin: 0;
-    padding: 20px;
-    background-color: {{ background_color }};
-}
-{% for font in font_faces %}
-@font-face {
-    font-family: '{{ font.name }}';
-    src: url('{{ font.path }}');
-}
-{% endfor %}
-
-table {
-    border-collapse: collapse;
-    width: {{ table_width }};
-    {{ table_style }}
-}
-
-td {
-    padding: 8px;
-    box-sizing: border-box;
-    {{ table_style }}
-}
-
-{% for col in columns %}
-.col-{{ col.index }} {
-    width: {{ col.width }};
-    {{ col.style }}
-}
-{% endfor %}
-
-{% for row in rows %}
-.row-{{ row.index }} {
-    {{ row.style }}
-}
-{% endfor %}
-</style>
-</head>
-<body>
-    <table>
-        {% for r_idx in range(cells|length) %}
-        <tr class="row-{{ r_idx }}">
-            {% for c_idx in range(cells[r_idx]|length) %}
-                {% set cell = cells[r_idx][c_idx] %}
-                {% if not cell.is_merged %}
-                <td class="row-{{ r_idx }} col-{{ c_idx }}"
-                    rowspan="{{ cell.row_span }}"
-                    colspan="{{ cell.col_span }}"
-                    style="{{ cell.style.to_css() }}">
-                    {% if cell.image_url %}
-                    <img src="{{ cell.image_url }}"
-                         style="{% if cell.image_width %}width: {{ cell.image_width }}px;{% endif %}
-                                {% if cell.image_height %}height: {{ cell.image_height }}px;{% endif %}">
-                    <br>
-                    {% endif %}
-                    {{ cell.value | replace('\\n', '<br>') }}
-                </td>
-                {% endif %}
-            {% endfor %}
-        </tr>
-        {% endfor %}
-    </table>
-</body>
-</html>
-"""
-
-
-def render_to_html(table: "Table", *, background_color: str = "transparent") -> str:
-    """
-    Generate the HTML representation of the table.
-
-    Args:
-        table: The Table object to render.
-        background_color: The background color of the body.
-
-    Returns:
-        A string containing the complete HTML document.
-    """
-    table._prepare_render()
-
-    # Calculate final styles for each cell based on inheritance
-    font_faces = []
-    for font_path in table.font_files:
-        name = os.path.splitext(os.path.basename(font_path))[0]
-        # Convert path to absolute file URL for WeasyPrint
-        abs_path = os.path.abspath(font_path)
-        font_faces.append({"name": name, "path": f"file://{abs_path}"})
-
-    cells_data = []
-    for row_index in range(len(table._cells)):
-        row_data = []
-        for col_index in range(len(table._cells[0])):
-            cell = table._cells[row_index][col_index]
-
-            # Handle Image URL resolution
-            cell.image_url = ""
-            if cell.image_path:
-                if cell.image_path.startswith(("http://", "https://")):
-                    cell.image_url = cell.image_path
-                else:
-                    abs_img_path = os.path.abspath(cell.image_path)
-                    cell.image_url = f"file://{abs_img_path}"
-
-            row_data.append(cell)
-        cells_data.append(row_data)
-
-    # Estimate safe canvas width to prevent clipping
-    # Base it on the number of columns if explicit widths aren't provided (assume ~100px min per column)
-    col_count = len(table._cells[0]) if table._cells else 0
-    estimated_width = max(2000, col_count * 100)
-
-    if isinstance(table.width, int):
-        estimated_width = max(estimated_width, table.width + 100)
-
-    col_width_sum = 0
-    for c in table._col_objects:
-        if isinstance(c.width, int):
-            col_width_sum += c.width
-    estimated_width = max(estimated_width, col_width_sum + 100)
-
-    # Estimate safe canvas height to optimize rendering speed for small tables, capped at 5000px
-    # Assume a generous average of 40px per row plus 100px padding
-    estimated_height = len(table._cells) * 40 + 100
-    estimated_height = min(max(estimated_height, 500), 5000)
-
-    template = Template(HTML_TEMPLATE)
-    return template.render(
-        page_width=estimated_width,
-        page_height=estimated_height,
-        background_color=background_color,
-        table_width=f"{table.width}px" if isinstance(table.width, int) else table.width,
-        table_style=table.style.to_css(),
-        font_faces=font_faces,
-        columns=[
-            {
-                "index": c.index,
-                "width": f"{c.width}px" if isinstance(c.width, int) else c.width,
-                "style": c.style.to_css(),
-            }
-            for c in table._col_objects
-        ],
-        rows=[
-            {"index": r.index, "style": r.style.to_css()} for r in table._row_objects
-        ],
-        cells=cells_data,
-    )
-
-
-def render_to_image(
-    table: "Table",
-    output_path: str,
-    *,
-    dpi: int = 144,
-    padding: int = 10,
-    background_color: str = "transparent",
-) -> None:
-    """
-    Render the table to an image file.
-
-    Args:
-        table: The Table object to render.
-        output_path: Destination path for the image.
-        dpi: Target resolution.
-        padding: Margin around the table.
-        background_color: Background color of the image.
-    """
-    html_content = render_to_html(table, background_color=background_color)
-    # WeasyPrint v53+ removed write_png, so we render to PDF then convert to PNG
-    pdf_bytes = HTML(string=html_content).write_pdf()
-
-    import pypdfium2 as pdfium
-    from PIL import Image
-
-    # Load the PDF from bytes
-    with pdfium.PdfDocument(pdf_bytes) as pdf:
-        page_images = []
-        scale_factor = dpi / 72
-
-        # Render each page to a PIL Image
-        for page in pdf:
-            # fill_color=(255, 255, 255, 0) ensures the background is transparent
-            bitmap = page.render(scale=scale_factor, fill_color=(255, 255, 255, 0))
-            pil_page = bitmap.to_pil()
-            page_images.append(pil_page)
-            bitmap.close()
-
-        if not page_images:
-            return
-
-        # Stitch all pages vertically into one long image
-        total_width = max(img.width for img in page_images)
-        total_height = sum(img.height for img in page_images)
-
-        # Create a large canvas
-        pil_image = Image.new("RGBA", (total_width, total_height), (255, 255, 255, 0))
-        y_offset = 0
-        for img in page_images:
-            pil_image.paste(img, (0, y_offset))
-            y_offset += img.height
-
-    # Visual Auto-Crop: Find the bounding box of non-white pixels
-    # Use 'L' (grayscale) mode to reduce memory usage (1 byte per pixel vs 3)
-    if pil_image.mode == "RGBA":
-        # Flatten RGBA onto a white grayscale background
-        grayscale = Image.new("L", pil_image.size, 255)
-        grayscale.paste(pil_image.convert("L"), mask=pil_image.getchannel("A"))
-    else:
-        # For RGB or other modes, just convert to grayscale
-        grayscale = pil_image.convert("L")
-
-    # Invert and find bbox of "ink" (non-white pixels)
-    import PIL.ImageOps
-
-    inverted = PIL.ImageOps.invert(grayscale)
-    bbox = inverted.getbbox()
-
-    if bbox:
-        # Add some padding
-        left, top, right, bottom = bbox
-        left = max(0, left - padding)
-        top = max(0, top - padding)
-        right = min(pil_image.width, right + padding)
-        bottom = min(pil_image.height, bottom + padding)
-        pil_image = pil_image.crop((left, top, right, bottom))
-
-    # Save to the requested format (Pillow handles most formats)
-    if output_path.lower().endswith((".jpg", ".jpeg")) and pil_image.mode == "RGBA":
-        # Create a white background image and paste the RGBA image on it to flatten it
-        rgb_image = Image.new("RGB", pil_image.size, (255, 255, 255))
-        rgb_image.paste(pil_image, mask=pil_image.split()[3])
-        pil_image = rgb_image
-
-    pil_image.save(output_path)
-
-
-def save_html(
-    table: "Table", output_path: str, *, background_color: str = "transparent"
-) -> None:
-    """
-    Save the table's HTML representation to a file.
-
-    Args:
-        table: The Table object to export.
-        output_path: Path to the destination HTML file.
-        background_color: Background color of the HTML body.
-    """
-    html_content = render_to_html(table, background_color=background_color)
-    with open(output_path, "w", encoding="utf-8") as f:
-        f.write(html_content)