pyWebLayout/README.md

PyWebLayout

Project Status

Badge	Description
	Test Coverage - Percentage of code covered by unit tests
	Documentation Coverage - Percentage of code with docstrings
	License - Project licensing information
A Python library for HTML-like layout and rendering.

📋 Note: Badges show results from the commit referenced in the URLs. Red "error" badges indicate build failures for that specific step.

Description

PyWebLayout is a Python library for HTML-like layout and rendering to paginated images. It provides a flexible page rendering system with support for borders, padding, text layout, and HTML parsing.

Key Features

Page Rendering System

• 📄 Flexible Page Layouts - Create pages with customizable sizes, borders, and padding
• 🎨 Styling System - Control backgrounds, border colors, and spacing
• 📐 Multiple Layouts - Support for portrait, landscape, and square pages
• 🖼️ Image Output - Render pages to PIL Images (PNG, JPEG, etc.)

Text and HTML Support

• 📝 HTML Parsing - Parse HTML content into structured document blocks
• 🔤 Font Support - Multiple font sizes, weights, and styles
• ↔️ Text Alignment - Left, center, right, and justified text
• 📖 Rich Content - Headings, paragraphs, bold, italic, and more

Architecture

• Abstract/Concrete Separation - Clean separation between content structure and rendering
• Extensible Design - Easy to extend with custom renderables
• Type-safe - Comprehensive type hints throughout the codebase

Installation

pip install pyWebLayout

Quick Start

Basic Page Rendering

from pyWebLayout.concrete.page import Page
from pyWebLayout.style.page_style import PageStyle

# Create a styled page
page_style = PageStyle(
    border_width=2,
    border_color=(200, 200, 200),
    padding=(30, 30, 30, 30),  # top, right, bottom, left
    background_color=(255, 255, 255)
)

page = Page(size=(600, 800), style=page_style)

# Render to image
image = page.render()
image.save("my_page.png")

HTML Content Parsing

from pyWebLayout.io.readers.html_extraction import parse_html_string
from pyWebLayout.style import Font

# Parse HTML to structured blocks
html = """
<h1>Document Title</h1>
<p>First paragraph with <b>bold</b> text.</p>
<p>Second paragraph with more content.</p>
"""

base_font = Font(font_size=14)
blocks = parse_html_string(html, base_font=base_font)

# blocks is a list of structured content (Paragraph, Heading, etc.)

Visual Examples

The library supports various page layouts and configurations:

Page Styles Different borders, padding, and backgrounds

HTML Content Parsed HTML with various text styles

Page Layouts Portrait, landscape, and square formats

Examples

The examples/ directory contains working demonstrations:

Getting Started

• 01_simple_page_rendering.py - Introduction to the Page system
• 02_text_and_layout.py - HTML parsing and text rendering
• 03_page_layouts.py - Different page configurations

Advanced Examples

• html_multipage_simple.py - Multi-page HTML rendering
• html_multipage_demo_final.py - Complete multi-page layout
• html_line_breaking_demo.py - Line breaking demonstration

Run any example:

cd examples
python 01_simple_page_rendering.py

See examples/README.md for detailed documentation.

Documentation

• ARCHITECTURE.md - Detailed explanation of Abstract/Concrete architecture
• examples/README.md - Complete guide to all examples
• examples/README_HTML_MULTIPAGE.md - HTML rendering guide
• API Reference - See docstrings in source code

License

MIT License

Author

Duncan Tourolle - duncan@tourolle.paris