table-renderer 0.1.0

A Python library for rendering structured tables as high-quality images or HTML.

Table Renderer 📊

English | 繁體中文

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 section:

---

🚀 Quick Start

Installation

If you are developing within this project, use uv:

uv sync

To install it in another project:

pip install .

Basic Usage

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.

# 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.

# 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.

# 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.

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.

# 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:

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.

uv run pytest --cov=src/table_renderer tests/

Linting & Formatting

We use ruff to maintain code quality.

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 for more information.