dtourolleandClaude Opus 5
1924cc234d
PageBuffer started a ProcessPoolExecutor(max_workers=4) and submitted page
renders to it. Every job failed. _render_page_worker returned
pickle.dumps(page), and a Page holds a live PIL canvas, which is not
picklable, so check_completed_renders swallowed a TypeError into a bare
print and cached nothing. The cost was paid in full for zero benefit:
four interpreter copies plus the whole block list shipped per job (~880KB
for a 200-block document).
Three further defects would have had to be fixed before it could ever
have worked: the worker built its BidirectionalLayouter without page_size
so it silently used the (800, 600) default; check_completed_renders
cached every result with is_backward=False, so backward renders landed in
the forward buffer; and both _queue_*_renders broke at the end of their
first loop body, queueing one page each despite looping buffer_size
times.
Two live defects go with it:
R1 - on Python 3.14 the default start method became forkserver, so
submit() reaches _check_not_importing_main() and raises unless the
caller sits inside an `if __name__ == "__main__"` guard.
EreaderLayoutManager.get_current_page() raised outright from ordinary
module-level script code.
R2 - PageBuffer.__del__ called executor.shutdown(wait=True). Blocking
on a process pool from a finaliser at interpreter teardown deadlocked;
the test suite finished in 11.5s and then never exited.
S12's measurement gate, on the tests/data Wikipedia fixture (411 blocks)
with text caches warm:
800x600 p50 8.8 ms p95 15.4 ms
1072x1448 p50 13.8 ms p95 56.1 ms
A page turn is cheaper than the IPC meant to hide it, so the gate says
delete rather than replace. The LRU buffers, position maps and
invalidation logic are kept unchanged; only the executor, worker,
pickling, prefetch queueing and the lock guarding the pending-render dict
are removed. If a slower device ever changes the numbers, the fallback is
a synchronous readahead() method or a single worker thread, not
processes.
EreaderLayoutManager.shutdown() becomes idempotent and its __del__ no
longer propagates exceptions - it was doing bookmark file I/O during
interpreter teardown.
Adds tests/layout/test_page_buffer.py, which the module had none of:
LRU eviction and position-map cleanup, cache hits, font-scale
invalidation, backward round-trip, and subprocess regressions for R1
(no __main__ guard) and R2 (exit without explicit shutdown).
870 passed, and the suite now exits in 12s wall instead of hanging.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
- 🎨 Dynamic Font Families - Switch between Sans, Serif, and Monospace fonts on-the-fly
- ↔️ 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
- 🔘 Interactive Elements - Buttons, forms, and links with callback support
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 |
Table Rendering HTML tables with headers and styling |
Interactive Elements Buttons, forms, and callback binding |
|
🆕 Pagination & PageBreak Multi-page documents with explicit and automatic breaks |
🆕 Link Navigation All 4 link types: Internal, External, API, Function |
🆕 Comprehensive Forms All 14 form field types with validation |
|
🆕 Dynamic Font Family Switching Switch between Sans, Serif, and Monospace fonts instantly |
|
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
- 04_table_rendering.py - HTML table rendering with styling
- 05_html_table_with_images.py - Tables with embedded images
- 06_functional_elements_demo.py - Interactive buttons and forms with callbacks
- 08_bundled_fonts_demo.py - Using the bundled DejaVu font families
🆕 Advanced Features (NEW)
- 08_pagination_demo.py - Multi-page documents with PageBreak (11 tests)
- 09_link_navigation_demo.py - All link types and navigation (10 tests)
- 10_forms_demo.py - All 14 form field types (9 tests)
- 11_font_family_switching_demo.py - 🆕 Dynamic font switching in ereader
Run any example:
cd examples
python 01_simple_page_rendering.py
python 08_pagination_demo.py # NEW: Multi-page documents
All new examples include comprehensive test coverage! Run tests with:
python -m pytest tests/examples/ -v # 30 tests, all passing ✅
Coverage Impact: The new examples fill critical documentation gaps:
- PageBreak: 0% → 100% (had NO examples before)
- LinkText: 14% → 100% (all 4 link types demonstrated)
- FormFields: 14% → 100% (all 14 field types demonstrated)
See examples/README.md for detailed documentation.
Font Family Switching (NEW ✨)
PyWebLayout now supports dynamic font family switching in the ereader, allowing readers to change fonts on-the-fly without losing their reading position!
Quick Example
from pyWebLayout.style.fonts import BundledFont
from pyWebLayout.layout.ereader_manager import create_ereader_manager
# Create an ereader
manager = create_ereader_manager(blocks, page_size=(600, 800))
# Switch to serif font
manager.set_font_family(BundledFont.SERIF)
# Switch to monospace font
manager.set_font_family(BundledFont.MONOSPACE)
# Restore original fonts
manager.set_font_family(None)
# Query current font
current = manager.get_font_family()
Features
- 3 Bundled Fonts: Sans, Serif, and Monospace (DejaVu font family)
- Instant Switching: Change fonts without recreating the document
- Position Preservation: Reading position maintained across font changes
- Attribute Preservation: Bold, italic, size, and color are preserved
- Smart Caching: Automatic cache invalidation for optimal performance
Learn more: See FONT_SWITCHING_FEATURE.md for complete documentation.
Documentation
- ARCHITECTURE.md - Abstract/Concrete architecture guide
- FONT_SWITCHING_FEATURE.md - 🆕 Font family switching guide
- examples/README.md - Complete examples guide with tests
- docs/images/README.md - Visual documentation index
- pyWebLayout/layout/README_EREADER_API.md - EbookReader API reference
- API Reference - See docstrings in source code
License
MIT License
Author
Duncan Tourolle - duncan@tourolle.paris