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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: table-renderer
-Version: 0.4.0
+Version: 0.6.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.6.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.6.0/pyproject.toml

@@ -0,0 +1,105 @@
+[build-system]
+requires = ["uv_build>=0.11.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "table-renderer"
+version = "0.6.0"
+description = "A Python library for rendering structured tables as high-quality images or HTML."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12,<3.15"
+keywords = [
+    "table",
+    "renderer",
+    "rendering",
+    "image",
+    "html",
+    "weasyprint",
+    "pdfium",
+    "report",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "jinja2~=3.0",
+    "pillow~=12.0",
+    "pypdfium2~=5.0",
+    "typing-extensions>=4.5.0",
+    "weasyprint>=68.1",
+]
+
+[[project.authors]]
+name = "pTaunium"
+email = "pTaunium@gmail.com"
+
+[dependency-groups]
+dev = [
+    "ipython",
+    "pytest~=9.0",
+    "pytest-cov~=7.0",
+    "ruff~=0.17",
+    "ty>=0.0.95",
+]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "I",
+    "N",
+    "F",
+    "C90",
+    "ANN",
+    "ASYNC",
+    "S",
+    "B",
+    "A",
+    "C4",
+    "PIE",
+    "PT",
+    "RET",
+    "SIM",
+    "PERF",
+    "FURB",
+    "UP",
+    "RUF",
+]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+section-order = [
+    "future",
+    "standard-library",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",
+    "S105",
+    "S106",
+    "S107",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.coverage.run]
+source = ["src"]

table_renderer-0.4.0/pyproject.toml → table_renderer-0.6.0/pyproject.toml.orig

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.11.0,<0.12.0"]
+requires = ["uv_build>=0.11.0,<0.14.0"]
 build-backend = "uv_build"
 
 [project]
 name = "table-renderer"
-version = "0.4.0"
+version = "0.6.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",
 ]
 
@@ -36,13 +37,15 @@ dev = [
   "ipython",
   "pytest~=9.0",
   "pytest-cov~=7.0",
-  "ruff~=0.15",
-  "ty>=0.0.41",
+  "ruff~=0.17",
+  "ty>=0.0.95",
 ]
 
 [tool.ruff]
 line-length = 88
 indent-width = 4
