154 lines
5.4 KiB
Markdown
154 lines
5.4 KiB
Markdown
# 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
|
|
- 📊 **Table Rendering** - Full HTML table support with headers, borders, and styling
|
|
|
|
### 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
|
|
|
|
```bash
|
|
pip install pyWebLayout
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Basic Page Rendering
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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:
|
|
|
|
<table>
|
|
<tr>
|
|
<td align="center" width="50%">
|
|
<b>Page Styles</b><br>
|
|
<img src="docs/images/example_01_page_rendering.png" width="300" alt="Page Rendering"><br>
|
|
<em>Different borders, padding, and backgrounds</em>
|
|
</td>
|
|
<td align="center" width="50%">
|
|
<b>HTML Content</b><br>
|
|
<img src="docs/images/example_02_text_and_layout.png" width="300" alt="Text Layout"><br>
|
|
<em>Parsed HTML with various text styles</em>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="50%">
|
|
<b>Page Layouts</b><br>
|
|
<img src="docs/images/example_03_page_layouts.png" width="300" alt="Page Layouts"><br>
|
|
<em>Portrait, landscape, and square formats</em>
|
|
</td>
|
|
<td align="center" width="50%">
|
|
<b>Table Rendering</b><br>
|
|
<img src="docs/images/example_04_table_rendering.png" width="300" alt="Table Rendering"><br>
|
|
<em>HTML tables with headers and styling</em>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
## Examples
|
|
|
|
The `examples/` directory contains working demonstrations:
|
|
|
|
### Getting Started
|
|
- **[01_simple_page_rendering.py](examples/01_simple_page_rendering.py)** - Introduction to the Page system
|
|
- **[02_text_and_layout.py](examples/02_text_and_layout.py)** - HTML parsing and text rendering
|
|
- **[03_page_layouts.py](examples/03_page_layouts.py)** - Different page configurations
|
|
- **[04_table_rendering.py](examples/04_table_rendering.py)** - HTML table rendering with styling
|
|
- **[05_table_with_images.py](examples/05_table_with_images.py)** - Tables with embedded images
|
|
|
|
### Advanced Examples
|
|
- **[html_multipage_simple.py](examples/html_multipage_simple.py)** - Multi-page HTML rendering
|
|
- **[html_multipage_demo_final.py](examples/html_multipage_demo_final.py)** - Complete multi-page layout
|
|
- **[html_line_breaking_demo.py](examples/html_line_breaking_demo.py)** - Line breaking demonstration
|
|
|
|
Run any example:
|
|
```bash
|
|
cd examples
|
|
python 01_simple_page_rendering.py
|
|
```
|
|
|
|
See **[examples/README.md](examples/README.md)** for detailed documentation.
|
|
|
|
## Documentation
|
|
|
|
- **[ARCHITECTURE.md](ARCHITECTURE.md)** - Detailed explanation of Abstract/Concrete architecture
|
|
- **[examples/README.md](examples/README.md)** - Complete guide to all examples
|
|
- **[examples/README_HTML_MULTIPAGE.md](examples/README_HTML_MULTIPAGE.md)** - HTML rendering guide
|
|
- **API Reference** - See docstrings in source code
|
|
|
|
## License
|
|
|
|
MIT License
|
|
|
|
## Author
|
|
|
|
Duncan Tourolle - duncan@tourolle.paris
|