# PyWebLayout

## Project Status


| Badge | Description |
|-------|-------------|
| ![Test Coverage](https://gitea.tourolle.paris/dtourolle/pyWebLayout/raw/branch/badges/cov_info/coverage.svg) | **Test Coverage** - Percentage of code covered by unit tests |
| ![Documentation Coverage](https://gitea.tourolle.paris/dtourolle/pyWebLayout/raw/branch/badges/cov_info/coverage-docs.svg) | **Documentation Coverage** - Percentage of code with docstrings |
| ![License](https://img.shields.io/badge/license-MIT-blue.svg) | **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

```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="33%">
      <b>Page Styles</b><br>
      <img src="docs/images/example_01_page_rendering.png" width="250" alt="Page Rendering"><br>
      <em>Different borders, padding, and backgrounds</em>
    </td>
    <td align="center" width="33%">
      <b>HTML Content</b><br>
      <img src="docs/images/example_02_text_and_layout.png" width="250" alt="Text Layout"><br>
      <em>Parsed HTML with various text styles</em>
    </td>
    <td align="center" width="33%">
      <b>Page Layouts</b><br>
      <img src="docs/images/example_03_page_layouts.png" width="250" alt="Page Layouts"><br>
      <em>Portrait, landscape, and square formats</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

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