+# Keep hand-aligned comments in README code blocks.
+extend-exclude = ["*.md"]
 
 [tool.ruff.lint]
 select = [

table_renderer-0.6.0/src/table_renderer/__init__.py

@@ -0,0 +1,33 @@
+import importlib.metadata
+
+from .models import Cell, Column, Row, Style, StyledObject, Table
+from .resolved_table import (
+    FontFace,
+    ResolvedCell,
+    ResolvedColumn,
+    ResolvedRow,
+    ResolvedTable,
+    resolve_table,
+)
+
+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.6.0"
+
+__all__ = [
+    "Cell",
+    "Column",
+    "FontFace",
+    "ResolvedCell",
+    "ResolvedColumn",
+    "ResolvedRow",
+    "ResolvedTable",
+    "Row",
+    "Style",
+    "StyledObject",
+    "Table",
+    "__version__",
+    "resolve_table",
+]

table_renderer-0.6.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.6.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.6.0/src/table_renderer/backends/geometry.py

@@ -0,0 +1,287 @@
+"""Layout geometry calculations for table rendering.
+
+This module is a deep module that encapsulates all unit-conversion,
+length-parsing, page-size estimation, overflow checks, and crop-box
+calculations. It deals purely with numbers and ResolvedTable dimensions,
+independent of any PDF engine or browser renderer.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from table_renderer.resolved_table import ResolvedTable
+
+CSS_DPI: int = 96
+PDF_DPI: int = 72
+DEFAULT_COL_WIDTH_PX: int = 100
+MIN_PAGE_WIDTH_PX: int = 200
+DEFAULT_BODY_PADDING_CSS_PX: int = 20
+BODY_PADDING_BUFFER_CSS_PX: int = 4
+WIDTH_MARGIN_ALLOWANCE_CSS_PX: int = 20
+HEIGHT_SAFETY_BUFFER_CSS_PX: int = 100
+INITIAL_PAGE_HEIGHT_CSS_PX: int = 1_000_000
+BORDER_SLACK_DEV_PX: int = 1
+MAX_BODY_PADDING_ALIGNMENT_STEP_CSS_PX: int = 8
+
+
+@dataclass(slots=True)
+class TableBounds:
+    """Bounding box of a rendered table in CSS pixels."""
+
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+@dataclass(slots=True)
+class PageDimensions:
+    """Dimensions of a rendering canvas/page in CSS pixels."""
+
+    width: int
+    height: int
+    body_padding_css_px: int
+
+
+def parse_pixel_length(value: int | str) -> int | None:
+    """Parse an integer or CSS pixel length string into integer pixels.
+
+    Args:
+        value: An integer pixel value or CSS length string (e.g., ``"1200px"``).
+
+    Returns:
+        Positive integer pixel count, or ``None`` if not a pixel value.
+    """
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value if value > 0 else None
+    if isinstance(value, str):
+        stripped = value.strip().lower()
+        if stripped.endswith("px"):
+            stripped = stripped[:-2].strip()
+        try:
+            parsed = float(stripped)
+        except ValueError:
+            return None
+        if parsed > 0 and math.isfinite(parsed):
+            return math.ceil(parsed)
+    return None
+
+
+def compute_body_padding_css_px(*, dpi: int, padding: int) -> int:
+    """Compute the CSS body padding required to accommodate device-pixel padding.
+
+    Args:
+        dpi: Target resolution in dots per inch.
+        padding: Padding in device pixels.
+
+    Returns:
+        CSS body padding in pixels.
+    """
+    device_px_per_css_px = dpi / CSS_DPI
+    raw_body_padding_css_px = max(
+        DEFAULT_BODY_PADDING_CSS_PX,
+        math.ceil(max(0, padding) / device_px_per_css_px) + BODY_PADDING_BUFFER_CSS_PX,
+    )
+    # Align CSS body padding to device pixel grid, capping alignment step to avoid runaway page expansion
+    body_padding_alignment_step_css_px = min(
+        MAX_BODY_PADDING_ALIGNMENT_STEP_CSS_PX,
+        CSS_DPI // math.gcd(dpi, CSS_DPI),
+    )
+    return (
+        math.ceil(raw_body_padding_css_px / body_padding_alignment_step_css_px)
+        * body_padding_alignment_step_css_px
+    )
+
+
+def estimate_page_width(
+    resolved: ResolvedTable,
+    *,
+    body_padding_css_px: int = DEFAULT_BODY_PADDING_CSS_PX,
+) -> int:
+    """Estimate the required table page width in CSS pixels.
+
+    Args:
+        resolved: The ResolvedTable to measure.
+        body_padding_css_px: CSS body padding in pixels.
+
+    Returns:
+        Estimated page width in CSS pixels.
+    """
+    margin_allowance_css_px = body_padding_css_px * 2 + WIDTH_MARGIN_ALLOWANCE_CSS_PX
+    if not resolved.cells:
+        return max(MIN_PAGE_WIDTH_PX, margin_allowance_css_px)
+
+    parsed_table_width = parse_pixel_length(resolved.width)
+    if parsed_table_width is not None:
+        return max(MIN_PAGE_WIDTH_PX, parsed_table_width + margin_allowance_css_px)
+
+    total_width_css_px = 0
+    for col in resolved.columns:
+        parsed_col_width = parse_pixel_length(col.width)
+        if parsed_col_width is not None:
+            total_width_css_px += parsed_col_width
+        else:
+            total_width_css_px += DEFAULT_COL_WIDTH_PX
+
+    return max(MIN_PAGE_WIDTH_PX, total_width_css_px + margin_allowance_css_px)
+
+
+def estimate_page_dimensions(
+    resolved: ResolvedTable,
+    *,
+    dpi: int,
+    padding: int,
+) -> PageDimensions:
+    """Estimate initial continuous page dimensions for a table.
+
+    Args:
+        resolved: The ResolvedTable to measure.
+        dpi: Target resolution in dots per inch.
+        padding: Requested image padding in device pixels.
+
+    Returns:
+        PageDimensions with width, initial page height, and body padding.
+    """
+    body_padding_css_px = compute_body_padding_css_px(dpi=dpi, padding=padding)
+    width = estimate_page_width(resolved, body_padding_css_px=body_padding_css_px)
+    return PageDimensions(
+        width=width,
+        height=INITIAL_PAGE_HEIGHT_CSS_PX,
+        body_padding_css_px=body_padding_css_px,
+    )
+
+
+def build_page_css(dimensions: PageDimensions) -> str:
+    """Build ``@page`` and ``html body`` CSS rules for continuous layout.
+
+    Args:
+        dimensions: The target page dimensions and padding.
+
+    Returns:
+        CSS string suitable for injection into ``extra_css``.
+    """
+    return (
+        "@page {\n"
+        f"    size: {dimensions.width}px {dimensions.height}px;\n"
+        "    margin: 0;\n"
+        "}\n"
+        "html body {\n"
+        f"    padding: {dimensions.body_padding_css_px}px;\n"
+        "}"
+    )
+
+
+def compute_relayout_dimensions(
+    bounds: Sequence[TableBounds],
+    page_count: int,
+    current_dimensions: PageDimensions,
+) -> PageDimensions | None:
+    """Determine if re-layout is needed and return the expanded dimensions.
+
+    Args:
+        bounds: Measured bounds for table instances across pages.
+        page_count: Number of pages generated in the layout pass.
+        current_dimensions: Current page dimensions.
+
+    Returns:
+        Expanded PageDimensions if relayout is needed and dimensions change,
+        or ``None`` if current dimensions are sufficient.
+    """
+    if not bounds:
+        return None
+
+    max_right_css_px = max(b.x + b.width for b in bounds)
+    total_height_css_px = sum(b.height for b in bounds)
+
+    needed_width_css_px = math.ceil(
+        max_right_css_px + current_dimensions.body_padding_css_px
+    )
+    needed_height_css_px = math.ceil(
+        total_height_css_px
+        + current_dimensions.body_padding_css_px * 2
+        + HEIGHT_SAFETY_BUFFER_CSS_PX
+    )
+
+    target_width = max(current_dimensions.width, needed_width_css_px)
+    target_height = max(current_dimensions.height, needed_height_css_px)
+
+    if (
+        page_count > 1
+        or target_width > current_dimensions.width
+        or target_height > current_dimensions.height
+    ):
+        if page_count > 1 and target_height <= current_dimensions.height:
+            target_height = current_dimensions.height + HEIGHT_SAFETY_BUFFER_CSS_PX
+
+        return PageDimensions(
+            width=target_width,
+            height=target_height,
+            body_padding_css_px=current_dimensions.body_padding_css_px,
+        )
+
+    return None
+
+
+def compute_crop_box_px(
+    bounds: TableBounds, *, dpi: int, padding: int
+) -> tuple[int, int, int, int]:
+    """Compute device-pixel crop bounding box from TableBounds.
+
+    Args:
+        bounds: Measured TableBounds in CSS pixels.
+        dpi: Target resolution in dots per inch.
+        padding: Padding around the table in device pixels.
+
+    Returns:
+        Tuple of ``(left, top, right, bottom)`` in device pixels.
+    """
+    device_px_per_css_px = dpi / CSS_DPI
+    pad = max(0, padding)
+
+    table_left_px = math.floor(bounds.x * device_px_per_css_px)
+    table_top_px = math.floor(bounds.y * device_px_per_css_px)
+
+    # Compute absolute right/bottom edges with outward slack for anti-aliased borders
+    table_right_px = (
+        math.ceil((bounds.x + bounds.width) * device_px_per_css_px)
+        + BORDER_SLACK_DEV_PX
+    )
+    table_bottom_px = (
+        math.ceil((bounds.y + bounds.height) * device_px_per_css_px)
+        + BORDER_SLACK_DEV_PX
+    )
+
+    left = max(0, table_left_px - pad)
+    top = max(0, table_top_px - pad)
+    right = table_right_px + pad
+    bottom = table_bottom_px + pad
+    return left, top, right, bottom
+
+
+def compute_bbox_padding_px(
+    bbox: tuple[int, int, int, int], *, padding: int
+) -> tuple[int, int, int, int]:
+    """Apply device-pixel padding around a device-pixel bounding box.
+
+    Args:
+        bbox: Raw bounding box ``(left, top, right, bottom)`` in device pixels.
+        padding: Padding around content in device pixels.
+
+    Returns:
+        Tuple of ``(left, top, right, bottom)`` with padding applied.
+    """
+    pad = max(0, padding)
+    min_x, min_y, max_x, max_y = bbox
+    return (
+        max(0, min_x - pad),
+        max(0, min_y - pad),
+        max_x + pad,
+        max_y + pad,
+    )