table-renderer 0.1.0__tar.gz

table_renderer-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: table-renderer
+Version: 0.1.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
+Author-email: pTaunium <pTaunium@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: jinja2~=3.0
+Requires-Dist: pillow~=12.0
+Requires-Dist: pypdfium2~=5.0
+Requires-Dist: weasyprint>=68.1
+Requires-Python: >=3.12, <3.15
+Description-Content-Type: text/markdown
+
+# Table Renderer 📊
+
+<!-- README-I18N:START -->
+
+**English** | [繁體中文](README.zh-TW.md)
+
+<!-- README-I18N:END -->
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
+[![CI](https://github.com/pTaunium/table-renderer/actions/workflows/ci.yml/badge.svg)](https://github.com/pTaunium/table-renderer/actions)
+
+`table-renderer` is a powerful and lightweight Python library designed to convert structured tables into high-quality images (PNG, JPG, WebP) or HTML. By combining the layout power of CSS with an intuitive Python API, it's perfect for automated reporting, Kubernetes CronJobs, or any data visualization task.
+
+## ✨ Features
+
+- **Broad Compatibility**: Fully supports **Python 3.12, 3.13, and 3.14**.
+- **Business Friendly**: Uses `pypdfium2` (Apache-2.0) and `WeasyPrint` for a 100% MIT-compatible dependency chain.
+- **High-Quality Rendering**: Powered by WeasyPrint (CSS engine), supporting complex text wrapping, alignment, and cell merging.
+- **Auto-Crop**: Automatically crops images to the actual table area using visual detection, eliminating unnecessary white space.
+- **Object-Oriented API**: Clean `Table` -> `Row/Column` -> `Cell` hierarchy with fluent interface support.
+- **Cascading Styles**: Manage visual styles effortlessly with "Global Defaults + Local Overrides."
+- **Multi-language Font Support**: Support for font stacks (e.g., different fonts for English and Chinese).
+- **Customizable Resolution**: Adjustable DPI for high-resolution output (e.g., 300 DPI for print).
+- **Lightweight Deployment**: No heavy browser dependencies (like Chromium), making it ideal for Docker/K8s.
+
+---
+
+## 🖼 Visual Example
+
+Here is an example table generated using the code in the [Quick Start](#-quick-start) section:
+
+![Example Table](assets/example_table.png)
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+If you are developing within this project, use `uv`:
+
+```bash
+uv sync
+```
+
+To install it in another project:
+
+```bash
+pip install .
+```
+
+### Basic Usage
+
+```python
+from table_renderer import Table
+
+# 1. Initialize a 3x3 table
+table = Table(3, 3)
+table.set_width(600)
+table.set_border(1, "black", "solid")
+
+# 2. Set header style (Row 0)
+header = table.get_row(0)
+header.set_background("#333").set_font(color="white", weight="bold", size=16)
+header.set_align(horizontal="center")
+
+table.cell(0, 0).set_text("Product")
+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, 2).set_text("$2,000")
+
+table.cell(2, 0).set_text("Magic Mouse")
+table.cell(2, 1).set_text("Peripherals")
+table.cell(2, 2).set_text("$79")
+
+# 4. Global column styling (align prices to the right)
+table.get_column(2).set_align(horizontal="right").set_width(100)
+
+# 5. Export to image with custom DPI and padding
+table.to_image("report.png", dpi=300, padding=20)
+```
+
+---
+
+## 🛠 Advanced Features
+
+### 1. Cell Merging
+
+Use the anchor-based design to merge cells by specifying the starting cell and the span.
+
+```python
+# Merge first row, first two columns (1 row, 2 columns)
+table.cell(0, 0).span(rows=1, cols=2).set_text("Merged Header")
+```
+
+### 2. Font Management
+
+Load local font files and define font stacks for character-level fallback.
+
+```python
+# Load local font files (.ttf / .otf)
+table.add_font("./fonts/Roboto-Regular.ttf")
+table.add_font("./fonts/NotoSansTC-Medium.otf")
+
+# Define a font stack: English prefers Roboto, Chinese falls back to Noto Sans
+table.set_font(family="Roboto-Regular, NotoSansTC-Medium")
+```
+
+### 3. Embedding Images in Cells
+
+You can easily embed local images into any cell.
+
+```python
+# Set an image with optional width/height constraints
+table.cell(1, 0).set_image("path/to/logo.png", width=50)
+table.cell(1, 0).set_text("Company Logo") # Text appears below the image
+```
+
+### 4. Layout & Sizing
+
+Mix fixed widths, percentages, and auto-sizing.
+
+```python
+table.set_width(800)                  # Total table width
+table.get_column(0).set_width(200)    # Fixed 200px
+table.get_column(1).set_width("auto") # Distribute remaining space
+```
+
+### 5. DPI, Formats & Padding
+
+Fine-tune your output image quality and margins.
+
+```python
+# High-res JPG with custom 20px padding
+table.to_image("output.jpg", dpi=300, padding=20)
+
+# Lightweight WebP with tight margins
+table.to_image("output.webp", dpi=72, padding=0)
+```
+
+---
+
+## 🐳 Docker / Kubernetes Deployment
+
+Since `weasyprint` relies on system-level C libraries, your Dockerfile should include these dependencies:
+
+```dockerfile
+FROM python:3.12-slim
+
+# Install system dependencies for WeasyPrint rendering and fonts
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpango-1.0-0 \
+    libharfbuzz0b \
+    libpangoft2-1.0-0 \
+    libpangocairo-1.0-0 \
+    fonts-noto-cjk \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . .
+RUN pip install .
+
+CMD ["python", "main.py"]
+```
+
+---
+
+## 🧪 Development
+
+### Running Tests
+
+We use `pytest` for testing. Ensure you have installed the development dependencies.
+
+```bash
+uv run pytest --cov=src/table_renderer tests/
+```
+
+### Linting & Formatting
+
+We use `ruff` to maintain code quality.
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
+
+## 📜 License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.

table_renderer-0.1.0/README.md

@@ -0,0 +1,207 @@
+# Table Renderer 📊
+
+<!-- README-I18N:START -->
+
+**English** | [繁體中文](README.zh-TW.md)
+
+<!-- README-I18N:END -->
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python Version](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
+[![CI](https://github.com/pTaunium/table-renderer/actions/workflows/ci.yml/badge.svg)](https://github.com/pTaunium/table-renderer/actions)
+
+`table-renderer` is a powerful and lightweight Python library designed to convert structured tables into high-quality images (PNG, JPG, WebP) or HTML. By combining the layout power of CSS with an intuitive Python API, it's perfect for automated reporting, Kubernetes CronJobs, or any data visualization task.
+
+## ✨ Features
+
+- **Broad Compatibility**: Fully supports **Python 3.12, 3.13, and 3.14**.
+- **Business Friendly**: Uses `pypdfium2` (Apache-2.0) and `WeasyPrint` for a 100% MIT-compatible dependency chain.
+- **High-Quality Rendering**: Powered by WeasyPrint (CSS engine), supporting complex text wrapping, alignment, and cell merging.
+- **Auto-Crop**: Automatically crops images to the actual table area using visual detection, eliminating unnecessary white space.
+- **Object-Oriented API**: Clean `Table` -> `Row/Column` -> `Cell` hierarchy with fluent interface support.
+- **Cascading Styles**: Manage visual styles effortlessly with "Global Defaults + Local Overrides."
+- **Multi-language Font Support**: Support for font stacks (e.g., different fonts for English and Chinese).
+- **Customizable Resolution**: Adjustable DPI for high-resolution output (e.g., 300 DPI for print).
+- **Lightweight Deployment**: No heavy browser dependencies (like Chromium), making it ideal for Docker/K8s.
+
+---
+
+## 🖼 Visual Example
+
+Here is an example table generated using the code in the [Quick Start](#-quick-start) section:
+
+![Example Table](assets/example_table.png)
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+If you are developing within this project, use `uv`:
+
+```bash
+uv sync
+```
+
+To install it in another project:
+
+```bash
+pip install .
+```
+
+### Basic Usage
+
+```python
+from table_renderer import Table
+
+# 1. Initialize a 3x3 table
+table = Table(3, 3)
+table.set_width(600)
+table.set_border(1, "black", "solid")
+
+# 2. Set header style (Row 0)
+header = table.get_row(0)
+header.set_background("#333").set_font(color="white", weight="bold", size=16)
+header.set_align(horizontal="center")
+
+table.cell(0, 0).set_text("Product")
+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, 2).set_text("$2,000")
+
+table.cell(2, 0).set_text("Magic Mouse")
+table.cell(2, 1).set_text("Peripherals")
+table.cell(2, 2).set_text("$79")
+
+# 4. Global column styling (align prices to the right)
+table.get_column(2).set_align(horizontal="right").set_width(100)
+
+# 5. Export to image with custom DPI and padding
+table.to_image("report.png", dpi=300, padding=20)
+```
+
+---
+
+## 🛠 Advanced Features
+
+### 1. Cell Merging
+
+Use the anchor-based design to merge cells by specifying the starting cell and the span.
+
+```python
+# Merge first row, first two columns (1 row, 2 columns)
+table.cell(0, 0).span(rows=1, cols=2).set_text("Merged Header")
+```
+
+### 2. Font Management
+
+Load local font files and define font stacks for character-level fallback.
+
+```python
+# Load local font files (.ttf / .otf)
+table.add_font("./fonts/Roboto-Regular.ttf")
+table.add_font("./fonts/NotoSansTC-Medium.otf")
+
+# Define a font stack: English prefers Roboto, Chinese falls back to Noto Sans
+table.set_font(family="Roboto-Regular, NotoSansTC-Medium")
+```
+
+### 3. Embedding Images in Cells
+
+You can easily embed local images into any cell.
+
+```python
+# Set an image with optional width/height constraints
+table.cell(1, 0).set_image("path/to/logo.png", width=50)
+table.cell(1, 0).set_text("Company Logo") # Text appears below the image
+```
+
+### 4. Layout & Sizing
+
+Mix fixed widths, percentages, and auto-sizing.
+
+```python
+table.set_width(800)                  # Total table width
+table.get_column(0).set_width(200)    # Fixed 200px
+table.get_column(1).set_width("auto") # Distribute remaining space
+```
+
+### 5. DPI, Formats & Padding
+
+Fine-tune your output image quality and margins.
+
+```python
+# High-res JPG with custom 20px padding
+table.to_image("output.jpg", dpi=300, padding=20)
+
+# Lightweight WebP with tight margins
+table.to_image("output.webp", dpi=72, padding=0)
+```
+
+---
+
+## 🐳 Docker / Kubernetes Deployment
+
+Since `weasyprint` relies on system-level C libraries, your Dockerfile should include these dependencies:
+
+```dockerfile
+FROM python:3.12-slim
+
+# Install system dependencies for WeasyPrint rendering and fonts
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpango-1.0-0 \
+    libharfbuzz0b \
+    libpangoft2-1.0-0 \
+    libpangocairo-1.0-0 \
+    fonts-noto-cjk \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . .
+RUN pip install .
+
+CMD ["python", "main.py"]
+```
+
+---
+
+## 🧪 Development
+
+### Running Tests
+
+We use `pytest` for testing. Ensure you have installed the development dependencies.
+
+```bash
+uv run pytest --cov=src/table_renderer tests/
+```
+
+### Linting & Formatting
+
+We use `ruff` to maintain code quality.
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
+
+## 📜 License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.

table_renderer-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "table-renderer"
+version = "0.1.0"
+description = "A Python library for rendering structured tables as high-quality images or HTML."
+readme = "README.md"
+license = "MIT"
+authors = [
+  { name = "pTaunium", email = "pTaunium@gmail.com" }
+]
+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",
+  "weasyprint>=68.1",
+]
+
+
+[dependency-groups]
+dev = [
+  "ipython",
+  "pytest~=9.0",
+  "pytest-cov~=7.0",
+  "ruff~=0.15",
+  "ty>=0.0.41",
+]
+
+[tool.ruff]
+line-length = 88
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+  "E",     # pycodestyle error
+  "W",     # pycodestyle warning
+  "I",     # isort
+  "N",     # pep8-naming
+  "F",     # Pyflakes
+  "C90",   # McCabe
+  "ANN",   # flake8-annotations
+  "ASYNC", # flake8-async
+  "S",     # flake8-bandit
+  "B",     # flake8-bugbear
+  "A",     # flake8-builtins
+  "C4",    # flake8-comprehensions
+  "PIE",   # flake8-pie
+  "PT",    # flake8-pytest-style
+  "RET",   # flake8-return
+  "SIM",   # flake8-simplify
+  "PERF",  # Perflint
+  "FURB",  # refurb
+  "UP",    # pyupgrade
+  "RUF",   # Ruff-specific rules
+]
+ignore = [
+  "E501", # line-too-long
+]
+
+[tool.ruff.lint.isort]
+section-order = [
+  "future",
+  "standard-library",
+  "third-party",
+  "first-party",
+  "local-folder",
+]
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+  "S101", # assert
+  "S105", # hardcoded-password-string
+  "S106", # hardcoded-password-func-arg
+  "S107", # hardcoded-password-default
+]
+
+[tool.coverage.run]
+source = ["src"]

table_renderer-0.1.0/src/table_renderer/__init__.py

@@ -0,0 +1,3 @@
+from .models import Cell, Column, Row, Style, StyledObject, Table
+
+__all__ = ["Cell", "Column", "Row", "Style", "StyledObject", "Table"]

table_renderer-0.1.0/src/table_renderer/models/__init__.py

@@ -0,0 +1,8 @@
+from .base import StyledObject
+from .cell import Cell
+from .column import Column
+from .row import Row
+from .style import Style
+from .table import Table
+
+__all__ = ["Cell", "Column", "Row", "Style", "StyledObject", "Table"]

table_renderer-0.1.0/src/table_renderer/models/base.py

@@ -0,0 +1,90 @@
+from typing import Literal, Self
+
+from .style import Style
+
+
+class StyledObject:
+    """Base class for objects that can be styled."""
+
+    def __init__(self) -> None:
+        """Initialize with a default Style."""
+        self.style = Style()
+
+    def set_font(
+        self,
+        size: int | None = None,
+        color: str | None = None,
+        family: str | None = None,
+        weight: Literal["normal", "bold"] | None = None,
+    ) -> Self:
+        """
+        Set font related styles.
+
+        Args:
+            size: Font size in pixels.
+            color: Text color (e.g., 'red', '#ff0000').
+            family: Font family or font stack.
+            weight: 'normal' or 'bold'.
+
+        Returns:
+            The object itself for chaining.
+        """
+        self.style.font_size = size or self.style.font_size
+        self.style.font_color = color or self.style.font_color
+        self.style.font_family = family or self.style.font_family
+        self.style.font_weight = weight or self.style.font_weight
+        return self
+
+    def set_background(self, color: str) -> Self:
+        """
+        Set the background color.
+
+        Args:
+            color: Background color.
+
+        Returns:
+            The object itself for chaining.
+        """
+        self.style.bg_color = color
+        return self
+
+    def set_align(
+        self,
+        horizontal: Literal["left", "center", "right"] | None = None,
+        vertical: Literal["top", "middle", "bottom"] | None = None,
+    ) -> Self:
+        """
+        Set text alignment.
+
+        Args:
+            horizontal: Horizontal alignment.
+            vertical: Vertical alignment.
+
+        Returns:
+            The object itself for chaining.
+        """
+        self.style.text_align = horizontal or self.style.text_align
+        self.style.vertical_align = vertical or self.style.vertical_align
+        return self
+
+    def set_border(
+        self,
+        width: int | None = None,
+        color: str | None = None,
+        style: Literal["solid", "dashed", "dotted"] | None = None,
+    ) -> Self:
+        """
+        Set border styles.
+
+        Args:
+            width: Border width in pixels.
+            color: Border color.
+            style: Border style.
+
+        Returns:
+            The object itself for chaining.
+        """
+        self.style.border_width = width or self.style.border_width
+        self.style.border_color = color or self.style.border_color
+        self.style.border_style = style or self.style.border_style
+        return self

table_renderer-0.1.0/src/table_renderer/models/cell.py

@@ -0,0 +1,72 @@
+from typing import Self
+
+from .base import StyledObject
+
+
+class Cell(StyledObject):
+    """Represents a single cell in a table."""
+
+    def __init__(self, value: str = "") -> None:
+        """
+        Initialize cell with a value.
+
+        Args:
+            value: The text content of the cell.
+        """
+        super().__init__()
+        self.value = value
+        self.row_span = 1
+        self.col_span = 1
+        self.is_merged = False  # If True, this cell is covered by another merged cell
+        self.final_style: str = ""
+        self.image_path: str | None = None
+        self.image_url: str = ""
+        self.image_width: int | None = None
+        self.image_height: int | None = None
+
+    def set_text(self, text: str) -> Self:
+        """
+        Update the text content of the cell.
+
+        Args:
+            text: New text content.
+
+        Returns:
+            The cell itself for chaining.
+        """
+        self.value = text
+        return self
+
+    def set_image(
+        self, path: str, width: int | None = None, height: int | None = None
+    ) -> Self:
+        """
+        Set an image to be displayed in the cell.
+
+        Args:
+            path: Path to the image file.
+            width: Optional display width in pixels.
+            height: Optional display height in pixels.
+
+        Returns:
+            The cell itself for chaining.
+        """
+        self.image_path = path
+        self.image_width = width
+        self.image_height = height
+        return self
+
+    def span(self, rows: int = 1, cols: int = 1) -> Self:
+        """
+        Set the row and column span for merging.
+
+        Args:
+            rows: Number of rows to span.
+            cols: Number of columns to span.
+
+        Returns:
+            The cell itself for chaining.
+        """
+        self.row_span = rows
+        self.col_span = cols
+        return self

table_renderer-0.1.0/src/table_renderer/models/column.py

@@ -0,0 +1,31 @@
+from typing import Self
+
+from .base import StyledObject
+
+
+class Column(StyledObject):
+    """Represents a column in a table."""
+
+    def __init__(self, index: int) -> None:
+        """
+        Initialize a column.
+
+        Args:
+            index: The 0-based index of the column.
+        """
+        super().__init__()
+        self.index = index
+        self.width: int | str = "auto"
+
+    def set_width(self, width: int | str) -> Self:
+        """
+        Set the width of the column.
+
+        Args:
+            width: Width in pixels (int) or CSS value (str, e.g., '10%').
+
+        Returns:
+            The column itself for chaining.
+        """
+        self.width = width
+        return self

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

@@ -0,0 +1,15 @@
+from .base 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.1.0/src/table_renderer/models/style.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class Style:
+    """Represents the visual style of a table element."""
+
+    font_size: int | None = None
+    font_color: str | None = None
+    font_family: str | None = None
+    font_weight: Literal["normal", "bold"] | None = None
+    bg_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
+    border_color: str | None = None
+    border_style: Literal["solid", "dashed", "dotted"] | None = None
+
+    # Detailed borders
+    border_top_width: int | None = None
+    border_top_color: str | None = None
+    border_top_style: Literal["solid", "dashed", "dotted"] | None = None
+
+    border_bottom_width: int | None = None
+    border_bottom_color: str | None = None
+    border_bottom_style: Literal["solid", "dashed", "dotted"] | None = None
+
+    border_left_width: int | None = None
+    border_left_color: str | None = None
+    border_left_style: Literal["solid", "dashed", "dotted"] | None = None
+
+    border_right_width: int | None = None
+    border_right_color: str | None = None
+    border_right_style: Literal["solid", "dashed", "dotted"] | None = None
+
+    def merge(self, other: "Style") -> "Style":
+        """
+        Merge another style into this one.
+
+        Args:
+            other: The style to merge. Attributes in 'other' take precedence.
+
+        Returns:
+            A new Style instance containing the merged attributes.
+        """
+        merged_style = Style(**self.__dict__)
+        for k, v in other.__dict__.items():
+            if v is not None:
+                setattr(merged_style, k, v)
+        return merged_style
+
+    def to_css(self) -> str:
+        """
+        Convert style attributes to a CSS string.
+
+        Returns:
+            A string containing CSS property-value pairs.
+        """
+        css = []
+        # Basic styles
+        if self.font_size:
+            css.append(f"font-size: {self.font_size}px;")
+        if self.font_color:
+            css.append(f"color: {self.font_color};")
+        if self.font_family:
+            # Handle font stacks: "Arial, Noto Sans" -> "'Arial', 'Noto Sans'"
+            families = [
+                f"'{f.strip()}'" if "'" not in f and '"' not in f else f.strip()
+                for f in self.font_family.split(",")
+            ]
+            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.text_align:
+            css.append(f"text-align: {self.text_align};")
+        if self.vertical_align:
+            css.append(f"vertical-align: {self.vertical_align};")
+
+        # Borders
+        css.extend(self._get_border_css())
+        return " ".join(css)
+
+    def _get_border_css(self) -> list[str]:
+        """Internal helper to generate border CSS."""
+        css = []
+        if self.border_width:
+            css.append(f"border-width: {self.border_width}px;")
+        if self.border_color:
+            css.append(f"border-color: {self.border_color};")
+        if self.border_style:
+            css.append(f"border-style: {self.border_style};")
+
+        # Individual borders
+        for side in ["top", "bottom", "left", "right"]:
+            width = getattr(self, f"border_{side}_width")
+            color = getattr(self, f"border_{side}_color")
+            style = getattr(self, f"border_{side}_style")
+            if width:
+                css.append(f"border-{side}-width: {width}px;")
+            if color:
+                css.append(f"border-{side}-color: {color};")
+            if style:
+                css.append(f"border-{side}-style: {style};")
+        return css

table_renderer-0.1.0/src/table_renderer/models/table.py

@@ -0,0 +1,162 @@
+from typing import Self
+
+from table_renderer.renderer import render_to_image, save_html
+
+from .base import StyledObject
+from .cell import Cell
+from .column import Column
+from .row import Row
+
+
+class Table(StyledObject):
+    """The main class representing a table to be rendered."""
+
+    def __init__(self, rows: int = 0, cols: int = 0) -> None:
+        """
+        Initialize a table with initial dimensions.
+
+        Args:
+            rows: Initial number of rows.
+            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)]
+        self.width: int | str = "100%"
+        self.font_files: list[str] = []
+
+    def cell(self, row_index: int, col_index: int) -> Cell:
+        """
+        Get a cell at specific coordinates. Grows the table if needed.
+
+        Args:
+            row_index: Row index.
+            col_index: Column index.
+
+        Returns:
+            The Cell object.
+        """
+        while row_index >= len(self._cells):
+            self._add_row()
+        while col_index >= len(self._cells[0]):
+            self._add_col()
+        return self._cells[row_index][col_index]
+
+    def get_row(self, row_index: int) -> Row:
+        """
+        Get a Row object. Grows the table if needed.
+
+        Args:
+            row_index: Row index.
+
+        Returns:
+            The Row object.
+        """
+        while row_index >= len(self._row_objects):
+            self._add_row()
+        return self._row_objects[row_index]
+
+    def get_column(self, col_index: int) -> Column:
+        """
+        Get a Column object. Grows the table if needed.
+
+        Args:
+            col_index: Column index.
+
+        Returns:
+            The Column object.
+        """
+        while col_index >= len(self._col_objects):
+            self._add_col()
+        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 set_width(self, width: int | str) -> Self:
+        """
+        Set the total width of the table.
+
+        Args:
+            width: Width in pixels or CSS value.
+
+        Returns:
+            The table itself for chaining.
+        """
+        self.width = width
+        return self
+
+    def add_font(self, font_path: str) -> Self:
+        """
+        Register a local font file.
+
+        Args:
+            font_path: Path to the .ttf or .otf file.
+
+        Returns:
+            The table itself for chaining.
+        """
+        self.font_files.append(font_path)
+        return self
+
+    def to_image(self, output_path: str, dpi: int = 144, padding: int = 10) -> None:
+        """
+        Render the table to an image file.
+
+        Args:
+            output_path: Path to the output file (e.g., 'table.png', 'table.webp').
+            dpi: Resolution of the output image.
+            padding: Padding around the table in pixels.
+        """
+        render_to_image(self, output_path, dpi=dpi, padding=padding)
+
+    def to_html(self, output_path: str) -> None:
+        """
+        Export the table to an HTML file.
+
+        Args:
+            output_path: Path to the output HTML file.
+        """
+        save_html(self, output_path)
+
+    def _prepare_render(self) -> None:
+        """Handle merging logic and cascading styles before rendering."""
+        # Reset is_merged flags
+        for row_index in range(len(self._cells)):
+            for col_index in range(len(self._cells[0])):
+                self._cells[row_index][col_index].is_merged = False
+
+        # Mark merged cells
+        for row_index in range(len(self._cells)):
+            for col_index in range(len(self._cells[0])):
+                self._mark_merged_area(row_index, col_index)
+
+    def _mark_merged_area(self, row_index: int, col_index: int) -> None:
+        """Mark cells covered by a span as merged."""
+        cell = self._cells[row_index][col_index]
+        if cell.is_merged:
+            return
+        if cell.row_span > 1 or cell.col_span > 1:
+            for d_row in range(cell.row_span):
+                for d_col in range(cell.col_span):
+                    if d_row == 0 and d_col == 0:
+                        continue
+                    if row_index + d_row < len(self._cells) and col_index + d_col < len(
+                        self._cells[0]
+                    ):
+                        self._cells[row_index + d_row][
+                            col_index + d_col
+                        ].is_merged = True

table_renderer-0.1.0/src/table_renderer/renderer.py

@@ -0,0 +1,219 @@
+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 {
+    margin: 0;
+}
+body {
+    margin: 0;
+    padding: 20px;
+    background-color: transparent;
+}
+{% 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;
+}
+
+{% 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="col-{{ c_idx }}"
+                    rowspan="{{ cell.row_span }}"
+                    colspan="{{ cell.col_span }}"
+                    style="{{ cell.final_style }}">
+                    {% 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") -> str:
+    """
+    Generate the HTML representation of the table.
+
+    Args:
+        table: The Table object to render.
+
+    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]
+            row = table.get_row(row_index)
+            col = table.get_column(col_index)
+
+            # Cascading: Table -> Row/Col -> Cell
+            base_style = table.style.merge(col.style).merge(row.style)
+            final_style = base_style.merge(cell.style)
+
+            # Handle Image URL resolution
+            cell.image_url = ""
+            if cell.image_path:
+                abs_img_path = os.path.abspath(cell.image_path)
+                cell.image_url = f"file://{abs_img_path}"
+
+            # Attach final style string for template
+            cell.final_style = final_style.to_css()
+            row_data.append(cell)
+        cells_data.append(row_data)
+
+    template = Template(HTML_TEMPLATE)
+    return template.render(
+        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,
+) -> 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.
+    """
+    html_content = render_to_html(table)
+    # 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 = pdf[0]
+
+        # Render page to a bitmap
+        # scale_factor: 72 is the default PDF DPI
+        scale_factor = dpi / 72
+        bitmap = page.render(scale=scale_factor)
+
+        # Convert pdfium bitmap to Pillow Image
+        pil_image = bitmap.to_pil()
+        bitmap.close()
+
+    # Visual Auto-Crop: Find the bounding box of non-white pixels
+    # 1. Convert to RGB to ensure we have a standard background to check
+    bg = Image.new("RGB", pil_image.size, (255, 255, 255))
+    if pil_image.mode == "RGBA":
+        bg.paste(pil_image, mask=pil_image.split()[3])
+    else:
+        bg.paste(pil_image)
+
+    # 2. Invert and find bbox of "ink"
+    import PIL.ImageOps
+
+    inverted = PIL.ImageOps.invert(bg)
+    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)
+    pil_image.save(output_path)
+
+
+def save_html(table: "Table", output_path: str) -> 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.
+    """
+    html_content = render_to_html(table)
+    with open(output_path, "w", encoding="utf-8") as f:
+        f.write(html_content)