Chapter One

101 # Add chapters to the book

102 self._add_chapters()

104 # Process images for e-ink display optimization

105 self._process_content_images()

107 return self.book

109 finally:

110 # Clean up temporary files

111 if self.temp_dir:

112 import shutil

113 shutil.rmtree(self.temp_dir, ignore_errors=True)

115 def _extract_epub(self):

116 """Extract the EPUB file to a temporary directory."""

117 with zipfile.ZipFile(self.epub_path, 'r') as zip_ref:

118 zip_ref.extractall(self.temp_dir)

119

120 # Find the content directory (typically OEBPS or OPS)

121 container_path = os.path.join(self.temp_dir, 'META-INF', 'container.xml')

122 if os.path.exists(container_path): 122 ↛ 136line 122 didn't jump to line 136 because the condition on line 122 was always true

123 tree = ET.parse(container_path)

124 root = tree.getroot()

126 # Get the path to the package document (content.opf)

127 for rootfile in root.findall( 127 ↛ 136line 127 didn't jump to line 136 because the loop on line 127 didn't complete

128 './/{urn:oasis:names:tc:opendocument:xmlns:container}rootfile'):

129 full_path = rootfile.get('full-path')

130 if full_path: 130 ↛ 127line 130 didn't jump to line 127 because the condition on line 130 was always true

131 self.content_dir = os.path.dirname(

132 os.path.join(self.temp_dir, full_path))

133 return

135 # Fallback: look for common content directories

136 for content_dir in ['OEBPS', 'OPS', 'Content']:

137 if os.path.exists(os.path.join(self.temp_dir, content_dir)):

138 self.content_dir = os.path.join(self.temp_dir, content_dir)

139 return

141 # If no content directory found, use the root

142 self.content_dir = self.temp_dir

143

144 def _parse_package_document(self):

145 """Parse the package document (content.opf)."""

146 # Find the package document

147 opf_path = None

148 for root, dirs, files in os.walk(self.content_dir): 148 ↛ 156line 148 didn't jump to line 156 because the loop on line 148 didn't complete

149 for file in files: 149 ↛ 153line 149 didn't jump to line 153 because the loop on line 149 didn't complete

150 if file.endswith('.opf'):

151 opf_path = os.path.join(root, file)

152 break

153 if opf_path: 153 ↛ 148line 153 didn't jump to line 148 because the condition on line 153 was always true

154 break

156 if not opf_path: 156 ↛ 157line 156 didn't jump to line 157 because the condition on line 156 was never true

157 raise ValueError("No package document (.opf) found in EPUB")

159 # Parse the package document

160 tree = ET.parse(opf_path)

161 root = tree.getroot()

162

163 # Parse metadata

164 self._parse_metadata(root)

166 # Parse manifest

167 self._parse_manifest(root)

169 # Parse spine

170 self._parse_spine(root)

172 def _parse_metadata(self, root: ET.Element):

173 """

174 Parse metadata from the package document.

175

176 Args:

177 root: Root element of the package document

178 """

179 # Find the metadata element

180 metadata_elem = root.find('.//{{{0}}}metadata'.format(NAMESPACES['opf']))

181 if metadata_elem is None: 181 ↛ 182line 181 didn't jump to line 182 because the condition on line 181 was never true

182 return

184 # Parse DC metadata

185 for elem in metadata_elem:

186 if elem.tag.startswith('{{{0}}}'.format(NAMESPACES['dc'])):

187 # Get the local name (without namespace)

188 name = elem.tag.split('}', 1)[1]

189 value = elem.text

191 if name == 'title':

192 self.metadata['title'] = value

193 elif name == 'creator':

194 self.metadata['creator'] = value

195 elif name == 'language':

196 self.metadata['language'] = value

197 elif name == 'description':

198 self.metadata['description'] = value

199 elif name == 'subject':

200 if 'subjects' not in self.metadata:

201 self.metadata['subjects'] = []

202 self.metadata['subjects'].append(value)

203 elif name == 'date':

204 self.metadata['date'] = value

205 elif name == 'identifier':

206 self.metadata['identifier'] = value

207 elif name == 'publisher':

208 self.metadata['publisher'] = value

209 else:

210 # Store other metadata

211 self.metadata[name] = value

212

213 # Parse meta elements for cover reference

214 for meta in metadata_elem.findall('.//{{{0}}}meta'.format(NAMESPACES['opf'])):

215 name = meta.get('name')

216 content = meta.get('content')

218 if name == 'cover' and content: 218 ↛ 220line 218 didn't jump to line 220 because the condition on line 218 was never true

219 # This is a reference to the cover image in the manifest

220 self.cover_id = content

221

222 def _parse_manifest(self, root: ET.Element):

223 """

224 Parse manifest from the package document.

226 Args:

227 root: Root element of the package document

228 """

229 # Find the manifest element

230 manifest_elem = root.find('.//{{{0}}}manifest'.format(NAMESPACES['opf']))

231 if manifest_elem is None: 231 ↛ 232line 231 didn't jump to line 232 because the condition on line 231 was never true

232 return

234 # Parse items

235 for item in manifest_elem.findall('.//{{{0}}}item'.format(NAMESPACES['opf'])):

236 id = item.get('id')

237 href = item.get('href')

238 media_type = item.get('media-type')

240 if id and href: 240 ↛ 235line 240 didn't jump to line 235 because the condition on line 240 was always true

241 # Resolve relative path

242 href = urllib.parse.unquote(href)

243 path = os.path.normpath(os.path.join(self.content_dir, href))

245 self.manifest[id] = {

246 'href': href,

247 'path': path,

248 'media_type': media_type

249 }

251 def _parse_spine(self, root: ET.Element):

252 """

253 Parse spine from the package document.

254

255 Args:

256 root: Root element of the package document

257 """

258 # Find the spine element

259 spine_elem = root.find('.//{{{0}}}spine'.format(NAMESPACES['opf']))

260 if spine_elem is None: 260 ↛ 261line 260 didn't jump to line 261 because the condition on line 260 was never true

261 return

262

263 # Get the toc attribute (NCX file ID)

264 toc_id = spine_elem.get('toc')

265 if toc_id and toc_id in self.manifest: 265 ↛ 269line 265 didn't jump to line 269 because the condition on line 265 was always true

266 self.toc_path = self.manifest[toc_id]['path']

268 # Parse itemrefs

269 for itemref in spine_elem.findall(

270 './/{{{0}}}itemref'.format(NAMESPACES['opf'])):

271 idref = itemref.get('idref')

272 if idref and idref in self.manifest: 272 ↛ 269line 272 didn't jump to line 269 because the condition on line 272 was always true

273 self.spine.append(idref)

275 def _parse_toc(self):

276 """Parse the table of contents."""

277 if not hasattr( 277 ↛ 282line 277 didn't jump to line 282 because the condition on line 277 was never true

278 self,

279 'toc_path') or not self.toc_path or not os.path.exists(

280 self.toc_path):

281 # Try to find the toc.ncx file

282 for root, dirs, files in os.walk(self.content_dir):

283 for file in files:

284 if file.endswith('.ncx'):

285 self.toc_path = os.path.join(root, file)

286 break

287 if hasattr(self, 'toc_path') and self.toc_path:

288 break

290 if not hasattr( 290 ↛ 295line 290 didn't jump to line 295 because the condition on line 290 was never true

291 self,

292 'toc_path') or not self.toc_path or not os.path.exists(

293 self.toc_path):

294 # No TOC found

295 return

297 # Parse the NCX file

298 tree = ET.parse(self.toc_path)

299 root = tree.getroot()

301 # Parse navMap

302 nav_map = root.find('.//{{{0}}}navMap'.format(NAMESPACES['ncx']))

303 if nav_map is None: 303 ↛ 304line 303 didn't jump to line 304 because the condition on line 303 was never true

304 return

306 # Parse navPoints

307 self._parse_nav_points(nav_map, [])

309 def _parse_nav_points(self, parent: ET.Element, path: List[Dict[str, Any]]):

310 """

311 Recursively parse navPoints from the NCX file.

313 Args:

314 parent: Parent element containing navPoints

315 path: Current path in the TOC hierarchy

316 """

317 for nav_point in parent.findall('.//{{{0}}}navPoint'.format(NAMESPACES['ncx'])):

318 # Get navPoint attributes

319 id = nav_point.get('id')

320 play_order = nav_point.get('playOrder')

322 # Get navLabel

323 nav_label = nav_point.find('.//{{{0}}}navLabel'.format(NAMESPACES['ncx']))

324 text_elem = nav_label.find(

325 './/{{{0}}}text'.format(NAMESPACES['ncx'])) if nav_label else None

326 label = text_elem.text if text_elem is not None else ""

327

328 # Get content

329 content = nav_point.find('.//{{{0}}}content'.format(NAMESPACES['ncx']))

330 src = content.get('src') if content is not None else ""

332 # Create a TOC entry

333 entry = {

334 'id': id,

335 'label': label,

336 'src': src,

337 'play_order': play_order,

338 'children': []

339 }

341 # Add to TOC

342 if path: 342 ↛ 343line 342 didn't jump to line 343 because the condition on line 342 was never true

343 path[-1]['children'].append(entry)

344 else:

345 self.toc.append(entry)

347 # Parse child navPoints

348 self._parse_nav_points(nav_point, path + [entry])

349

350 def _create_book(self):

351 """Create a Book object from the parsed metadata."""

352 # Set book metadata

353 if 'title' in self.metadata: 353 ↛ 356line 353 didn't jump to line 356 because the condition on line 353 was always true

354 self.book.set_title(self.metadata['title'])

355

356 if 'creator' in self.metadata:

357 self.book.set_metadata(MetadataType.AUTHOR, self.metadata['creator'])

359 if 'language' in self.metadata:

360 self.book.set_metadata(MetadataType.LANGUAGE, self.metadata['language'])

362 if 'description' in self.metadata:

363 self.book.set_metadata(

364 MetadataType.DESCRIPTION,

365 self.metadata['description'])

367 if 'subjects' in self.metadata:

368 self.book.set_metadata(

369 MetadataType.KEYWORDS, ', '.join(

370 self.metadata['subjects']))

371

372 if 'date' in self.metadata:

373 self.book.set_metadata(MetadataType.PUBLICATION_DATE, self.metadata['date'])

375 if 'identifier' in self.metadata: 375 ↛ 378line 375 didn't jump to line 378 because the condition on line 375 was always true

376 self.book.set_metadata(MetadataType.IDENTIFIER, self.metadata['identifier'])

378 if 'publisher' in self.metadata:

379 self.book.set_metadata(MetadataType.PUBLISHER, self.metadata['publisher'])

380

381 def _add_cover_chapter(self):

382 """Add a cover chapter if a cover image is available."""

383 if not self.cover_id or self.cover_id not in self.manifest: 383 ↛ 387line 383 didn't jump to line 387 because the condition on line 383 was always true

384 return

385

386 # Get the cover image path from the manifest

387 cover_item = self.manifest[self.cover_id]

388 cover_path = cover_item['path']

389

390 # Check if the file exists

391 if not os.path.exists(cover_path):

392 print(f"Warning: Cover image file not found: {cover_path}")

393 return

395 # Create a cover chapter

396 cover_chapter = self.book.create_chapter("Cover", 0)

398 try:

399 # Create an Image block for the cover

400 from pyWebLayout.abstract.block import Image as AbstractImage

401 from PIL import Image as PILImage

402 import io

403

404 # Load the image into memory before the temp directory is cleaned up

405 # We need to fully copy the image data to ensure it persists after temp

406 # cleanup

407 with open(cover_path, 'rb') as f:

408 image_bytes = f.read()

410 # Create PIL image from bytes in memory

411 pil_image = PILImage.open(io.BytesIO(image_bytes))

412 pil_image.load() # Force loading into memory

414 # Create a copy to ensure all data is in memory

415 pil_image = pil_image.copy()

416

417 # Apply image processing if enabled

418 if self.image_processor:

419 try:

420 pil_image = self.image_processor(pil_image)

421 except Exception as e:

422 print(f"Warning: Image processing failed for cover: {str(e)}")

423 # Continue with unprocessed image

425 # Create an AbstractImage block with the cover image path

426 cover_image = AbstractImage(source=cover_path, alt_text="Cover Image")

428 # Set dimensions from the loaded image

429 cover_image._width = pil_image.width

430 cover_image._height = pil_image.height

432 # Store the loaded PIL image in the abstract image so it persists after

433 # temp cleanup

434 cover_image._loaded_image = pil_image

436 # Add the image to the cover chapter

437 cover_chapter.add_block(cover_image)

438

439 except Exception as e:

440 print(f"Error creating cover chapter: {str(e)}")

441 import traceback

442 traceback.print_exc()

443 # If we can't create the cover image, remove the chapter

444 if hasattr(self.book, 'chapters') and cover_chapter in self.book.chapters:

445 self.book.chapters.remove(cover_chapter)

447 def _process_chapter_images(self, chapter: Chapter):

448 """

449 Load and process images in a single chapter.

450

451 This method loads images from disk into memory and applies image processing.

452 Images must be loaded before the temporary EPUB directory is cleaned up.

453

454 Args:

455 chapter: The chapter containing images to process

456 """

457 from pyWebLayout.abstract.block import Image as AbstractImage

458 from PIL import Image as PILImage

459 import io

461 for block in chapter.blocks:

462 if isinstance(block, AbstractImage):

463 # Load image into memory if not already loaded

464 if not hasattr(block, '_loaded_image') or not block._loaded_image: 464 ↛ 485line 464 didn't jump to line 485 because the condition on line 464 was always true

465 try:

466 # Load the image from the source path

467 if os.path.isfile(block.source): 467 ↛ 485line 467 didn't jump to line 485 because the condition on line 467 was always true

468 with open(block.source, 'rb') as f:

469 image_bytes = f.read()

470 # Create PIL image from bytes in memory

471 pil_image = PILImage.open(io.BytesIO(image_bytes))

472 pil_image.load() # Force loading into memory

473 block._loaded_image = pil_image.copy() # Create a copy to ensure it persists

475 # Set width and height on the block from the loaded image

476 # This is required for layout calculations

477 block._width = pil_image.width

478 block._height = pil_image.height

479 except Exception as e:

480 print(f"Warning: Failed to load image '{block.source}': {str(e)}")

481 # Continue without the image

482 continue

483

484 # Apply image processing if enabled and image is loaded

485 if self.image_processor and hasattr(block, '_loaded_image') and block._loaded_image:

486 try:

487 block._loaded_image = self.image_processor(block._loaded_image)

488 except Exception as e:

489 print(

490 f"Warning: Image processing failed for image '{block.alt_text}': {str(e)}"

491 )

492 # Continue with unprocessed image

493

494 def _process_content_images(self):

495 """

496 Load all images into memory and apply image processing.

497

498 This must be called before the temporary EPUB directory is cleaned up,

499 to ensure images are loaded from disk into memory.

500 """

501 for chapter in self.book.chapters:

502 self._process_chapter_images(chapter)

504 def _add_chapters(self):

505 """Add chapters to the book based on the spine and TOC."""

506 # Add cover chapter first if available

507 self._add_cover_chapter()

508

509 # Create a mapping from src to TOC entry

510 toc_map = {}

512 def add_to_toc_map(entries):

513 for entry in entries:

514 if entry['src']: 514 ↛ 521line 514 didn't jump to line 521 because the condition on line 514 was always true

515 # Extract the path part of the src (remove fragment)

516 src_parts = entry['src'].split('#', 1)

517 path = src_parts[0]

518 toc_map[path] = entry

519

520 # Process children

521 if entry['children']: 521 ↛ 522line 521 didn't jump to line 522 because the condition on line 521 was never true

522 add_to_toc_map(entry['children'])

523

524 add_to_toc_map(self.toc)

526 # Process spine items

527 # Start from chapter_index = 1 if cover was added, otherwise 0

528 chapter_index = 1 if (self.cover_id and self.cover_id in self.manifest) else 0

529 for i, idref in enumerate(self.spine):

530 if idref not in self.manifest: 530 ↛ 531line 530 didn't jump to line 531 because the condition on line 530 was never true

531 continue

532

533 item = self.manifest[idref]

534 path = item['path']

535 href = item['href']

536

537 # Skip navigation files

538 if (idref == 'nav' or

539 item.get('media_type') == 'application/xhtml+xml' and

540 ('nav' in href.lower() or 'toc' in href.lower())):

541 continue

542

543 # Check if this item is in the TOC

544 chapter_title = None

545 if href in toc_map: 545 ↛ 549line 545 didn't jump to line 549 because the condition on line 545 was always true

546 chapter_title = toc_map[href]['label']

547

548 # Create a chapter

549 chapter_index += 1

550 chapter = self.book.create_chapter(chapter_title, chapter_index)

551

552 # Parse the HTML content

553 try:

554 # Read the HTML file

555 with open(path, 'r', encoding='utf-8') as f:

556 html = f.read()

557

558 # Get the directory of the HTML file for resolving relative paths

559 html_dir = os.path.dirname(path)

560

561 # Parse HTML and add blocks to chapter, passing base_path for image resolution

562 blocks = parse_html_string(html, document=self.book, base_path=html_dir)

563

564 # Copy blocks to the chapter

565 for block in blocks:

566 chapter.add_block(block)

567

568 # Add a PageBreak after the chapter to ensure next chapter starts on new page

569 # This helps maintain chapter boundaries during pagination

570 chapter.add_block(PageBreak())

571

572 except Exception as e:

573 print(f"Error parsing chapter {i + 1}: {str(e)}")

574 # Add an error message block

575 from pyWebLayout.abstract.block import Paragraph

576 from pyWebLayout.abstract.inline import Word

577 from pyWebLayout.style import Font

578 error_para = Paragraph()

579 # Create a default font style for the error message

580 default_font = Font()

581 error_para.add_word(

582 Word(

583 f"Error loading chapter: {str(e)}",

584 default_font

585 )

586 )

587 chapter.add_block(error_para)

588 # Still add PageBreak even after error

589 chapter.add_block(PageBreak())

590

591

592def read_epub(epub_path: str) -> Book:

593 """

594 Read an EPUB file and convert it to a Book.

595

596 Args:

597 epub_path: Path to the EPUB file

598

599 Returns:

600 Book: The parsed book

601 """

602 reader = EPUBReader(epub_path)

603 return reader.read()

+ + + diff --git a/cov_info/htmlcov/z_263f2e628cef8c50_html_extraction_py.html b/cov_info/htmlcov/z_263f2e628cef8c50_html_extraction_py.html new file mode 100644 index 0000000..009e038 --- /dev/null +++ b/cov_info/htmlcov/z_263f2e628cef8c50_html_extraction_py.html @@ -0,0 +1,1067 @@ + + + + + Coverage for pyWebLayout/io/readers/html_extraction.py: 89% + + + + + +

+ Coverage for pyWebLayout/io/readers/html_extraction.py: + 89% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 400 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2HTML extraction module for converting HTML elements to pyWebLayout abstract elements.

4This module provides handler functions for converting HTML elements into the abstract document structure

5used by pyWebLayout, including paragraphs, headings, lists, tables, and inline formatting.

6Each handler function has a robust signature that handles style hints, CSS classes, and attributes.

7"""

9from typing import List, Dict, Any, Optional, Union, Callable, Tuple, NamedTuple

10from bs4 import BeautifulSoup, Tag, NavigableString

11from bs4.element import CData, Comment, Doctype, ProcessingInstruction

12from pyWebLayout.abstract.inline import Word

13from pyWebLayout.abstract.block import (

14 Block,

15 Paragraph,

16 Heading,

17 HeadingLevel,

18 Quote,

19 CodeBlock,

20 HList,

21 ListItem,

22 ListStyle,

23 Table,

24 TableRow,

25 TableCell,

26 HorizontalRule,

27 Image,

28)

29from pyWebLayout.style import Font, FontWeight, FontStyle, TextDecoration

32class StyleContext(NamedTuple):

33 """

34 Immutable style context passed to handler functions.

35 Contains all styling information including inherited styles, CSS hints, and element attributes.

36 """

38 font: Font

39 background: Optional[Tuple[int, int, int, int]]

40 css_classes: set

41 css_styles: Dict[str, str]

42 element_attributes: Dict[str, Any]

43 parent_elements: List[str] # Stack of parent element names

44 document: Optional[Any] # Reference to document for font registry

45 base_path: Optional[str] = None # Base path for resolving relative URLs

47 def with_font(self, font: Font) -> "StyleContext":

48 """Create new context with modified font."""

49 return self._replace(font=font)

51 def with_background(

52 self, background: Optional[Tuple[int, int, int, int]]

53 ) -> "StyleContext":

54 """Create new context with modified background."""

55 return self._replace(background=background)

57 def with_css_classes(self, css_classes: set) -> "StyleContext":

58 """Create new context with modified CSS classes."""

59 return self._replace(css_classes=css_classes)

61 def with_css_styles(self, css_styles: Dict[str, str]) -> "StyleContext":

62 """Create new context with modified CSS styles."""

63 return self._replace(css_styles=css_styles)

65 def with_attributes(self, attributes: Dict[str, Any]) -> "StyleContext":

66 """Create new context with modified element attributes."""

67 return self._replace(element_attributes=attributes)

69 def push_element(self, element_name: str) -> "StyleContext":

70 """Create new context with element pushed onto parent stack."""

71 return self._replace(parent_elements=self.parent_elements + [element_name])

74def create_base_context(

75 base_font: Optional[Font] = None,

76 document=None,

77 base_path: Optional[str] = None) -> StyleContext:

78 """

79 Create a base style context with default values.

81 Args:

82 base_font: Base font to use, defaults to system default

83 document: Document instance for font registry

84 base_path: Base directory path for resolving relative URLs

86 Returns:

87 StyleContext with default values

88 """

89 # Use document's font registry if available, otherwise create default font

90 if base_font is None:

91 if document and hasattr(document, 'get_or_create_font'):

92 base_font = document.get_or_create_font()

93 else:

94 base_font = Font()

96 return StyleContext(

97 font=base_font,

98 background=None,

99 css_classes=set(),

100 css_styles={},

101 element_attributes={},

102 parent_elements=[],

103 document=document,

104 base_path=base_path,

105 )

108def apply_element_styling(context: StyleContext, element: Tag) -> StyleContext:

109 """

110 Apply element-specific styling to context based on HTML element and attributes.

112 Args:

113 context: Current style context

114 element: BeautifulSoup Tag object

116 Returns:

117 New StyleContext with applied styling

118 """

119 tag_name = element.name.lower()

120 attributes = dict(element.attrs) if element.attrs else {}

122 # Start with current context

123 new_context = context.with_attributes(attributes).push_element(tag_name)

125 # Apply CSS classes

126 css_classes = new_context.css_classes.copy()

127 if "class" in attributes:

128 classes = (

129 attributes["class"].split()

130 if isinstance(attributes["class"], str)

131 else attributes["class"]

132 )

133 css_classes.update(classes)

134 new_context = new_context.with_css_classes(css_classes)

136 # Apply inline styles

137 css_styles = new_context.css_styles.copy()

138 if "style" in attributes:

139 inline_styles = parse_inline_styles(attributes["style"])

140 css_styles.update(inline_styles)

141 new_context = new_context.with_css_styles(css_styles)

143 # Apply element-specific default styles

144 font = apply_element_font_styles(

145 new_context.font, tag_name, css_styles, new_context)

146 new_context = new_context.with_font(font)

148 # Apply background from styles

149 background = apply_background_styles(new_context.background, css_styles)

150 new_context = new_context.with_background(background)

152 return new_context

153

155def parse_inline_styles(style_text: str) -> Dict[str, str]:

156 """

157 Parse CSS inline styles into dictionary.

159 Args:

160 style_text: CSS style text (e.g., "color: red; font-weight: bold;")

162 Returns:

163 Dictionary of CSS property-value pairs

164 """

165 styles = {}

166 for declaration in style_text.split(";"):

167 if ":" in declaration:

168 prop, value = declaration.split(":", 1)

169 styles[prop.strip().lower()] = value.strip()

170 return styles

172

173def apply_element_font_styles(font: Font,

174 tag_name: str,

175 css_styles: Dict[str,

176 str],

177 context: Optional[StyleContext] = None) -> Font:

178 """

179 Apply font styling based on HTML element and CSS styles.

180 Uses document's font registry when available to avoid creating duplicate fonts.

182 Args:

183 font: Current font

184 tag_name: HTML tag name

185 css_styles: CSS styles dictionary

186 context: Style context with document reference for font registry

188 Returns:

189 Font object with applied styling (either existing or newly created)

190 """

191 # Default element styles

192 element_font_styles = {

193 "b": {"weight": FontWeight.BOLD},

194 "strong": {"weight": FontWeight.BOLD},

195 "i": {"style": FontStyle.ITALIC},

196 "em": {"style": FontStyle.ITALIC},

197 "u": {"decoration": TextDecoration.UNDERLINE},

198 "s": {"decoration": TextDecoration.STRIKETHROUGH},

199 "del": {"decoration": TextDecoration.STRIKETHROUGH},

200 "h1": {"size": 24, "weight": FontWeight.BOLD},

201 "h2": {"size": 20, "weight": FontWeight.BOLD},

202 "h3": {"size": 18, "weight": FontWeight.BOLD},

203 "h4": {"size": 16, "weight": FontWeight.BOLD},

204 "h5": {"size": 14, "weight": FontWeight.BOLD},

205 "h6": {"size": 12, "weight": FontWeight.BOLD},

206 }

208 # Start with current font properties

209 font_size = font.font_size

210 colour = font.colour

211 weight = font.weight

212 style = font.style

213 decoration = font.decoration

214 background = font.background

215 language = font.language

216 font_path = font._font_path

218 # Apply element default styles

219 if tag_name in element_font_styles:

220 elem_styles = element_font_styles[tag_name]

221 if "size" in elem_styles:

222 font_size = elem_styles["size"]

223 if "weight" in elem_styles:

224 weight = elem_styles["weight"]

225 if "style" in elem_styles:

226 style = elem_styles["style"]

227 if "decoration" in elem_styles:

228 decoration = elem_styles["decoration"]

230 # Apply CSS styles (override element defaults)

231 if "font-size" in css_styles:

232 # Parse font-size (simplified - could be enhanced)

233 size_value = css_styles["font-size"].lower()

234 if size_value.endswith("px"):

235 try:

236 font_size = int(float(size_value[:-2]))

237 except ValueError:

238 pass

239 elif size_value.endswith("pt"): 239 ↛ 240line 239 didn't jump to line 240 because the condition on line 239 was never true

240 try:

241 font_size = int(float(size_value[:-2]))

242 except ValueError:

243 pass

245 if "font-weight" in css_styles:

246 weight_value = css_styles["font-weight"].lower()

247 if weight_value in ["bold", "700", "800", "900"]: 247 ↛ 249line 247 didn't jump to line 249 because the condition on line 247 was always true

248 weight = FontWeight.BOLD

249 elif weight_value in ["normal", "400"]:

250 weight = FontWeight.NORMAL

252 if "font-style" in css_styles:

253 style_value = css_styles["font-style"].lower()

254 if style_value == "italic":

255 style = FontStyle.ITALIC

256 elif style_value == "normal": 256 ↛ 259line 256 didn't jump to line 259 because the condition on line 256 was always true

257 style = FontStyle.NORMAL

259 if "text-decoration" in css_styles:

260 decoration_value = css_styles["text-decoration"].lower()

261 if "underline" in decoration_value:

262 decoration = TextDecoration.UNDERLINE

263 elif "line-through" in decoration_value: 263 ↛ 264line 263 didn't jump to line 264 because the condition on line 263 was never true

264 decoration = TextDecoration.STRIKETHROUGH

265 elif "none" in decoration_value: 265 ↛ 268line 265 didn't jump to line 268 because the condition on line 265 was always true

266 decoration = TextDecoration.NONE

268 if "color" in css_styles:

269 # Parse color (simplified - could be enhanced for hex, rgb, etc.)

270 color_value = css_styles["color"].lower()

271 color_map = {

272 "black": (0, 0, 0),

273 "white": (255, 255, 255),

274 "red": (255, 0, 0),

275 "green": (0, 255, 0),

276 "blue": (0, 0, 255),

277 }

278 if color_value in color_map:

279 colour = color_map[color_value]

280 elif color_value.startswith("#") and len(color_value) == 7:

281 try:

282 r = int(color_value[1:3], 16)

283 g = int(color_value[3:5], 16)

284 b = int(color_value[5:7], 16)

285 colour = (r, g, b)

286 except ValueError:

287 pass

288

289 # Use document's style registry if available to avoid creating duplicate styles

290 if context and context.document and hasattr(

291 context.document, 'get_or_create_style'):

292 # Create an abstract style first

293 from pyWebLayout.style.abstract_style import FontFamily, FontSize

295 # Map font properties to abstract style properties

296 font_family = FontFamily.SERIF # Default - could be enhanced to detect from font_path

297 if font_size: 297 ↛ 301line 297 didn't jump to line 301 because the condition on line 297 was always true

298 font_size_value = font_size if isinstance(

299 font_size, int) else FontSize.MEDIUM

300 else:

301 font_size_value = FontSize.MEDIUM

302

303 # Create abstract style and register it

304 style_id, abstract_style = context.document.get_or_create_style(

305 font_family=font_family,

306 font_size=font_size_value,

307 font_weight=weight,

308 font_style=style,

309 text_decoration=decoration,

310 color=colour,

311 language=language

312 )

313

314 # Get the concrete font for this style

315 return context.document.get_font_for_style(abstract_style)

316 elif context and context.document and hasattr(context.document, 'get_or_create_font'): 316 ↛ 318line 316 didn't jump to line 318 because the condition on line 316 was never true

317 # Fallback to old font registry system

318 return context.document.get_or_create_font(

319 font_path=font_path,

320 font_size=font_size,

321 colour=colour,

322 weight=weight,

323 style=style,

324 decoration=decoration,

325 background=background,

326 language=language,

327 min_hyphenation_width=font.min_hyphenation_width

328 )

329 else:

330 # Fallback to creating new font if no document context

331 return Font(

332 font_path=font_path,

333 font_size=font_size,

334 colour=colour,

335 weight=weight,

336 style=style,

337 decoration=decoration,

338 background=background,

339 language=language,

340 )

342

343def apply_background_styles(

344 current_background: Optional[Tuple[int, int, int, int]], css_styles: Dict[str, str]

345) -> Optional[Tuple[int, int, int, int]]:

346 """

347 Apply background styling from CSS.

349 Args:

350 current_background: Current background color (RGBA)

351 css_styles: CSS styles dictionary

353 Returns:

354 New background color or None

355 """

356 if "background-color" in css_styles:

357 bg_value = css_styles["background-color"].lower()

358 if bg_value == "transparent": 358 ↛ 359line 358 didn't jump to line 359 because the condition on line 358 was never true

359 return None

360 # Add color parsing logic here if needed

362 return current_background

364

365def extract_text_content(element: Tag, context: StyleContext) -> List[Word]:

366 """

367 Extract text content from an element, handling inline formatting and links.

368

369 Args:

370 element: BeautifulSoup Tag object

371 context: Current style context

373 Returns:

374 List of Word objects (including LinkedWord for hyperlinks)

375 """

376 return extract_words_from_nodes(list(element.children), context)

379def extract_words_from_nodes(nodes: List, context: StyleContext) -> List[Word]:

380 """

381 Extract words from a sequence of sibling nodes.

383 Separated from extract_text_content so that a container holding a mix of

384 inline and block children can hand over just the inline runs, without

385 building a synthetic element to wrap them in.

386

387 Args:

388 nodes: BeautifulSoup nodes (Tags and NavigableStrings) in document order

389 context: Current style context

390

391 Returns:

392 List of Word objects (including LinkedWord for hyperlinks)

393 """

394 from pyWebLayout.abstract.inline import LinkedWord

395 from pyWebLayout.abstract.functional import LinkType

396

397 words = []

399 for child in nodes:

400 # Comments and processing instructions are NavigableString subclasses;

401 # their text is markup, not content.

402 if isinstance(child, (Comment, Doctype, CData, ProcessingInstruction)): 402 ↛ 403line 402 didn't jump to line 403 because the condition on line 402 was never true

403 continue

405 if isinstance(child, NavigableString):

406 # Plain text - split into words. Argument-less str.split() already

407 # discards surrounding whitespace and never yields an empty string, so

408 # it needs neither a preceding strip() nor a per-word emptiness test.

409 font = context.font

410 background = context.background

411 words.extend([Word(word_text, font, background)

412 for word_text in str(child).split()])

413 elif isinstance(child, Tag): 413 ↛ 399line 413 didn't jump to line 399 because the condition on line 413 was always true

414 # Special handling for <a> tags (hyperlinks)

415 if child.name.lower() == "a":

416 href = child.get('href', '')

417 if href:

418 # Determine link type based on href

419 if href.startswith(('http://', 'https://')):

420 link_type = LinkType.EXTERNAL

421 elif href.startswith('#'):

422 link_type = LinkType.INTERNAL

423 elif href.startswith('javascript:') or href.startswith('api:'):

424 link_type = LinkType.API

425 else:

426 link_type = LinkType.INTERNAL

428 # Apply link styling

429 child_context = apply_element_styling(context, child)

431 # Extract text and create LinkedWord for each word

432 link_text = child.get_text(strip=True)

433 title = child.get('title', '')

434

435 for word_text in link_text.split():

436 if word_text: 436 ↛ 435line 436 didn't jump to line 435 because the condition on line 436 was always true

437 linked_word = LinkedWord(

438 text=word_text,

439 style=child_context.font,

440 location=href,

441 link_type=link_type,

442 background=child_context.background,

443 title=title if title else None

444 )

445 words.append(linked_word)

446 else:

447 # <a> without href - treat as normal text

448 child_context = apply_element_styling(context, child)

449 child_words = extract_text_content(child, child_context)

450 words.extend(child_words)

452 # Process other inline elements

453 elif child.name.lower() in [

454 "span",

455 "strong",

456 "b",

457 "em",

458 "i",

459 "u",

460 "s",

461 "del",

462 "ins",

463 "mark",

464 "small",

465 "sub",

466 "sup",

467 "code",

468 "q",

469 "cite",

470 "abbr",

471 "time",

472 ]:

473 child_context = apply_element_styling(context, child)

474 child_words = extract_text_content(child, child_context)

475 words.extend(child_words)

476 else:

477 # Block element - shouldn't happen in well-formed HTML but handle

478 # gracefully

479 child_context = apply_element_styling(context, child)

480 child_result = process_element(child, child_context)

481 if isinstance(child_result, list): 481 ↛ 482line 481 didn't jump to line 482 because the condition on line 481 was never true

482 for block in child_result:

483 if isinstance(block, Paragraph):

484 for _, word in block.words_iter():

485 words.append(word)

486 elif isinstance(child_result, Paragraph): 486 ↛ 487line 486 didn't jump to line 487 because the condition on line 486 was never true

487 for _, word in child_result.words_iter():

488 words.append(word)

489

490 return words

491

493# Tags that flow within a line of text rather than forming a block of their own.

494# They carry no handler of their own: extract_words_from_nodes consumes them,

495# applying their styling to the words they contain.

496INLINE_TAGS = frozenset({

497 "a", "span", "strong", "b", "em", "i", "u", "s", "del", "ins", "mark",

498 "small", "sub", "sup", "code", "q", "cite", "abbr", "time",

499})

500

501

502def is_inline(node) -> bool:

503 """

504 Whether a node belongs to a run of text rather than standing as its own block.

506 Args:

507 node: A BeautifulSoup Tag or NavigableString

508

509 Returns:

510 True for text and inline tags, False for block-level tags

511 """

512 if isinstance(node, Tag):

513 return node.name.lower() in INLINE_TAGS

514 if isinstance(node, (Comment, Doctype, CData, ProcessingInstruction)):

515 return False

516 return isinstance(node, NavigableString)

517

518

519def process_block_children(element: Tag, context: StyleContext) -> List[Block]:

520 """

521 Process a container's children into a list of blocks.

522

523 Containers may hold a mix of inline and block content. Consecutive inline

524 children are gathered into a run and become one Paragraph; a block child ends

525 the current run and is processed by its own handler. This is the single entry

526 point for every container that is not itself a paragraph - div, li, td, th,

527 blockquote and the semantic containers.

529 Without this, inline tags reach process_element, whose handler for them is

530 ignore_handler, and their text is silently dropped.

532 Args:

533 element: The container element

534 context: Current style context

535

536 Returns:

537 Blocks in document order

538 """

539 blocks: List[Block] = []

540 run: List = []

541

542 def flush_run():

543 """Turn the pending inline run into a paragraph, if it holds any words."""

544 if not run:

545 return

546 words = extract_words_from_nodes(run, context)

547 run.clear()

548 if words:

549 paragraph = Paragraph(context.font)

550 for word in words:

551 paragraph.add_word(word)

552 blocks.append(paragraph)

553

554 for child in element.children:

555 # <br> ends the current line of text and starts a new one.

556 if isinstance(child, Tag) and child.name.lower() == "br":

557 flush_run()

558 continue

559

560 if is_inline(child):

561 run.append(child)

562 continue

563

564 if not isinstance(child, Tag):

565 continue # comments and similar

566

567 flush_run()

568 child_context = apply_element_styling(context, child)

569 result = process_element(child, child_context)

570 if result:

571 if isinstance(result, list):

572 blocks.extend(result)

573 else:

574 blocks.append(result)

576 flush_run()

577 return blocks

578

579

580def process_element(

581 element: Tag, context: StyleContext

582) -> Union[Block, List[Block], None]:

583 """

584 Process a single HTML element using appropriate handler.

585

586 Args:

587 element: BeautifulSoup Tag object

588 context: Current style context

589

590 Returns:

591 Block object(s) or None if element should be ignored

592 """

593 tag_name = element.name.lower()

594 handler = HANDLERS.get(tag_name, generic_handler)

595 return handler(element, context)

596

597

598# Handler function signatures:

599# All handlers receive (element: Tag, context: StyleContext) ->

600# Union[Block, List[Block], None]

601

602

603def paragraph_handler(element: Tag, context: StyleContext) -> Union[Paragraph, List[Block], Image]:

604 """

605 Handle <p> elements.

606

607 Special handling for paragraphs containing images:

608 - If the paragraph contains only an image (common in EPUBs), return the image block

609 - If the paragraph contains images mixed with text, split into separate blocks

610 - Otherwise, return a normal paragraph with text content

611 """

612 # Check if paragraph contains any img tags (including nested ones)

613 img_tags = element.find_all('img')

614

615 if img_tags:

616 # Paragraph contains images - need special handling

617 blocks = []

618

619 # Check if this is an image-only paragraph (very common in EPUBs)

620 # Get text content without the img tags

621 text_content = element.get_text(strip=True)

622

623 if not text_content or len(text_content.strip()) == 0:

624 # Image-only paragraph - return just the image(s)

625 for img_tag in img_tags:

626 child_context = apply_element_styling(context, img_tag)

627 img_block = image_handler(img_tag, child_context)

628 if img_block: 628 ↛ 625line 628 didn't jump to line 625 because the condition on line 628 was always true

629 blocks.append(img_block)

630

631 # Return single image or list of images

632 if len(blocks) == 1:

633 return blocks[0]

634 return blocks if blocks else Paragraph(context.font)

635

636 # Mixed content - paragraph has both text and images

637 # Process children in order to preserve structure

638 for child in element.children:

639 if isinstance(child, Tag):

640 if child.name == 'img': 640 ↛ 649line 640 didn't jump to line 649 because the condition on line 640 was always true

641 # Add the image as a separate block

642 child_context = apply_element_styling(context, child)

643 img_block = image_handler(child, child_context)

644 if img_block: 644 ↛ 638line 644 didn't jump to line 638 because the condition on line 644 was always true

645 blocks.append(img_block)

646 else:

647 # Process other inline elements as part of text

648 # This will be handled by extract_text_content below

649 pass

650

651 # Also add a paragraph with the text content

652 paragraph = Paragraph(context.font)

653 words = extract_text_content(element, context)

654 if words: 654 ↛ 659line 654 didn't jump to line 659 because the condition on line 654 was always true

655 for word in words:

656 paragraph.add_word(word)

657 blocks.insert(0, paragraph) # Text comes before images

658

659 return blocks if blocks else Paragraph(context.font)

660

661 # No images - normal paragraph handling

662 paragraph = Paragraph(context.font)

663 words = extract_text_content(element, context)

664 for word in words:

665 paragraph.add_word(word)

666 return paragraph

667

668

669def div_handler(element: Tag, context: StyleContext) -> List[Block]:

670 """Handle <div> elements - treat as generic container."""

671 return process_block_children(element, context)

672

673

674def heading_handler(element: Tag, context: StyleContext) -> Heading:

675 """Handle <h1>-<h6> elements."""

676 level_map = {

677 "h1": HeadingLevel.H1,

678 "h2": HeadingLevel.H2,

679 "h3": HeadingLevel.H3,

680 "h4": HeadingLevel.H4,

681 "h5": HeadingLevel.H5,

682 "h6": HeadingLevel.H6,

683 }

684

685 level = level_map.get(element.name.lower(), HeadingLevel.H1)

686 heading = Heading(level, context.font)

687 words = extract_text_content(element, context)

688 for word in words:

689 heading.add_word(word)

690 return heading

692

693def blockquote_handler(element: Tag, context: StyleContext) -> Quote:

694 """Handle <blockquote> elements."""

695 quote = Quote(context.font)

696 for block in process_block_children(element, context):

697 quote.add_block(block)

698 return quote

699

700

701def preformatted_handler(element: Tag, context: StyleContext) -> CodeBlock:

702 """Handle <pre> elements."""

703 language = context.element_attributes.get("data-language", "")

704 code_block = CodeBlock(language)

706 # Preserve whitespace and line breaks in preformatted text

707 text = element.get_text(separator="\n", strip=False)

708 for line in text.split("\n"):

709 code_block.add_line(line)

710

711 return code_block

712

713

714def code_handler(element: Tag, context: StyleContext) -> Union[CodeBlock, None]:

715 """Handle <code> elements."""

716 # If parent is <pre>, this is handled by preformatted_handler

717 if context.parent_elements and context.parent_elements[-1] == "pre":

718 return None # Will be handled by parent

719

720 # Inline code - handled during text extraction

721 return None

722

723

724def unordered_list_handler(element: Tag, context: StyleContext) -> HList:

725 """Handle <ul> elements."""

726 hlist = HList(ListStyle.UNORDERED, context.font)

727 for child in element.children:

728 if isinstance(child, Tag) and child.name.lower() == "li":

729 child_context = apply_element_styling(context, child)

730 item = process_element(child, child_context)

731 if item: 731 ↛ 727line 731 didn't jump to line 727 because the condition on line 731 was always true

732 hlist.add_item(item)

733 return hlist

734

735

736def ordered_list_handler(element: Tag, context: StyleContext) -> HList:

737 """Handle <ol> elements."""

738 hlist = HList(ListStyle.ORDERED, context.font)

739 for child in element.children:

740 if isinstance(child, Tag) and child.name.lower() == "li":

741 child_context = apply_element_styling(context, child)

742 item = process_element(child, child_context)

743 if item: 743 ↛ 739line 743 didn't jump to line 739 because the condition on line 743 was always true

744 hlist.add_item(item)

745 return hlist

746

747

748def list_item_handler(element: Tag, context: StyleContext) -> ListItem:

749 """Handle <li> elements."""

750 list_item = ListItem(None, context.font)

751 for block in process_block_children(element, context):

752 list_item.add_block(block)

753 return list_item

754

755

756def table_handler(element: Tag, context: StyleContext) -> Table:

757 """Handle <table> elements."""

758 caption = None

759 caption_elem = element.find("caption")

760 if caption_elem: 760 ↛ 761line 760 didn't jump to line 761 because the condition on line 760 was never true

761 caption = caption_elem.get_text(strip=True)

762

763 table = Table(caption, context.font)

764

765 # Process table rows

766 for child in element.children:

767 if isinstance(child, Tag):

768 if child.name.lower() == "tr":

769 child_context = apply_element_styling(context, child)

770 row = process_element(child, child_context)

771 if row: 771 ↛ 766line 771 didn't jump to line 766 because the condition on line 771 was always true

772 table.add_row(row)

773 elif child.name.lower() in ["thead", "tbody", "tfoot"]: 773 ↛ 766line 773 didn't jump to line 766 because the condition on line 773 was always true

774 section = "header" if child.name.lower() == "thead" else "body"

775 section = "footer" if child.name.lower() == "tfoot" else section

776

777 for row_elem in child.find_all("tr"):

778 child_context = apply_element_styling(context, row_elem)

779 row = process_element(row_elem, child_context)

780 if row: 780 ↛ 777line 780 didn't jump to line 777 because the condition on line 780 was always true

781 table.add_row(row, section)

782

783 return table

784

785

786def table_row_handler(element: Tag, context: StyleContext) -> TableRow:

787 """Handle <tr> elements."""

788 row = TableRow(context.font)

789 for child in element.children:

790 if isinstance(child, Tag) and child.name.lower() in ["td", "th"]:

791 child_context = apply_element_styling(context, child)

792 cell = process_element(child, child_context)

793 if cell: 793 ↛ 789line 793 didn't jump to line 789 because the condition on line 793 was always true

794 row.add_cell(cell)

795 return row

796

797

798def table_cell_handler(element: Tag, context: StyleContext) -> TableCell:

799 """Handle <td> elements."""

800 colspan = int(context.element_attributes.get("colspan", 1))

801 rowspan = int(context.element_attributes.get("rowspan", 1))

802 cell = TableCell(False, colspan, rowspan, context.font)

803

804 for block in process_block_children(element, context):

805 cell.add_block(block)

806

807 return cell

808

809

810def table_header_cell_handler(element: Tag, context: StyleContext) -> TableCell:

811 """Handle <th> elements."""

812 colspan = int(context.element_attributes.get("colspan", 1))

813 rowspan = int(context.element_attributes.get("rowspan", 1))

814 cell = TableCell(True, colspan, rowspan, context.font)

815

816 for block in process_block_children(element, context):

817 cell.add_block(block)

818

819 return cell

820

821

822def horizontal_rule_handler(element: Tag, context: StyleContext) -> HorizontalRule:

823 """Handle <hr> elements."""

824 return HorizontalRule()

825

826

827def line_break_handler(element: Tag, context: StyleContext) -> None:

828 """Handle <br> elements."""

829 # Line breaks are typically handled at the paragraph level

830 return None

831

832

833def image_handler(element: Tag, context: StyleContext) -> Image:

834 """Handle <img> elements."""

835 import os

836 import urllib.parse

837

838 src = context.element_attributes.get("src", "")

839 alt_text = context.element_attributes.get("alt", "")

840

841 # Resolve relative paths if base_path is provided

842 if context.base_path and src and not src.startswith(('http://', 'https://', '/')):

843 # Parse the src to handle URL-encoded characters

844 src_decoded = urllib.parse.unquote(src)

845 # Resolve relative path to absolute path

846 src = os.path.normpath(os.path.join(context.base_path, src_decoded))

847

848 # Parse dimensions if provided

849 width = height = None

850 try:

851 if "width" in context.element_attributes:

852 width = int(context.element_attributes["width"])

853 if "height" in context.element_attributes:

854 height = int(context.element_attributes["height"])

855 except ValueError:

856 pass

857

858 return Image(source=src, alt_text=alt_text, width=width, height=height)

859

860

861def ignore_handler(element: Tag, context: StyleContext) -> None:

862 """Handle elements that should be ignored."""

863 return None

864

865

866def generic_handler(element: Tag, context: StyleContext) -> List[Block]:

867 """Handle unknown elements as generic containers."""

868 return div_handler(element, context)

869

870

871# Handler registry - maps HTML tag names to handler functions

872HANDLERS: Dict[str, Callable[[Tag, StyleContext], Union[Block, List[Block], None]]] = {

873 # Block elements

874 "p": paragraph_handler,

875 "div": div_handler,

876 "h1": heading_handler,

877 "h2": heading_handler,

878 "h3": heading_handler,

879 "h4": heading_handler,

880 "h5": heading_handler,

881 "h6": heading_handler,

882 "blockquote": blockquote_handler,

883 "pre": preformatted_handler,

884 "code": code_handler,

885 "ul": unordered_list_handler,

886 "ol": ordered_list_handler,

887 "li": list_item_handler,

888 "table": table_handler,

889 "tr": table_row_handler,

890 "td": table_cell_handler,

891 "th": table_header_cell_handler,

892 "hr": horizontal_rule_handler,

893 "br": line_break_handler,

894 # Semantic elements (treated as containers)

895 "section": div_handler,

896 "article": div_handler,

897 "aside": div_handler,

898 "nav": div_handler,

899 "header": div_handler,

900 "footer": div_handler,

901 "main": div_handler,

902 "figure": div_handler,

903 "figcaption": paragraph_handler,

904 # Media elements

905 "img": image_handler,

906 # Inline elements (handled during text extraction)

907 "span": ignore_handler,

908 "a": ignore_handler,

909 "strong": ignore_handler,

910 "b": ignore_handler,

911 "em": ignore_handler,

912 "i": ignore_handler,

913 "u": ignore_handler,

914 "s": ignore_handler,

915 "del": ignore_handler,

916 "ins": ignore_handler,

917 "mark": ignore_handler,

918 "small": ignore_handler,

919 "sub": ignore_handler,

920 "sup": ignore_handler,

921 "q": ignore_handler,

922 "cite": ignore_handler,

923 "abbr": ignore_handler,

924 "time": ignore_handler,

925 # Ignored elements

926 "script": ignore_handler,

927 "style": ignore_handler,

928 "meta": ignore_handler,

929 "link": ignore_handler,

930 "head": ignore_handler,

931 "title": ignore_handler,

932}

933

934

935def parse_html_string(

936 html_string: str, base_font: Optional[Font] = None, document=None, base_path: Optional[str] = None

937) -> List[Block]:

938 """

939 Parse HTML string and return list of Block objects.

940

941 Args:

942 html_string: HTML content to parse

943 base_font: Base font for styling, defaults to system default

944 document: Document instance for font registry to avoid duplicate fonts

945 base_path: Base directory path for resolving relative URLs (e.g., image sources)

946

947 Returns:

948 List of Block objects representing the document structure

949 """

950 soup = BeautifulSoup(html_string, "html.parser")

951 context = create_base_context(base_font, document, base_path)

952

953 blocks = []

954

955 # Process the body if it exists, otherwise process all top-level elements

956 root_element = soup.find("body") or soup

957

958 for element in root_element.children:

959 if isinstance(element, Tag):

960 element_context = apply_element_styling(context, element)

961 result = process_element(element, element_context)

962 if result:

963 if isinstance(result, list):

964 blocks.extend(result)

965 else:

966 blocks.append(result)

967

968 return blocks

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37___init___py.html b/cov_info/htmlcov/z_40407af872b0cf37___init___py.html new file mode 100644 index 0000000..3a8561d --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37___init___py.html @@ -0,0 +1,133 @@ + + + + + Coverage for pyWebLayout/core/__init__.py: 100% + + + + + +

+ Coverage for pyWebLayout/core/init.py: + 100% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 2 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Core functionality for the pyWebLayout library.

4This package contains the core abstractions and base classes that form the foundation

5of the pyWebLayout rendering system.

6"""

8from .base import (

9 Renderable,

10 Interactable,

11 Layoutable,

12 Queriable,

13 Hierarchical,

14 Geometric,

15 Styleable,

16 FontRegistry,

17 MetadataContainer,

18 BlockContainer,

19 ContainerAware,

20)

22__all__ = [

23 'Renderable',

24 'Interactable',

25 'Layoutable',

26 'Queriable',

27 'Hierarchical',

28 'Geometric',

29 'Styleable',

30 'FontRegistry',

31 'MetadataContainer',

32 'BlockContainer',

33 'ContainerAware',

34]

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37_base_py.html b/cov_info/htmlcov/z_40407af872b0cf37_base_py.html new file mode 100644 index 0000000..3229f28 --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37_base_py.html @@ -0,0 +1,547 @@ + + + + + Coverage for pyWebLayout/core/base.py: 72% + + + + + +

+ Coverage for pyWebLayout/core/base.py: + 72% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 134 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from abc import ABC

2from typing import Optional, Tuple, TYPE_CHECKING, Any, Dict

3import numpy as np

6if TYPE_CHECKING: 6 ↛ 7line 6 didn't jump to line 7 because the condition on line 6 was never true

7 from pyWebLayout.style import Font, FontWeight, FontStyle, TextDecoration

10class Renderable(ABC):

11 """

12 Abstract base class for any object that can be rendered to an image.

13 All renderable objects must implement the render method.

14 """

16 def render(self):

17 """

18 Render the object to an image.

20 Returns:

21 PIL.Image: The rendered image

22 """

24 @property

25 def origin(self):

26 return self._origin

29class Interactable(ABC):

30 """

31 Abstract base class for any object that can be interacted with.

32 Interactable objects must have a callback that is executed when interacted with.

33 """

35 def __init__(self, callback=None):

36 """

37 Initialize an interactable object.

39 Args:

40 callback: The function to call when this object is interacted with

41 """

42 self._callback = callback

44 def interact(self, point: np.generic):

45 """

46 Handle interaction at the given point.

48 Args:

49 point: The coordinates of the interaction

51 Returns:

52 The result of calling the callback function with the point

53 """

54 if self._callback is None: 54 ↛ 55line 54 didn't jump to line 55 because the condition on line 54 was never true

55 return None

56 return self._callback(point)

59class Layoutable(ABC):

60 """

61 Abstract base class for any object that can be laid out.

62 Layoutable objects must implement the layout method which arranges their contents.

63 """

65 def layout(self):

66 """

67 Layout the object's contents.

68 This method should be called before rendering to properly arrange the object's contents.

69 """

72class Queriable(ABC):

74 def in_object(self, point: np.generic):

75 """

76 check if a point is in the object

77 """

78 point_array = np.array(point)

79 relative_point = point_array - self._origin

80 return np.all((0 <= relative_point) & (relative_point < self.size))

83# ==============================================================================

84# Mixins - Reusable components for common patterns

85# ==============================================================================

88class Hierarchical:

89 """

90 Mixin providing parent-child relationship management.

92 Classes using this mixin can track their parent in a document hierarchy.

93 """

95 def __init__(self, *args, **kwargs):

96 super().__init__(*args, **kwargs)

97 self._parent: Optional[Any] = None

99 @property

100 def parent(self) -> Optional[Any]:

101 """Get the parent object containing this object, if any"""

102 return self._parent

104 @parent.setter

105 def parent(self, parent: Any):

106 """Set the parent object"""

107 self._parent = parent

110class Geometric:

111 """

112 Mixin providing origin and size properties for positioned elements.

113

114 Provides standard geometric properties for elements that have a position

115 and size in 2D space. Uses numpy arrays for efficient calculations.

116 """

118 def __init__(self, *args, origin=None, size=None, **kwargs):

119 super().__init__(*args, **kwargs)

120 self._origin = np.array(origin) if origin is not None else np.array([0, 0])

121 self._size = np.array(size) if size is not None else np.array([0, 0])

123 @property

124 def origin(self) -> np.ndarray:

125 """Get the origin (top-left corner) of the element"""

126 return self._origin

127

128 @origin.setter

129 def origin(self, origin: np.ndarray):

130 """Set the origin of the element"""

131 self._origin = np.array(origin)

133 @property

134 def size(self) -> np.ndarray:

135 """Get the size (width, height) of the element"""

136 return self._size

138 @size.setter

139 def size(self, size: np.ndarray):

140 """Set the size of the element"""

141 self._size = np.array(size)

143 def set_origin(self, origin: np.ndarray):

144 """Set the origin of this element (alternative setter method)"""

145 self._origin = np.array(origin)

148class Styleable:

149 """

150 Mixin providing style property management.

152 Classes using this mixin can have a style property that can be

153 inherited from parents or set explicitly.

154 """

156 def __init__(self, *args, style=None, **kwargs):

157 super().__init__(*args, **kwargs)

158 self._style = style

159

160 @property

161 def style(self) -> Optional[Any]:

162 """Get the style for this element"""

163 return self._style

165 @style.setter

166 def style(self, style: Any):

167 """Set the style for this element"""

168 self._style = style

170

171class FontRegistry:

172 """

173 Mixin providing font caching and creation with parent delegation.

175 This mixin allows classes to maintain a local font registry and create/reuse

176 Font objects efficiently. It supports parent delegation, where font requests

177 can cascade up to a parent container if one exists.

179 Classes using this mixin should also use Hierarchical to support parent delegation.

180 """

182 def __init__(self, *args, **kwargs):

183 super().__init__(*args, **kwargs)

184 self._fonts: Dict[str, 'Font'] = {}

186 def get_or_create_font(self,

187 font_path: Optional[str] = None,

188 font_size: int = 16,

189 colour: Tuple[int, int, int] = (0, 0, 0),

190 weight: 'FontWeight' = None,

191 style: 'FontStyle' = None,

192 decoration: 'TextDecoration' = None,

193 background: Optional[Tuple[int, int, int, int]] = None,

194 language: str = "en_EN",

195 min_hyphenation_width: Optional[int] = None) -> 'Font':

196 """

197 Get or create a font with the specified properties.

199 This method will first check if a parent object has a get_or_create_font

200 method and delegate to it. Otherwise, it will manage fonts locally.

202 Args:

203 font_path: Path to the font file (.ttf, .otf). If None, uses default font.

204 font_size: Size of the font in points.

205 colour: RGB color tuple for the text.

206 weight: Font weight (normal or bold).

207 style: Font style (normal or italic).

208 decoration: Text decoration (none, underline, or strikethrough).

209 background: RGBA background color for the text. If None, transparent background.

210 language: Language code for hyphenation and text processing.

211 min_hyphenation_width: Minimum width in pixels required for hyphenation.

212

213 Returns:

214 Font object (either existing or newly created)

215 """

216 # Import here to avoid circular imports

217 from pyWebLayout.style import Font, FontWeight, FontStyle, TextDecoration

219 # Set defaults for enum types

220 if weight is None:

221 weight = FontWeight.NORMAL

222 if style is None:

223 style = FontStyle.NORMAL

224 if decoration is None:

225 decoration = TextDecoration.NONE

227 # If we have a parent with font management, delegate to parent

228 if hasattr(

229 self,

230 '_parent') and self._parent and hasattr(

231 self._parent,

232 'get_or_create_font'):

233 return self._parent.get_or_create_font(

234 font_path=font_path,

235 font_size=font_size,

236 colour=colour,

237 weight=weight,

238 style=style,

239 decoration=decoration,

240 background=background,

241 language=language,

242 min_hyphenation_width=min_hyphenation_width

243 )

245 # Otherwise manage our own fonts

246 # Create a unique key for this font configuration

247 bg_tuple = background if background else (255, 255, 255, 0)

248 min_hyph_width = min_hyphenation_width if min_hyphenation_width is not None else font_size * 4

250 font_key = (

251 font_path,

252 font_size,

253 colour,

254 weight.value if hasattr(weight, 'value') else weight,

255 style.value if hasattr(style, 'value') else style,

256 decoration.value if hasattr(decoration, 'value') else decoration,

257 bg_tuple,

258 language,

259 min_hyph_width

260 )

262 # Convert tuple to string for dictionary key

263 key_str = str(font_key)

265 # Check if we already have this font

266 if key_str in self._fonts:

267 return self._fonts[key_str]

269 # Create new font and store it

270 new_font = Font(

271 font_path=font_path,

272 font_size=font_size,

273 colour=colour,

274 weight=weight,

275 style=style,

276 decoration=decoration,

277 background=background,

278 language=language,

279 min_hyphenation_width=min_hyphenation_width

280 )

282 self._fonts[key_str] = new_font

283 return new_font

286class MetadataContainer:

287 """

288 Mixin providing metadata dictionary management.

290 Allows classes to store and retrieve arbitrary metadata as key-value pairs.

291 """

293 def __init__(self, *args, **kwargs):

294 super().__init__(*args, **kwargs)

295 self._metadata: Dict[Any, Any] = {}

297 def set_metadata(self, key: Any, value: Any):

298 """

299 Set a metadata value.

301 Args:

302 key: The metadata key

303 value: The metadata value

304 """

305 self._metadata[key] = value

307 def get_metadata(self, key: Any) -> Optional[Any]:

308 """

309 Get a metadata value.

311 Args:

312 key: The metadata key

313

314 Returns:

315 The metadata value, or None if not set

316 """

317 return self._metadata.get(key)

319

320class BlockContainer:

321 """

322 Mixin providing block management methods.

323

324 Provides standard methods for managing block-level children including

325 adding blocks and creating common block types.

327 Classes using this mixin should also use Styleable to support style inheritance.

328 """

329

330 def __init__(self, *args, **kwargs):

331 super().__init__(*args, **kwargs)

332 self._blocks = []

333

334 def blocks(self):

335 """

336 Get an iterator over the blocks in this container.

338 Can be used as blocks() for iteration or accessing the _blocks list directly.

339

340 Returns:

341 Iterator over blocks

342 """

343 return iter(self._blocks)

345 def add_block(self, block):

346 """

347 Add a block to this container.

349 Args:

350 block: The block to add

351 """

352 self._blocks.append(block)

353 if hasattr(block, 'parent'): 353 ↛ exitline 353 didn't return from function 'add_block' because the condition on line 353 was always true

354 block.parent = self

355

356 def create_paragraph(self, style=None):

357 """

358 Create a new paragraph and add it to this container.

359

360 Args:

361 style: Optional style override. If None, inherits from container

363 Returns:

364 The newly created Paragraph object

365 """

366 from pyWebLayout.abstract.block import Paragraph

368 if style is None and hasattr(self, '_style'):

369 style = self._style

371 paragraph = Paragraph(style)

372 self.add_block(paragraph)

373 return paragraph

375 def create_heading(self, level=None, style=None):

376 """

377 Create a new heading and add it to this container.

379 Args:

380 level: The heading level (h1-h6)

381 style: Optional style override. If None, inherits from container

383 Returns:

384 The newly created Heading object

385 """

386 from pyWebLayout.abstract.block import Heading, HeadingLevel

388 if level is None:

389 level = HeadingLevel.H1

390

391 if style is None and hasattr(self, '_style'):

392 style = self._style

393

394 heading = Heading(level, style)

395 self.add_block(heading)

396 return heading

399class ContainerAware:

400 """

401 Mixin providing support for the create_and_add_to factory pattern.

402

403 This is a base that can be extended to provide the create_and_add_to

404 class method pattern used throughout the abstract module.

405

406 Note: This is a framework for future refactoring. Currently, each class

407 has its own create_and_add_to implementation due to varying constructor

408 signatures. This mixin provides a foundation for standardizing that pattern.

409 """

410

411 @classmethod

412 def _validate_container(cls, container, required_method='add_block'):

413 """

414 Validate that a container has the required method.

416 Args:

417 container: The container to validate

418 required_method: The method name to check for

419

420 Raises:

421 AttributeError: If the container doesn't have the required method

422 """

423 if not hasattr(container, required_method):

424 raise AttributeError(

425 f"Container {type(container).__name__} must have a '{required_method}' method"

426 )

428 @classmethod

429 def _inherit_style(cls, container, style=None):

430 """

431 Inherit style from container if not explicitly provided.

432

433 Args:

434 container: The container to inherit from

435 style: Optional explicit style

436

437 Returns:

438 The style to use (explicit or inherited)

439 """

440 if style is not None:

441 return style

442

443 if hasattr(container, 'style'):

444 return container.style

445 elif hasattr(container, 'default_style'):

446 return container.default_style

448 return None

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37_cache_py.html b/cov_info/htmlcov/z_40407af872b0cf37_cache_py.html new file mode 100644 index 0000000..271b299 --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37_cache_py.html @@ -0,0 +1,442 @@ + + + + + Coverage for pyWebLayout/core/cache.py: 97% + + + + + +

+ Coverage for pyWebLayout/core/cache.py: + 97% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 171 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Bounded usage-ranked caches for the text rendering hot path.

4Laying out and rasterising a page re-measures and re-draws the same words over and

5over: a typical page issues ~2800 width measurements and ~2500 glyph rasterisations

6for fewer than 1000 distinct (font, string) pairs. Caching both collapses that work,

7but an unbounded cache is not an option on a memory-constrained target such as a

8Raspberry Pi Zero 2, where the rasterised bitmaps reach ~19MB over a long session.

10Eviction is by **usage count**, not recency. Word frequency in prose is Zipfian and

11stationary -- a small set of words ("the", "and", "of") accounts for most tokens on

12every page, and that set barely shifts as the reader advances -- so the words worth

13keeping are exactly the ones used most.

15Two design choices keep this from costing more than it saves, because `get` runs

16once per word drawn (~2500 times per page):

18* **Counting is O(1) with no reordering.** Each entry carries its own use counter,

19 bumped in place. Ranking structures that reorder on every hit (a frequency-bucket

20 LFU, or an LRU's linked-list splice) were measured 3-5ms per page slower than the

21 hit rate they buy is worth.

22* **Eviction samples rather than sorts.** Finding the globally least-used entry

23 would need a heap kept current on every hit. Instead a small random sample is

24 drawn and the least-used member of it evicted, the same approximation Redis uses

25 for its LFU policy. With the default sample size the evicted entry is very

26 likely to be in the bottom few percent, which is all that matters here.

28Both are single-threaded by design; the rendering path holds the GIL throughout and

29adding locking would cost more than it protects.

30"""

32from __future__ import annotations

34import random

35from typing import Any, Callable, Dict, Generic, Hashable, List, Optional, TypeVar

37K = TypeVar('K', bound=Hashable)

38V = TypeVar('V')

40# Entries examined per eviction. Larger samples approximate true least-frequently-used

41# more closely at linear cost; 8 puts the victim in the bottom ~15% of entries, which

42# is ample when the alternative is a rasterisation that costs ~60us either way.

43DEFAULT_EVICTION_SAMPLE = 8

45# Halving every entry's use count after this many insertions keeps the cache

46# responsive to a change of working set. Without it, entries that were hot long ago

47# retain counts a newly-hot entry cannot beat and are never evicted -- the classic

48# failure of pure frequency eviction. Measured on a real access trace, a font-size

49# change drove hit rate to 0% without aging and left it unchanged with it.

50DEFAULT_AGING_INTERVAL = 10000

52# Index of each field in an entry. Entries are plain lists rather than tuples or

53# objects so the counter can be bumped in place, without rehashing the key.

54_VALUE = 0

55_COUNT = 1

56_SLOT = 2

59class _UsageRanked(Generic[K, V]):

60 """

61 Shared usage-count bookkeeping for the caches below.

63 Entries live in a dict for lookup and, in parallel, in a flat list that makes

64 uniform random sampling possible. Each entry records its own index in that list

65 so removal can swap in the tail element and stay O(1).

67 Subclasses supply the bound by implementing :meth:`_over_budget` and the

68 accounting hooks :meth:`_record_add` / :meth:`_record_remove`.

69 """

71 def __init__(self,

72 aging_interval: Optional[int] = DEFAULT_AGING_INTERVAL,

73 eviction_sample: int = DEFAULT_EVICTION_SAMPLE):

74 if aging_interval is not None and aging_interval <= 0:

75 raise ValueError(f"aging_interval must be positive, got {aging_interval}")

76 if eviction_sample <= 0:

77 raise ValueError(f"eviction_sample must be positive, got {eviction_sample}")

79 self._aging_interval = aging_interval

80 self._eviction_sample = eviction_sample

82 self._entries: Dict[K, List[Any]] = {}

83 self._slots: List[K] = []

84 self._randrange = random.randrange

86 self._inserts_since_aging = 0

87 self._hits = 0

88 self._misses = 0

89 self._evictions = 0

90 self._agings = 0

92 # -- subclass hooks ----------------------------------------------------

94 def _over_budget(self) -> bool:

95 raise NotImplementedError

97 def _record_add(self, key: K, value: V):

98 """Account for a value entering the cache."""

100 def _record_remove(self, key: K):

101 """Account for a value leaving the cache."""

102

103 # -- core operations ---------------------------------------------------

105 def get(self, key: K) -> Optional[V]:

106 """Return the cached value for `key`, or None, counting the use."""

107 entry = self._entries.get(key)

108 if entry is None:

109 self._misses += 1

110 return None

111 entry[_COUNT] += 1

112 self._hits += 1

113 return entry[_VALUE]

115 def _add_new(self, key: K, value: V):

116 """Insert a key not currently present."""

117 # New entries start at 1 rather than 0 so that a single reuse is enough to

118 # outrank an entry that has never been touched since the last aging pass.

119 self._entries[key] = [value, 1, len(self._slots)]

120 self._slots.append(key)

121 self._record_add(key, value)

123 def _remove(self, key: K):

124 """Remove a key outright, keeping the sampling list dense."""

125 entry = self._entries.pop(key)

126 slot = entry[_SLOT]

127 last = self._slots.pop()

128 if last != key:

129 self._slots[slot] = last

130 self._entries[last][_SLOT] = slot

131 self._record_remove(key)

133 def _evict_one(self) -> bool:

134 """Evict the least-used member of a random sample. False if empty."""

135 count = len(self._slots)

136 if not count: 136 ↛ 137line 136 didn't jump to line 137 because the condition on line 136 was never true

137 return False

139 if count <= self._eviction_sample:

140 victim = min(self._slots, key=lambda k: self._entries[k][_COUNT])

141 else:

142 randrange = self._randrange

143 entries = self._entries

144 slots = self._slots

145 victim = slots[randrange(count)]

146 best = entries[victim][_COUNT]

147 for _ in range(self._eviction_sample - 1):

148 candidate = slots[randrange(count)]

149 score = entries[candidate][_COUNT]

150 if score < best:

151 victim, best = candidate, score

153 self._remove(victim)

154 self._evictions += 1

155 return True

157 def _evict_to_budget(self):

158 while self._over_budget():

159 if not self._evict_one(): 159 ↛ 160line 159 didn't jump to line 160 because the condition on line 159 was never true

160 break

162 def _maybe_age(self):

163 """Halve every use count once the aging interval has elapsed."""

164 if self._aging_interval is None:

165 return

166 self._inserts_since_aging += 1

167 if self._inserts_since_aging < self._aging_interval:

168 return

170 self._inserts_since_aging = 0

171 self._agings += 1

172 for entry in self._entries.values():

173 entry[_COUNT] = entry[_COUNT] // 2 or 1

175 def clear(self):

176 """Drop all entries. Counters are preserved."""

177 self._entries.clear()

178 self._slots.clear()

179 self._inserts_since_aging = 0

181 def _base_stats(self) -> Dict[str, Any]:

182 total = self._hits + self._misses

183 return {

184 'entries': len(self._entries),

185 'hits': self._hits,

186 'misses': self._misses,

187 'evictions': self._evictions,

188 'agings': self._agings,

189 'hit_rate': (self._hits / total) if total else 0.0,

190 }

192 def __len__(self) -> int:

193 return len(self._entries)

195 def __contains__(self, key: object) -> bool:

196 return key in self._entries

199class UsageCache(_UsageRanked[K, V]):

200 """

201 Usage-ranked cache bounded by number of entries.

203 Args:

204 max_entries: Maximum number of entries to retain. Must be positive.

205 aging_interval: Insertions between halving all use counts, or None to

206 disable aging. See :data:`DEFAULT_AGING_INTERVAL`.

207 eviction_sample: Entries sampled per eviction.

208 """

209

210 def __init__(self, max_entries: int,

211 aging_interval: Optional[int] = DEFAULT_AGING_INTERVAL,

212 eviction_sample: int = DEFAULT_EVICTION_SAMPLE):

213 if max_entries <= 0:

214 raise ValueError(f"max_entries must be positive, got {max_entries}")

215 super().__init__(aging_interval, eviction_sample)

216 self._max_entries = max_entries

218 def _over_budget(self) -> bool:

219 return len(self._entries) > self._max_entries

221 def put(self, key: K, value: V, count: int = 1):

222 """

223 Insert `value`, evicting the least-used entries past the bound.

224

225 Args:

226 count: Initial use count. Pass a document-derived frequency to rank a

227 preloaded entry ahead of words that have not been seen yet.

228 """

229 existing = self._entries.get(key)

230 if existing is not None:

231 existing[_VALUE] = value

232 existing[_COUNT] += 1

233 return

234 self._add_new(key, value)

235 if count > 1:

236 self._entries[key][_COUNT] = count

237 self._evict_to_budget()

238 self._maybe_age()

240 @property

241 def max_entries(self) -> int:

242 return self._max_entries

244 def resize(self, max_entries: int):

245 """Change the bound, evicting immediately if the cache now overflows."""

246 if max_entries <= 0:

247 raise ValueError(f"max_entries must be positive, got {max_entries}")

248 self._max_entries = max_entries

249 self._evict_to_budget()

251 def stats(self) -> Dict[str, Any]:

252 """Hit/miss/eviction counters and current occupancy."""

253 stats = self._base_stats()

254 stats['max_entries'] = self._max_entries

255 return stats

257

258class SizedUsageCache(_UsageRanked[K, V]):

259 """

260 Usage-ranked cache bounded by the total size of its values.

262 Args:

263 max_bytes: Maximum total value size to retain. Must be positive.

264 sizer: Returns the size in bytes of a value. Called once per insertion.

265 aging_interval: Insertions between halving all use counts, or None to

266 disable aging. See :data:`DEFAULT_AGING_INTERVAL`.

267 eviction_sample: Entries sampled per eviction.

269 A value larger than `max_bytes` on its own is returned to the caller but not

270 retained, so that one oversized entry cannot flush the whole cache.

271 """

273 def __init__(self, max_bytes: int, sizer: Callable[[V], int],

274 aging_interval: Optional[int] = DEFAULT_AGING_INTERVAL,

275 eviction_sample: int = DEFAULT_EVICTION_SAMPLE):

276 if max_bytes <= 0:

277 raise ValueError(f"max_bytes must be positive, got {max_bytes}")

278 super().__init__(aging_interval, eviction_sample)

279 self._max_bytes = max_bytes

280 self._sizer = sizer

281 self._sizes: Dict[K, int] = {}

282 self._total_bytes = 0

284 def _over_budget(self) -> bool:

285 return self._total_bytes > self._max_bytes

287 def _record_add(self, key: K, value: V):

288 size = self._sizer(value)

289 self._sizes[key] = size

290 self._total_bytes += size

291

292 def _record_remove(self, key: K):

293 self._total_bytes -= self._sizes.pop(key)

295 def put(self, key: K, value: V, count: int = 1):

296 """

297 Insert `value`, evicting the least-used entries past the bound.

299 Args:

300 count: Initial use count. Pass a document-derived frequency to rank a

301 preloaded entry ahead of words that have not been seen yet.

302 """

303 if key in self._entries:

304 # Re-measure: the replacement may be a different size.

305 self._remove(key)

307 if self._sizer(value) > self._max_bytes:

308 # Too large to ever retain; skip rather than flush everything for it.

309 return

311 self._add_new(key, value)

312 if count > 1:

313 self._entries[key][_COUNT] = count

314 self._evict_to_budget()

315 self._maybe_age()

317 @property

318 def max_bytes(self) -> int:

319 return self._max_bytes

321 @property

322 def total_bytes(self) -> int:

323 return self._total_bytes

325 def resize(self, max_bytes: int):

326 """Change the bound, evicting immediately if the cache now overflows."""

327 if max_bytes <= 0: 327 ↛ 328line 327 didn't jump to line 328 because the condition on line 327 was never true

328 raise ValueError(f"max_bytes must be positive, got {max_bytes}")

329 self._max_bytes = max_bytes

330 self._evict_to_budget()

332 def clear(self):

333 """Drop all entries. Counters are preserved."""

334 super().clear()

335 self._sizes.clear()

336 self._total_bytes = 0

338 def stats(self) -> Dict[str, Any]:

339 """Hit/miss/eviction counters and current occupancy."""

340 stats = self._base_stats()

341 stats['total_bytes'] = self._total_bytes

342 stats['max_bytes'] = self._max_bytes

343 return stats

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37_callback_registry_py.html b/cov_info/htmlcov/z_40407af872b0cf37_callback_registry_py.html new file mode 100644 index 0000000..3867b3c --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37_callback_registry_py.html @@ -0,0 +1,377 @@ + + + + + Coverage for pyWebLayout/core/callback_registry.py: 92% + + + + + +

+ Coverage for pyWebLayout/core/callback_registry.py: + 92% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 75 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Callback Registry for managing interactable elements and their callbacks.

4This module provides a registry system for tracking interactive elements (links, buttons, forms)

5and managing their callbacks. Supports multiple binding strategies:

6- HTML id attributes for HTML-generated content

7- Auto-generated ids for programmatic construction

8- Type-based batch operations

9"""

11from typing import Dict, List, Optional, Callable

12from pyWebLayout.core.base import Interactable

15class CallbackRegistry:

16 """

17 Registry for managing interactable callbacks with multiple binding strategies.

19 Supports:

20 - Direct references by object id

21 - HTML id attributes (from parsed HTML)

22 - Type-based queries (all buttons, all links, etc.)

23 - Auto-generated ids for programmatic construction

25 This enables flexible callback binding for both HTML-generated content

26 and manually constructed UIs.

27 """

29 def __init__(self):

30 """Initialize an empty callback registry."""

31 self._by_reference: Dict[int, Interactable] = {} # id(obj) -> obj

32 self._by_id: Dict[str, Interactable] = {} # HTML id or auto id -> obj

33 self._by_type: Dict[str, List[Interactable]] = {} # type name -> [objs]

34 self._auto_counter: int = 0

36 def register(self, obj: Interactable, html_id: Optional[str] = None) -> str:

37 """

38 Register an interactable object with optional HTML id.

40 The object is always registered by reference (using Python's id()).

41 If an html_id is provided, it's also registered by that id.

42 If no html_id is provided, an auto-generated id is created.

44 Args:

45 obj: The interactable object to register

46 html_id: Optional HTML id attribute value (e.g., from <button id="save-btn">)

48 Returns:

49 The id used for registration (either html_id or auto-generated)

51 Example:

52 >>> button = ButtonText(...)

53 >>> registry.register(button, html_id="save-btn")

54 'save-btn'

55 >>> registry.register(other_button) # No html_id

56 'auto_button_0'

57 """

58 # Always register by Python object id for direct lookups

59 obj_id = id(obj)

60 self._by_reference[obj_id] = obj

62 # Determine type name and register by type

63 type_name = self._get_type_name(obj)

64 if type_name not in self._by_type:

65 self._by_type[type_name] = []

66 self._by_type[type_name].append(obj)

68 # Register by HTML id or generate auto id

69 if html_id:

70 # Use provided HTML id

71 self._by_id[html_id] = obj

72 return html_id

73 else:

74 # Generate automatic id

75 auto_id = f"auto_{type_name}_{self._auto_counter}"

76 self._auto_counter += 1

77 self._by_id[auto_id] = obj

78 return auto_id

80 def get_by_id(self, identifier: str) -> Optional[Interactable]:

81 """

82 Get an interactable by its id (HTML id or auto-generated id).

84 Args:

85 identifier: The id to lookup (e.g., "save-btn" or "auto_button_0")

87 Returns:

88 The interactable object, or None if not found

90 Example:

91 >>> button = registry.get_by_id("save-btn")

92 >>> if button:

93 ... button._callback = my_save_function

94 """

95 return self._by_id.get(identifier)

97 def get_by_type(self, type_name: str) -> List[Interactable]:

98 """

99 Get all interactables of a specific type.

101 Args:

102 type_name: The type name (e.g., "link", "button", "form_field")

104 Returns:

105 List of interactable objects of that type (may be empty)

107 Example:

108 >>> all_buttons = registry.get_by_type("button")

109 >>> for button in all_buttons:

110 ... print(button.text)

111 """

112 return self._by_type.get(type_name, []).copy()

113

114 def get_all_ids(self) -> List[str]:

115 """

116 Get all registered ids (both HTML ids and auto-generated ids).

118 Returns:

119 List of all ids in the registry

121 Example:

122 >>> ids = registry.get_all_ids()

123 >>> print(ids)

124 ['save-btn', 'cancel-btn', 'auto_link_0', 'auto_button_1']

125 """

126 return list(self._by_id.keys())

127

128 def get_all_types(self) -> List[str]:

129 """

130 Get all registered type names.

131

132 Returns:

133 List of type names that have registered objects

135 Example:

136 >>> types = registry.get_all_types()

137 >>> print(types)

138 ['link', 'button', 'form_field']

139 """

140 return list(self._by_type.keys())

141

142 def set_callback(self, identifier: str, callback: Callable) -> bool:

143 """

144 Set the callback for an interactable by its id.

146 Args:

147 identifier: The id of the interactable

148 callback: The callback function to set

150 Returns:

151 True if the interactable was found and callback set, False otherwise

153 Example:

154 >>> def on_save(point):

155 ... print("Save clicked!")

156 >>> registry.set_callback("save-btn", on_save)

157 True

158 """

159 obj = self.get_by_id(identifier)

160 if obj:

161 obj._callback = callback

162 return True

163 return False

165 def set_callbacks_by_type(self, type_name: str, callback: Callable) -> int:

166 """

167 Set the callback for all interactables of a specific type.

169 Useful for batch operations like setting a default click sound

170 for all buttons, or a default link handler for all links.

172 Args:

173 type_name: The type name (e.g., "button", "link")

174 callback: The callback function to set

175

176 Returns:

177 Number of objects that had their callback set

179 Example:

180 >>> def play_click_sound(point):

181 ... audio.play("click.wav")

182 >>> count = registry.set_callbacks_by_type("button", play_click_sound)

183 >>> print(f"Set callback for {count} buttons")

184 """

185 objects = self.get_by_type(type_name)

186 for obj in objects:

187 obj._callback = callback

188 return len(objects)

189

190 def unregister(self, identifier: str) -> bool:

191 """

192 Unregister an interactable by its id.

194 Args:

195 identifier: The id of the interactable to unregister

197 Returns:

198 True if the interactable was found and unregistered, False otherwise

199 """

200 obj = self._by_id.pop(identifier, None)

201 if obj: 201 ↛ 214line 201 didn't jump to line 214 because the condition on line 201 was always true

202 # Remove from reference map

203 self._by_reference.pop(id(obj), None)

205 # Remove from type map

206 type_name = self._get_type_name(obj)

207 if type_name in self._by_type: 207 ↛ 213line 207 didn't jump to line 213 because the condition on line 207 was always true

208 try:

209 self._by_type[type_name].remove(obj)

210 except ValueError:

211 pass

212

213 return True

214 return False

216 def clear(self):

217 """Clear all registered interactables."""

218 self._by_reference.clear()

219 self._by_id.clear()

220 self._by_type.clear()

221 self._auto_counter = 0

222

223 def count(self) -> int:

224 """

225 Get the total number of registered interactables.

227 Returns:

228 Total count of registered objects

229 """

230 return len(self._by_id)

232 def count_by_type(self, type_name: str) -> int:

233 """

234 Get the count of interactables of a specific type.

236 Args:

237 type_name: The type name to count

239 Returns:

240 Number of objects of that type

241 """

242 return len(self._by_type.get(type_name, []))

244 def _get_type_name(self, obj: Interactable) -> str:

245 """

246 Get a normalized type name for an interactable object.

247

248 Args:

249 obj: The interactable object

251 Returns:

252 Type name string (e.g., "link", "button", "form_field")

253 """

254 # Import here to avoid circular imports

255 from pyWebLayout.concrete.functional import LinkText, ButtonText, FormFieldText

257 if isinstance(obj, LinkText):

258 return "link"

259 elif isinstance(obj, ButtonText):

260 return "button"

261 elif isinstance(obj, FormFieldText): 261 ↛ 265line 261 didn't jump to line 265 because the condition on line 261 was always true

262 return "form_field"

263 else:

264 # Fallback to class name

265 return obj.__class__.__name__.lower()

266

267 def __len__(self) -> int:

268 """Support len() to get count of registered interactables."""

269 return self.count()

271 def __contains__(self, identifier: str) -> bool:

272 """Support 'in' operator to check if an id is registered."""

273 return identifier in self._by_id

275 def __repr__(self) -> str:

276 """String representation showing registry statistics."""

277 type_counts = {t: len(objs) for t, objs in self._by_type.items()}

278 return f"CallbackRegistry(total={self.count()}, types={type_counts})"

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37_highlight_py.html b/cov_info/htmlcov/z_40407af872b0cf37_highlight_py.html new file mode 100644 index 0000000..322c44e --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37_highlight_py.html @@ -0,0 +1,348 @@ + + + + + Coverage for pyWebLayout/core/highlight.py: 97% + + + + + +

+ Coverage for pyWebLayout/core/highlight.py: + 97% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 87 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Text highlighting system for ebook reader.

4Provides data structures and utilities for highlighting text regions,

5managing highlight collections, and rendering highlights on pages.

6"""

8from __future__ import annotations

9import logging

10from dataclasses import dataclass

11from typing import List, Tuple, Optional, Dict, Any

12from enum import Enum

13from pathlib import Path

15from pyWebLayout.core.persistence import ensure_dir, read_json, write_json

17logger = logging.getLogger(__name__)

20class HighlightColor(Enum):

21 """Predefined highlight colors with RGBA values"""

22 YELLOW = (255, 255, 0, 100) # Classic highlight yellow

23 GREEN = (100, 255, 100, 100) # Green for verified/correct

24 BLUE = (100, 200, 255, 100) # Blue for important

25 PINK = (255, 150, 200, 100) # Pink for questions

26 ORANGE = (255, 180, 100, 100) # Orange for warnings

27 PURPLE = (200, 150, 255, 100) # Purple for definitions

28 RED = (255, 100, 100, 100) # Red for errors/concerns

31@dataclass

32class Highlight:

33 """

34 Represents a highlighted text region.

36 Highlights are stored with both pixel bounds (for rendering) and

37 semantic bounds (text content, for persistence across font changes).

38 """

39 # Identification

40 id: str # Unique identifier

42 # Visual properties

43 bounds: List[Tuple[int, int, int, int]] # List of (x, y, w, h) rectangles

44 color: Tuple[int, int, int, int] # RGBA color

46 # Semantic properties (for persistence)

47 text: str # The highlighted text

48 start_word_index: Optional[int] = None # Word index in document (if available)

49 end_word_index: Optional[int] = None

51 # Where in the document this highlight lives, as a serialized

52 # RenderingPosition. `bounds` are pixel coordinates on one particular

53 # rendering, so they stop matching as soon as the font scale or page size

54 # changes; this survives repagination and is what page association uses.

55 position: Optional[Dict[str, Any]] = None

57 # Metadata

58 note: Optional[str] = None # Optional annotation

59 tags: List[str] = None # Optional categorization tags

60 timestamp: Optional[float] = None # When created

62 def __post_init__(self):

63 """Initialize default values"""

64 if self.tags is None:

65 self.tags = []

67 def to_dict(self) -> Dict[str, Any]:

68 """Serialize to dictionary"""

69 return {

70 'id': self.id,

71 'bounds': self.bounds,

72 'color': self.color,

73 'text': self.text,

74 'start_word_index': self.start_word_index,

75 'end_word_index': self.end_word_index,

76 'position': self.position,

77 'note': self.note,

78 'tags': self.tags,

79 'timestamp': self.timestamp

80 }

82 @classmethod

83 def from_dict(cls, data: Dict[str, Any]) -> 'Highlight':

84 """Deserialize from dictionary"""

85 return cls(

86 id=data['id'],

87 bounds=[tuple(b) for b in data['bounds']],

88 color=tuple(data['color']),

89 text=data['text'],

90 start_word_index=data.get('start_word_index'),

91 end_word_index=data.get('end_word_index'),

92 position=data.get('position'),

93 note=data.get('note'),

94 tags=data.get('tags', []),

95 timestamp=data.get('timestamp')

96 )

99class HighlightManager:

100 """

101 Manages highlights for a document.

102

103 Handles adding, removing, listing, and persisting highlights.

104 """

106 def __init__(self, document_id: str, highlights_dir: str = "highlights"):

107 """

108 Initialize highlight manager.

110 Args:

111 document_id: Unique identifier for the document

112 highlights_dir: Directory to store highlight data

113 """

114 self.document_id = document_id

115 self.highlights_dir = ensure_dir(highlights_dir)

116 self.highlights: Dict[str, Highlight] = {} # id -> Highlight

118 # Load existing highlights

119 self._load_highlights()

121 def add_highlight(self, highlight: Highlight) -> None:

122 """

123 Add a highlight.

125 Args:

126 highlight: Highlight to add

127 """

128 self.highlights[highlight.id] = highlight

129 self._save_highlights()

131 def remove_highlight(self, highlight_id: str) -> bool:

132 """

133 Remove a highlight by ID.

135 Args:

136 highlight_id: ID of highlight to remove

138 Returns:

139 True if removed, False if not found

140 """

141 if highlight_id in self.highlights:

142 del self.highlights[highlight_id]

143 self._save_highlights()

144 return True

145 return False

147 def get_highlight(self, highlight_id: str) -> Optional[Highlight]:

148 """Get a highlight by ID"""

149 return self.highlights.get(highlight_id)

151 def list_highlights(self) -> List[Highlight]:

152 """Get all highlights"""

153 return list(self.highlights.values())

155 def clear_all(self) -> None:

156 """Remove all highlights"""

157 self.highlights.clear()

158 self._save_highlights()

159

160 def get_highlights_for_page(

161 self, page_bounds: Tuple[int, int, int, int]) -> List[Highlight]:

162 """

163 Get highlights that appear on a specific page.

165 Args:

166 page_bounds: Page bounds (x, y, width, height)

167

168 Returns:

169 List of highlights on this page

170 """

171 page_x, page_y, page_w, page_h = page_bounds

172 page_highlights = []

174 for highlight in self.highlights.values():

175 # Check if any highlight bounds overlap with page

176 for hx, hy, hw, hh in highlight.bounds:

177 if (hx < page_x + page_w and hx + hw > page_x and

178 hy < page_y + page_h and hy + hh > page_y):

179 page_highlights.append(highlight)

180 break

182 return page_highlights

184 def _get_filepath(self) -> Path:

185 """Get filepath for this document's highlights"""

186 return self.highlights_dir / f"{self.document_id}_highlights.json"

188 def _save_highlights(self) -> None:

189 """Persist highlights to disk"""

190 write_json(self._get_filepath(), {

191 'document_id': self.document_id,

192 'highlights': [h.to_dict() for h in self.highlights.values()]

193 })

195 def _load_highlights(self) -> None:

196 """Load highlights from disk"""

197 data = read_json(self._get_filepath(), {})

198 try:

199 self.highlights = {

200 h['id']: Highlight.from_dict(h)

201 for h in data.get('highlights', [])

202 }

203 except (AttributeError, TypeError, KeyError):

204 logger.warning("Highlight file %s is not in the expected shape; ignoring it",

205 self._get_filepath(), exc_info=True)

206 self.highlights = {}

208

209def create_highlight_from_query_result(

210 result,

211 color: Tuple[int, int, int, int] = HighlightColor.YELLOW.value,

212 note: Optional[str] = None,

213 tags: Optional[List[str]] = None,

214 position: Optional[Dict[str, Any]] = None

215) -> Highlight:

216 """

217 Create a highlight from a QueryResult.

219 Args:

220 result: QueryResult from query_point or query_range

221 color: RGBA color tuple

222 note: Optional annotation

223 tags: Optional categorization tags

224 position: Serialized RenderingPosition of the page the result came from

226 Returns:

227 Highlight instance

228 """

229 from time import time

230 import uuid

232 # Handle single result or SelectionRange

233 if hasattr(result, 'results'): # SelectionRange

234 bounds = result.bounds_list

235 text = result.text

236 else: # Single QueryResult

237 bounds = [result.bounds]

238 text = result.text or ""

240 return Highlight(

241 id=str(uuid.uuid4()),

242 bounds=bounds,

243 color=color,

244 text=text,

245 position=position,

246 note=note,

247 tags=tags or [],

248 timestamp=time()

249 )

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37_persistence_py.html b/cov_info/htmlcov/z_40407af872b0cf37_persistence_py.html new file mode 100644 index 0000000..f245e8c --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37_persistence_py.html @@ -0,0 +1,158 @@ + + + + + Coverage for pyWebLayout/core/persistence.py: 90% + + + + + +

+ Coverage for pyWebLayout/core/persistence.py: + 90% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 27 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Small JSON-file helpers shared by the per-document stores.

4BookmarkManager and HighlightManager both keep a JSON file per document under a

5directory, and both had their own copy of "make the directory, try to read it,

6swallow and print on failure". The duplication is the point of this module; the

7file formats themselves stay owned by each store.

8"""

10from __future__ import annotations

12import json

13import logging

14from pathlib import Path

15from typing import Any

17logger = logging.getLogger(__name__)

20def ensure_dir(path: str | Path) -> Path:

21 """Return `path` as a Path, creating it and any missing parents."""

22 directory = Path(path)

23 directory.mkdir(parents=True, exist_ok=True)

24 return directory

27def read_json(path: Path, default: Any) -> Any:

28 """

29 Read JSON from `path`, returning `default` if it is missing or unreadable.

31 A corrupt store must not stop a book from opening, so failures are logged

32 and swallowed. `default` is returned as given, so pass a fresh mutable if

33 the caller intends to mutate it.

34 """

35 if not path.exists():

36 return default

38 try:

39 with open(path, 'r', encoding='utf-8') as handle:

40 return json.load(handle)

41 except (OSError, ValueError):

42 logger.warning("Could not read %s; ignoring its contents", path, exc_info=True)

43 return default

46def write_json(path: Path, data: Any) -> bool:

47 """

48 Write `data` to `path` as JSON.

50 Returns True on success. Failures are logged rather than raised: losing a

51 bookmark is not a reason to take down the reader.

52 """

53 try:

54 with open(path, 'w', encoding='utf-8') as handle:

55 json.dump(data, handle, indent=2)

56 return True

57 except (OSError, TypeError, ValueError):

58 logger.error("Could not write %s", path, exc_info=True)

59 return False

+ + + diff --git a/cov_info/htmlcov/z_40407af872b0cf37_query_py.html b/cov_info/htmlcov/z_40407af872b0cf37_query_py.html new file mode 100644 index 0000000..78fcefd --- /dev/null +++ b/cov_info/htmlcov/z_40407af872b0cf37_query_py.html @@ -0,0 +1,185 @@ + + + + + Coverage for pyWebLayout/core/query.py: 94% + + + + + +

+ Coverage for pyWebLayout/core/query.py: + 94% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 33 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Query system for pixel-to-content mapping.

4This module provides data structures for querying rendered content,

5enabling interactive features like link clicking, word definition lookup,

6and text selection.

7"""

9from __future__ import annotations

10from dataclasses import dataclass

11from typing import Optional, Tuple, List, Any, TYPE_CHECKING

13if TYPE_CHECKING: 13 ↛ 14line 13 didn't jump to line 14 because the condition on line 13 was never true

14 from pyWebLayout.core.base import Queriable

17@dataclass

18class QueryResult:

19 """

20 Result of querying a point on a rendered page.

22 This encapsulates all information about what was found at a pixel location,

23 including geometry, content, and interaction capabilities.

24 """

25 # What was found

26 object: 'Queriable' # The object at this point

27 object_type: str # "link", "text", "image", "button", "word", "empty"

29 # Geometry

30 bounds: Tuple[int, int, int, int] # (x, y, width, height) in page coordinates

32 # Content (for text/words)

33 text: Optional[str] = None

34 word_index: Optional[int] = None # Index in abstract document structure

35 block_index: Optional[int] = None # Block index in document

37 # Interaction (for links/buttons)

38 is_interactive: bool = False

39 link_target: Optional[str] = None # URL or internal reference

40 callback: Optional[Any] = None # Interaction callback

42 # Hierarchy (for debugging/traversal)

43 parent_line: Optional[Any] = None

44 parent_page: Optional[Any] = None

46 def to_dict(self) -> dict:

47 """Convert to dictionary for serialization"""

48 return {

49 'object_type': self.object_type,

50 'bounds': self.bounds,

51 'text': self.text,

52 'is_interactive': self.is_interactive,

53 'link_target': self.link_target,

54 'word_index': self.word_index,

55 'block_index': self.block_index

56 }

59@dataclass

60class SelectionRange:

61 """

62 Represents a range of selected text between two points.

63 """

64 start_point: Tuple[int, int]

65 end_point: Tuple[int, int]

66 results: List[QueryResult] # All query results in the range

68 @property

69 def text(self) -> str:

70 """Get concatenated text from all results"""

71 return " ".join(r.text for r in self.results if r.text)

73 @property

74 def bounds_list(self) -> List[Tuple[int, int, int, int]]:

75 """Get list of all bounding boxes for highlighting"""

76 return [r.bounds for r in self.results]

78 def to_dict(self) -> dict:

79 """Convert to dictionary for serialization"""

80 return {

81 'start': self.start_point,

82 'end': self.end_point,

83 'text': self.text,

84 'word_count': len(self.results),

85 'bounds': self.bounds_list

86 }

+ + + diff --git a/cov_info/htmlcov/z_427cc3035faf7633___init___py.html b/cov_info/htmlcov/z_427cc3035faf7633___init___py.html new file mode 100644 index 0000000..0064709 --- /dev/null +++ b/cov_info/htmlcov/z_427cc3035faf7633___init___py.html @@ -0,0 +1,110 @@ + + + + + Coverage for pyWebLayout/layout/__init__.py: 100% + + + + + +

+ Coverage for pyWebLayout/layout/init.py: + 100% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 0 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Typesetting module for the pyWebLayout library.

4This package handles the organization and arrangement of elements for rendering, including:

5- Flow layout algorithms

6- Container management

7- Element positioning and sizing

8- Content wrapping and overflow

9- Coordinate systems and transformations

10- Pagination for book-like content

11"""

+ + + diff --git a/cov_info/htmlcov/z_427cc3035faf7633_document_layouter_py.html b/cov_info/htmlcov/z_427cc3035faf7633_document_layouter_py.html new file mode 100644 index 0000000..1c57226 --- /dev/null +++ b/cov_info/htmlcov/z_427cc3035faf7633_document_layouter_py.html @@ -0,0 +1,836 @@ + + + + + Coverage for pyWebLayout/layout/document_layouter.py: 77% + + + + + +

+ Coverage for pyWebLayout/layout/document_layouter.py: + 77% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 219 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

3from typing import List, Tuple, Optional, Union

4import numpy as np

6from pyWebLayout.concrete import Page, Line, Text

7from pyWebLayout.concrete.image import RenderableImage

8from pyWebLayout.concrete.functional import ButtonText, FormFieldText

9from pyWebLayout.concrete.table import TableRenderer, TableStyle

10from pyWebLayout.abstract import Paragraph, Word

11from pyWebLayout.abstract.block import Image as AbstractImage, Heading, PageBreak, Table

12from pyWebLayout.abstract.functional import Button, Form, FormField

13from pyWebLayout.style.concrete_style import ConcreteStyleRegistry, RenderingContext, StyleResolver

14from pyWebLayout.style import Font, Alignment

17def paragraph_layouter(paragraph: Paragraph,

18 page: Page,

19 start_word: int = 0,

20 pretext: Optional[Text] = None,

21 alignment_override: Optional['Alignment'] = None) -> Tuple[bool,

22 Optional[int],

23 Optional[Text]]:

24 """

25 Layout a paragraph of text within a given page.

27 This function extracts word spacing constraints from the style system

28 and uses them to create properly spaced lines of text.

30 Args:

31 paragraph: The paragraph to layout

32 page: The page to layout the paragraph on

33 start_word: Index of the first word to process (for continuation)

34 pretext: Optional pretext from a previous hyphenated word

35 alignment_override: Optional alignment to override the paragraph's default alignment

37 Returns:

38 Tuple of:

39 - bool: True if paragraph was completely laid out, False if page ran out of space

40 - Optional[int]: Index of first word that didn't fit (if any)

41 - Optional[Text]: Remaining pretext if word was hyphenated (if any)

42 """

43 if not paragraph.words:

44 return True, None, None

46 # Validate inputs

47 if start_word >= len(paragraph.words):

48 return True, None, None

50 # paragraph.style is already a Font object (concrete), not AbstractStyle

51 # We need to get word spacing constraints from the Font's abstract style if available

52 # For now, use reasonable defaults based on font size

54 # Alignment for text that does not specify its own. Headings are never

55 # justified - stretching a two-word title across the measure is always wrong -

56 # so they fall back to flush left.

57 default_alignment = getattr(page.style, 'default_alignment', None)

58 if not isinstance(default_alignment, Alignment):

59 default_alignment = Alignment.JUSTIFY

60 if isinstance(paragraph, Heading):

61 default_alignment = Alignment.LEFT

63 if isinstance(paragraph.style, Font):

64 # paragraph.style is already a Font (concrete style)

65 font = paragraph.style

66 # Use default word spacing constraints based on font size

67 # Minimum spacing should be proportional to font size for better readability

68 min_spacing = float(font.font_size) * 0.25 # 25% of font size

69 max_spacing = float(font.font_size) * 0.5 # 50% of font size

70 word_spacing_constraints = (int(min_spacing), int(max_spacing))

71 text_align = default_alignment

72 else:

73 # paragraph.style is an AbstractStyle, resolve it

74 # Ensure font_size is an int (it could be a FontSize enum)

75 from pyWebLayout.style.abstract_style import FontSize

76 if isinstance(paragraph.style.font_size, FontSize): 76 ↛ 80line 76 didn't jump to line 80 because the condition on line 76 was always true

77 # Use a default base font size, the resolver will handle the semantic size

78 base_font_size = 16

79 else:

80 base_font_size = int(paragraph.style.font_size)

82 rendering_context = RenderingContext(base_font_size=base_font_size)

83 style_resolver = StyleResolver(rendering_context)

84 style_registry = ConcreteStyleRegistry(style_resolver)

85 concrete_style = style_registry.get_concrete_style(paragraph.style)

86 font = concrete_style.create_font()

87 word_spacing_constraints = (

88 int(concrete_style.word_spacing_min),

89 int(concrete_style.word_spacing_max)

90 )

91 # text_align is None when the source did not specify one.

92 text_align = concrete_style.text_align or default_alignment

94 # Apply page-level word spacing override if specified

95 if hasattr( 95 ↛ 101line 95 didn't jump to line 101 because the condition on line 95 was never true

96 page.style,

97 'word_spacing') and isinstance(

98 page.style.word_spacing,

99 int) and page.style.word_spacing > 0:

100 # Add the page-level word spacing to both min and max constraints

101 min_ws, max_ws = word_spacing_constraints

102 word_spacing_constraints = (

103 min_ws + page.style.word_spacing,

104 max_ws + page.style.word_spacing

105 )

107 # Apply alignment override if provided

108 if alignment_override is not None:

109 text_align = alignment_override

111 # Cap font size to page maximum if needed

112 if font.font_size > page.style.max_font_size: 112 ↛ 114line 112 didn't jump to line 114 because the condition on line 112 was never true

113 # Use paragraph's font registry to create the capped font

114 if hasattr(paragraph, 'get_or_create_font'):

115 font = paragraph.get_or_create_font(

116 font_path=font._font_path,

117 font_size=page.style.max_font_size,

118 colour=font.colour,

119 weight=font.weight,

120 style=font.style,

121 decoration=font.decoration,

122 background=font.background

123 )

124 else:

125 # Fallback to direct creation (will still use global cache)

126 font = Font(

127 font_path=font._font_path,

128 font_size=page.style.max_font_size,

129 colour=font.colour,

130 weight=font.weight,

131 style=font.style,

132 decoration=font.decoration,

133 background=font.background

134 )

136 # Calculate baseline-to-baseline spacing: font size + additional line spacing

137 # This is the vertical distance between baselines of consecutive lines

138 # Formula: baseline_spacing = font_size + line_spacing (absolute pixels)

139 line_spacing_value = getattr(page.style, 'line_spacing', 5)

140 # Ensure line_spacing is an int (could be Mock in tests)

141 if not isinstance(line_spacing_value, int):

142 line_spacing_value = 5

143 baseline_spacing = font.font_size + line_spacing_value

145 # Get font metrics for boundary checking

146 ascent, descent = font.font.getmetrics()

148 def create_new_line(word: Optional[Union[Word, Text]] = None,

149 is_first_line: bool = False) -> Optional[Line]:

150 """Helper function to create a new line, returns None if page is full."""

151 # Check if this line's baseline and descenders would fit on the page

152 if not page.can_fit_line(baseline_spacing, ascent, descent):

153 return None

155 # For the first line, position it so text starts at the top boundary

156 # For subsequent lines, use current y_offset which tracks

157 # baseline-to-baseline spacing

158 if is_first_line: 158 ↛ 161line 158 didn't jump to line 161 because the condition on line 158 was never true

159 # Position line origin so that baseline (origin + ascent) is close to top

160 # We want minimal space above the text, so origin should be at boundary

161 y_cursor = page._current_y_offset

162 else:

163 y_cursor = page._current_y_offset

164 x_cursor = page.content_origin[0]

166 # `word` is accepted for call-site readability only: the line that is about

167 # to be created measures it when it is added, so measuring it here as well

168 # only paid for a Text object that was immediately discarded.

170 return Line(

171 spacing=word_spacing_constraints,

172 origin=(x_cursor, y_cursor),

173 size=(page.available_width, baseline_spacing),

174 draw=page.measurement_draw,

175 font=font,

176 halign=text_align

177 )

179 # Create initial line

180 current_line = create_new_line()

181 if not current_line:

182 return False, start_word, pretext

184 page.add_child(current_line)

185 # Note: add_child already updates _current_y_offset based on child's origin and size

186 # No need to manually increment it here

188 # Track current position in paragraph

189 current_pretext = pretext

191 # Process words starting from start_word

192 for i, word in enumerate(paragraph.words[start_word:], start=start_word):

193 # Check if this is a LinkedWord and needs special handling in concrete layer

194 # Note: The Line.add_word method will create Text objects internally,

195 # but we may want to create LinkText for LinkedWord instances in future

196 # For now, the abstract layer (LinkedWord) carries the link info,

197 # and the concrete layer (LinkText) would be created during rendering

199 success, overflow_text = current_line.add_word(word, current_pretext)

200

201 if success:

202 # Word fit successfully

203 if overflow_text is not None:

204 # If there's overflow text, we need to start a new line with it

205 current_pretext = overflow_text

206 current_line = create_new_line(overflow_text)

207 if not current_line:

208 # If we can't create a new line, return with the current state

209 return False, i, overflow_text

210 page.add_child(current_line)

211 # Note: add_child already updates _current_y_offset

212 # Continue to the next word

213 continue

214 else:

215 # No overflow, clear pretext

216 current_pretext = None

217 else:

218 # Word didn't fit, need a new line

219 current_line = create_new_line(word)

220 if not current_line:

221 # Page is full, return current position

222 return False, i, overflow_text

223

224 # Check if the word will fit on the new line before adding it

225 temp_text = Text.from_word(word, page.measurement_draw)

226 if temp_text.width > current_line.size[0]:

227 # Word is too wide for the line, we need to hyphenate it

228 if len(word.text) >= 6: 228 ↛ 250line 228 didn't jump to line 250 because the condition on line 228 was always true

229 # Try to hyphenate the word

230 splits = [

231 (Text(

232 pair[0],

233 word.style,

234 page.measurement_draw,

235 line=current_line,

236 source=word),

237 Text(

238 pair[1],

239 word.style,

240 page.measurement_draw,

241 line=current_line,

242 source=word)) for pair in word.possible_hyphenation()]

243 if len(splits) > 0: 243 ↛ 250line 243 didn't jump to line 250 because the condition on line 243 was always true

244 # Use the first hyphenation point

245 first_part, second_part = splits[0]

246 current_line.add_word(word, first_part)

247 current_pretext = second_part

248 continue

250 page.add_child(current_line)

251 # Note: add_child already updates _current_y_offset

253 # Try to add the word to the new line

254 success, overflow_text = current_line.add_word(word, current_pretext)

256 if not success: 256 ↛ 259line 256 didn't jump to line 259 because the condition on line 256 was never true

257 # Word still doesn't fit even on a new line

258 # This might happen with very long words or narrow pages

259 if overflow_text:

260 # Word was hyphenated, continue with the overflow

261 current_pretext = overflow_text

262 continue

263 else:

264 # Word cannot be broken, skip it or handle as error

265 # For now, we'll return indicating we couldn't process this word

266 return False, i, None

267 else:

268 current_pretext = overflow_text # May be None or hyphenated remainder

270 # All words processed successfully. The line holding the final word is the

271 # end of the paragraph, so it is rendered at its natural width rather than

272 # justified to the full column. A paragraph continued on the next page does

273 # not reach here, so its lines stay justified - which is correct.

274 if current_line is not None: 274 ↛ 277line 274 didn't jump to line 277 because the condition on line 274 was always true

275 current_line.is_paragraph_end = True

277 return True, None, None

278

280def pagebreak_layouter(page_break: PageBreak, page: Page) -> bool:

281 """

282 Handle a page break element.

284 A page break signals that all subsequent content should start on a new page.

285 This function always returns False to indicate that the current page is complete

286 and a new page should be created for subsequent content.

288 Args:

289 page_break: The PageBreak block

290 page: The current page (not used, but kept for consistency)

291

292 Returns:

293 bool: Always False to force creation of a new page

294 """

295 # Page break always forces a new page

296 return False

299def image_layouter(image: AbstractImage, page: Page, max_width: Optional[int] = None,

300 max_height: Optional[int] = None) -> bool:

301 """

302 Layout an image within a given page.

304 This function places an image on the page, respecting size constraints

305 and available space. Images are centered horizontally by default.

307 Args:

308 image: The abstract Image object to layout

309 page: The page to layout the image on

310 max_width: Maximum width constraint (defaults to page available width)

311 max_height: Maximum height constraint (defaults to remaining page height)

313 Returns:

314 bool: True if image was successfully laid out, False if page ran out of space

315 """

316 # Use page available width if max_width not specified

317 if max_width is None:

318 max_width = page.available_width

319

320 # Calculate available height on page

321 available_height = page.remaining_height

322

323 # If no space available, image doesn't fit

324 if available_height <= 0: 324 ↛ 325line 324 didn't jump to line 325 because the condition on line 324 was never true

325 return False

327 if max_height is None:

328 max_height = available_height

329 else:

330 max_height = min(max_height, available_height)

332 # Calculate scaled dimensions

333 scaled_width, scaled_height = image.calculate_scaled_dimensions(

334 max_width, max_height)

336 # Check if image fits on current page

337 if scaled_height is None or scaled_height > available_height:

338 return False

339

340 # Create renderable image

341 x_offset = page.content_origin[0]

342 y_offset = page._current_y_offset

344 # Access page.draw to ensure canvas is initialized

345 _ = page.draw

347 renderable_image = RenderableImage(

348 image=image,

349 canvas=page._canvas,

350 max_width=max_width,

351 max_height=max_height,

352 origin=(x_offset, y_offset),

353 size=(scaled_width or max_width, scaled_height or max_height),

354 halign=Alignment.CENTER,

355 valign=Alignment.TOP

356 )

357

358 # Add to page

359 page.add_child(renderable_image)

360

361 return True

364def table_layouter(

365 table: Table,

366 page: Page,

367 style: Optional[TableStyle] = None) -> bool:

368 """

369 Layout a table within a given page.

371 This function uses the TableRenderer to render the table at the current

372 page position, advancing the page's y-offset after successful rendering.

373

374 Args:

375 table: The abstract Table object to layout

376 page: The page to layout the table on

377 style: Optional table styling configuration

379 Returns:

380 bool: True if table was successfully laid out, False if page ran out of space

381 """

382 # Calculate available space

383 available_width = page.available_width

384 x_offset = page.content_origin[0]

385 y_offset = page._current_y_offset

386

387 # Access page.draw to ensure canvas is initialized

388 draw = page.draw

389 canvas = page._canvas

390

391 # Create table renderer

392 origin = (x_offset, y_offset)

393 renderer = TableRenderer(

394 table=table,

395 origin=origin,

396 available_width=available_width,

397 draw=draw,

398 style=style,

399 canvas=canvas

400 )

401

402 # Check if table fits on current page

403 table_height = renderer.size[1]

404 available_height = page.remaining_height

405

406 if table_height > available_height:

407 return False

409 # Render the table

410 renderer.render()

411

412 # Update page y-offset

413 page._current_y_offset = y_offset + table_height

414

415 return True

416

418def button_layouter(button: Button,

419 page: Page,

420 font: Optional[Font] = None,

421 padding: Tuple[int,

422 int,

423 int,

424 int] = (4,

425 8,

426 4,

427 8)) -> Tuple[bool,

428 str]:

429 """

430 Layout a button within a given page and register it for callback binding.

432 This function creates a ButtonText renderable, positions it on the page,

433 and registers it in the page's callback registry using the button's html_id

434 (if available) or an auto-generated id.

436 Args:

437 button: The abstract Button object to layout

438 page: The page to layout the button on

439 font: Optional font for button text (defaults to page default)

440 padding: Padding around button text (top, right, bottom, left)

442 Returns:

443 Tuple of:

444 - bool: True if button was successfully laid out, False if page ran out of space

445 - str: The id used to register the button in the callback registry

446 """

447 # Use provided font or create a default one

448 if font is None:

449 font = Font(font_size=14, colour=(255, 255, 255))

450

451 # Calculate available space

452 available_height = page.remaining_height

453

454 # Create ButtonText renderable

455 button_text = ButtonText(button, font, page.measurement_draw, padding=padding)

457 # Check if button fits on current page

458 button_height = button_text.size[1]

459 if button_height > available_height:

460 return False, ""

461

462 # Position the button

463 x_offset = page.content_origin[0]

464 y_offset = page._current_y_offset

465

466 button_text.set_origin(np.array([x_offset, y_offset]))

467

468 # Register in callback registry

469 html_id = button.html_id

470 registered_id = page.callbacks.register(button_text, html_id=html_id)

471

472 # Add to page

473 page.add_child(button_text)

475 return True, registered_id

476

477

478def form_field_layouter(field: FormField, page: Page, font: Optional[Font] = None,

479 field_height: int = 24) -> Tuple[bool, str]:

480 """

481 Layout a form field within a given page and register it for callback binding.

482

483 This function creates a FormFieldText renderable, positions it on the page,

484 and registers it in the page's callback registry.

485

486 Args:

487 field: The abstract FormField object to layout

488 page: The page to layout the field on

489 font: Optional font for field label (defaults to page default)

490 field_height: Height of the input field area

491

492 Returns:

493 Tuple of:

494 - bool: True if field was successfully laid out, False if page ran out of space

495 - str: The id used to register the field in the callback registry

496 """

497 # Use provided font or create a default one

498 if font is None: 498 ↛ 499line 498 didn't jump to line 499 because the condition on line 498 was never true

499 font = Font(font_size=12, colour=(0, 0, 0))

500

501 # Calculate available space

502 available_height = page.remaining_height

504 # Create FormFieldText renderable

505 field_text = FormFieldText(field, font, page.measurement_draw,

506 field_height=field_height)

507

508 # Check if field fits on current page

509 total_field_height = field_text.size[1]

510 if total_field_height > available_height: 510 ↛ 511line 510 didn't jump to line 511 because the condition on line 510 was never true

511 return False, ""

512

513 # Position the field

514 x_offset = page.content_origin[0]

515 y_offset = page._current_y_offset

517 field_text.set_origin(np.array([x_offset, y_offset]))

518

519 # Register in callback registry (use field name as html_id fallback)

520 html_id = getattr(field, '_html_id', None) or field.name

521 registered_id = page.callbacks.register(field_text, html_id=html_id)

522

523 # Add to page

524 page.add_child(field_text)

526 return True, registered_id

527

529def form_layouter(form: Form, page: Page, font: Optional[Font] = None,

530 field_spacing: int = 10) -> Tuple[bool, List[str]]:

531 """

532 Layout a complete form with all its fields within a given page.

533

534 This function creates FormFieldText renderables for all fields in the form,

535 positions them vertically, and registers both the form and its fields in

536 the page's callback registry.

538 Args:

539 form: The abstract Form object to layout

540 page: The page to layout the form on

541 font: Optional font for field labels (defaults to page default)

542 field_spacing: Vertical spacing between fields in pixels

543

544 Returns:

545 Tuple of:

546 - bool: True if form was successfully laid out, False if page ran out of space

547 - List[str]: List of registered ids for all fields (empty if layout failed)

548 """

549 # Use provided font or create a default one

550 if font is None: 550 ↛ 551line 550 didn't jump to line 551 because the condition on line 550 was never true

551 font = Font(font_size=12, colour=(0, 0, 0))

552

553 # Track registered field ids

554 field_ids = []

555

556 # Layout each field in the form

557 for field_name, field in form._fields.items():

558 # Add spacing before each field (except the first)

559 if field_ids:

560 page._current_y_offset += field_spacing

561

562 # Layout the field

563 success, field_id = form_field_layouter(field, page, font)

565 if not success: 565 ↛ 567line 565 didn't jump to line 567 because the condition on line 565 was never true

566 # Couldn't fit this field, return failure

567 return False, []

568

569 field_ids.append(field_id)

570

571 # Register the form itself (optional, for form submission)

572 # Note: The form doesn't have a visual representation, but we can track it

573 # for submission callbacks

574 # form_id = page.callbacks.register(form, html_id=form.html_id)

576 return True, field_ids

577

578

579class DocumentLayouter:

580 """

581 Document layouter that orchestrates layout of various abstract elements.

582

583 Delegates to specialized layouters for different content types:

584 - paragraph_layouter for text paragraphs

585 - image_layouter for images

586 - table_layouter for tables

587

588 This class acts as a coordinator, managing the overall document flow

589 and page context while delegating specific layout tasks to specialized

590 layouter functions.

591 """

592

593 def __init__(self, page: Page):

594 """

595 Initialize the document layouter with a page.

596

597 Args:

598 page: The page to layout content on

599 """

600 self.page = page

601 # Create a style resolver if page doesn't have one

602 if hasattr(page, 'style_resolver'):

603 style_resolver = page.style_resolver

604 else:

605 # Create a default rendering context and style resolver

606 from pyWebLayout.style.concrete_style import RenderingContext

607 context = RenderingContext()

608 style_resolver = StyleResolver(context)

609 self.style_registry = ConcreteStyleRegistry(style_resolver)

610

611 def layout_paragraph(self,

612 paragraph: Paragraph,

613 start_word: int = 0,

614 pretext: Optional[Text] = None) -> Tuple[bool,

615 Optional[int],

616 Optional[Text]]:

617 """

618 Layout a paragraph using the paragraph_layouter.

619

620 Args:

621 paragraph: The paragraph to layout

622 start_word: Index of the first word to process (for continuation)

623 pretext: Optional pretext from a previous hyphenated word

624

625 Returns:

626 Tuple of (success, failed_word_index, remaining_pretext)

627 """

628 return paragraph_layouter(paragraph, self.page, start_word, pretext)

629

630 def layout_image(self, image: AbstractImage, max_width: Optional[int] = None,

631 max_height: Optional[int] = None) -> bool:

632 """

633 Layout an image using the image_layouter.

635 Args:

636 image: The abstract Image object to layout

637 max_width: Maximum width constraint (defaults to page available width)

638 max_height: Maximum height constraint (defaults to remaining page height)

639

640 Returns:

641 bool: True if image was successfully laid out, False if page ran out of space

642 """

643 return image_layouter(image, self.page, max_width, max_height)

644

645 def layout_table(self, table: Table, style: Optional[TableStyle] = None) -> bool:

646 """

647 Layout a table using the table_layouter.

648

649 Args:

650 table: The abstract Table object to layout

651 style: Optional table styling configuration

652

653 Returns:

654 bool: True if table was successfully laid out, False if page ran out of space

655 """

656 return table_layouter(table, self.page, style)

657

658 def layout_button(self,

659 button: Button,

660 font: Optional[Font] = None,

661 padding: Tuple[int,

662 int,

663 int,

664 int] = (4,

665 8,

666 4,

667 8)) -> Tuple[bool,

668 str]:

669 """

670 Layout a button using the button_layouter.

671

672 Args:

673 button: The abstract Button object to layout

674 font: Optional font for button text

675 padding: Padding around button text

676

677 Returns:

678 Tuple of (success, registered_id)

679 """

680 return button_layouter(button, self.page, font, padding)

681

682 def layout_form(self, form: Form, font: Optional[Font] = None,

683 field_spacing: int = 10) -> Tuple[bool, List[str]]:

684 """

685 Layout a form using the form_layouter.

686

687 Args:

688 form: The abstract Form object to layout

689 font: Optional font for field labels

690 field_spacing: Vertical spacing between fields

692 Returns:

693 Tuple of (success, list_of_field_ids)

694 """

695 return form_layouter(form, self.page, font, field_spacing)

696

697 def layout_document(

698 self, elements: List[Union[Paragraph, AbstractImage, Table, Button, Form]]) -> bool:

699 """

700 Layout a list of abstract elements (paragraphs, images, tables, buttons, and forms).

701

702 This method delegates to specialized layouters based on element type:

703 - Paragraphs are handled by layout_paragraph

704 - Images are handled by layout_image

705 - Tables are handled by layout_table

706 - Buttons are handled by layout_button

707 - Forms are handled by layout_form

708

709 Args:

710 elements: List of abstract elements to layout

711

712 Returns:

713 True if all elements were successfully laid out, False otherwise

714 """

715 for element in elements:

716 if isinstance(element, Paragraph):

717 success, _, _ = self.layout_paragraph(element)

718 if not success:

719 return False

720 elif isinstance(element, AbstractImage):

721 success = self.layout_image(element)

722 if not success: 722 ↛ 723line 722 didn't jump to line 723 because the condition on line 722 was never true

723 return False

724 elif isinstance(element, Table): 724 ↛ 728line 724 didn't jump to line 728 because the condition on line 724 was always true

725 success = self.layout_table(element)

726 if not success:

727 return False

728 elif isinstance(element, Button):

729 success, _ = self.layout_button(element)

730 if not success:

731 return False

732 elif isinstance(element, Form):

733 success, _ = self.layout_form(element)

734 if not success:

735 return False

736 # Future: elif isinstance(element, CodeBlock): use code_layouter

737 return True

+ + + diff --git a/cov_info/htmlcov/z_427cc3035faf7633_ereader_layout_py.html b/cov_info/htmlcov/z_427cc3035faf7633_ereader_layout_py.html new file mode 100644 index 0000000..2d2dcde --- /dev/null +++ b/cov_info/htmlcov/z_427cc3035faf7633_ereader_layout_py.html @@ -0,0 +1,917 @@ + + + + + Coverage for pyWebLayout/layout/ereader_layout.py: 90% + + + + + +

+ Coverage for pyWebLayout/layout/ereader_layout.py: + 90% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 304 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Enhanced ereader layout system with position tracking, font scaling, and multi-page support.

4This module provides the core infrastructure for building high-performance ereader applications

5with features like:

6- Precise position tracking tied to abstract document structure

7- Font scaling support

8- Bidirectional page rendering (forward/backward)

9- Chapter navigation based on HTML headings

10- Multi-process page buffering

11- Sub-second page rendering performance

12"""

14from __future__ import annotations

15from dataclasses import dataclass, asdict

16from typing import List, Dict, Tuple, Optional, Any

18from pyWebLayout.abstract.block import (

19 Block, Paragraph, Heading, HeadingLevel, Table, TableRow, TableCell,

20 HList, ListItem, Quote, Image)

21from pyWebLayout.abstract.inline import Word

22from pyWebLayout.concrete.page import Page

23from pyWebLayout.concrete.text import Text

24from pyWebLayout.style.page_style import PageStyle

25from pyWebLayout.style import Font

26from pyWebLayout.style.fonts import BundledFont, get_bundled_font_path, FontWeight, FontStyle

27from pyWebLayout.layout.document_layouter import paragraph_layouter, image_layouter

30@dataclass

31class RenderingPosition:

32 """

33 Complete state for resuming rendering at any point in a document.

34 Position is tied to abstract document structure for stability across font changes.

35 """

36 chapter_index: int = 0 # Which chapter (based on headings)

37 block_index: int = 0 # Which block within chapter

38 # Which word within block (for paragraphs)

39 word_index: int = 0

40 table_row: int = 0 # Which row for tables

41 table_col: int = 0 # Which column for tables

42 list_item_index: int = 0 # Which item for lists

43 remaining_pretext: Optional[str] = None # Hyphenated word continuation

44 page_y_offset: int = 0 # Vertical position on page

46 def _key(self) -> Tuple[Any, ...]:

47 """

48 The fields in declaration order.

50 Copying, comparing and hashing a position all used to go through

51 dataclasses.asdict, which walks the field list and deep-copies each value.

52 Every field here is an immutable scalar, so that traversal bought nothing

53 and these three run constantly during page navigation and buffer lookups.

54 """

55 return (self.chapter_index, self.block_index, self.word_index,

56 self.table_row, self.table_col, self.list_item_index,

57 self.remaining_pretext, self.page_y_offset)

59 def to_dict(self) -> Dict[str, Any]:

60 """Serialize position for saving to file/database"""

61 return asdict(self)

63 @classmethod

64 def from_dict(cls, data: Dict[str, Any]) -> 'RenderingPosition':

65 """Deserialize position from saved state"""

66 return cls(**data)

68 def copy(self) -> 'RenderingPosition':

69 """Create a copy of this position"""

70 return RenderingPosition(*self._key())

72 def __eq__(self, other) -> bool:

73 """Check if two positions are equal"""

74 if not isinstance(other, RenderingPosition):

75 return False

76 return self._key() == other._key()

78 def __hash__(self) -> int:

79 """Make position hashable for use as dict key"""

80 return hash(self._key())

83class ChapterInfo:

84 """Information about a chapter/section in the document"""

86 def __init__(

87 self,

88 title: str,

89 level: HeadingLevel,

90 position: RenderingPosition,

91 block_index: int):

92 self.title = title

93 self.level = level

94 self.position = position

95 self.block_index = block_index

98class ChapterNavigator:

99 """

100 Handles chapter/section navigation based on HTML heading structure (H1-H6).

101 Builds a table of contents and provides navigation capabilities.

102 """

104 def __init__(self, blocks: List[Block]):

105 self.blocks = blocks

106 self.chapters: List[ChapterInfo] = []

107 self._build_chapter_map()

109 def _build_chapter_map(self):

110 """Scan blocks for headings and build chapter navigation map"""

111 current_chapter_index = 0

113 # Check if first block is a cover image and add it to TOC

114 if self.blocks and isinstance(self.blocks[0], Image):

115 cover_position = RenderingPosition(

116 chapter_index=0,

117 block_index=0,

118 word_index=0,

119 table_row=0,

120 table_col=0,

121 list_item_index=0

122 )

123

124 cover_info = ChapterInfo(

125 title="Cover",

126 level=HeadingLevel.H1, # Treat as top-level entry

127 position=cover_position,

128 block_index=0

129 )

131 self.chapters.append(cover_info)

133 for block_index, block in enumerate(self.blocks):

134 if isinstance(block, Heading):

135 # Create position for this heading

136 position = RenderingPosition(

137 chapter_index=current_chapter_index,

138 block_index=block_index, # Use actual block index

139 word_index=0,

140 table_row=0,

141 table_col=0,

142 list_item_index=0

143 )

145 # Extract heading text

146 heading_text = self._extract_heading_text(block)

148 chapter_info = ChapterInfo(

149 title=heading_text,

150 level=block.level,

151 position=position,

152 block_index=block_index

153 )

155 self.chapters.append(chapter_info)

157 # Only increment chapter index for top-level headings (H1)

158 if block.level == HeadingLevel.H1:

159 current_chapter_index += 1

161 def _extract_heading_text(self, heading: Heading) -> str:

162 """Extract text content from a heading block"""

163 words = []

164 for position, word in heading.words_iter():

165 if isinstance(word, Word): 165 ↛ 164line 165 didn't jump to line 164 because the condition on line 165 was always true

166 words.append(word.text)

167 return " ".join(words)

169 def get_table_of_contents(

170 self) -> List[Tuple[str, HeadingLevel, RenderingPosition]]:

171 """Generate table of contents from heading structure"""

172 return [(chapter.title, chapter.level, chapter.position)

173 for chapter in self.chapters]

175 def get_chapter_position(self, chapter_title: str) -> Optional[RenderingPosition]:

176 """Get rendering position for a chapter by title"""

177 for chapter in self.chapters:

178 if chapter.title.lower() == chapter_title.lower():

179 return chapter.position

180 return None

182 def get_current_chapter(self, position: RenderingPosition) -> Optional[ChapterInfo]:

183 """Determine which chapter contains the current position"""

184 if not self.chapters:

185 return None

186

187 # Find the chapter that contains this position

188 for i, chapter in enumerate(self.chapters): 188 ↛ 197line 188 didn't jump to line 197 because the loop on line 188 didn't complete

189 # Check if this is the last chapter or if position is before next chapter

190 if i == len(self.chapters) - 1:

191 return chapter

193 next_chapter = self.chapters[i + 1]

194 if position.chapter_index < next_chapter.position.chapter_index:

195 return chapter

197 return self.chapters[0] if self.chapters else None

200class FontFamilyOverride:

201 """

202 Manages font family preferences for ereader rendering.

203 Allows dynamic font family switching without modifying source blocks.

204 """

205

206 def __init__(self, preferred_family: Optional[BundledFont] = None):

207 """

208 Initialize font family override.

209

210 Args:

211 preferred_family: Preferred bundled font family (None = use original fonts)

212 """

213 self.preferred_family = preferred_family

215 def override_font(self, font: Font) -> Font:

216 """

217 Create a new font with the preferred family while preserving other attributes.

219 Args:

220 font: Original font object

221

222 Returns:

223 Font with overridden family, or original if no override is set

224 """

225 if self.preferred_family is None:

226 return font

228 # Get the appropriate font path for the preferred family

229 # preserving the original font's weight and style

230 new_font_path = get_bundled_font_path(

231 family=self.preferred_family,

232 weight=font.weight,

233 style=font.style

234 )

236 # If we couldn't find a matching font, fall back to original

237 if new_font_path is None:

238 return font

240 # Create a new font with the overridden path

241 return Font(

242 font_path=new_font_path,

243 font_size=font.font_size,

244 colour=font.colour,

245 weight=font.weight,

246 style=font.style,

247 decoration=font.decoration,

248 background=font.background,

249 language=font.language,

250 min_hyphenation_width=font.min_hyphenation_width

251 )

253

254class FontScaler:

255 """

256 Handles font scaling operations for ereader font size adjustments.

257 Applies scaling at layout/render time while preserving original font objects.

258 """

259

260 @staticmethod

261 def scale_font(font: Font, scale_factor: float, family_override: Optional[FontFamilyOverride] = None) -> Font:

262 """

263 Create a scaled version of a font for layout calculations.

265 Args:

266 font: Original font object

267 scale_factor: Scaling factor (1.0 = no change, 2.0 = double size, etc.)

268 family_override: Optional font family override

270 Returns:

271 New Font object with scaled size and optional family override

272 """

273 # Apply family override first if specified

274 working_font = font

275 if family_override is not None: 275 ↛ 276line 275 didn't jump to line 276 because the condition on line 275 was never true

276 working_font = family_override.override_font(font)

278 # Then apply scaling

279 if scale_factor == 1.0:

280 return working_font

282 scaled_size = max(1, int(working_font.font_size * scale_factor))

284 return Font(

285 font_path=working_font._font_path,

286 font_size=scaled_size,

287 colour=working_font.colour,

288 weight=working_font.weight,

289 style=working_font.style,

290 decoration=working_font.decoration,

291 background=working_font.background,

292 language=working_font.language,

293 min_hyphenation_width=working_font.min_hyphenation_width

294 )

295

296 @staticmethod

297 def scale_word_spacing(spacing: Tuple[int, int],

298 scale_factor: float) -> Tuple[int, int]:

299 """Scale word spacing constraints proportionally"""

300 if scale_factor == 1.0:

301 return spacing

302

303 min_spacing, max_spacing = spacing

304 return (

305 max(1, int(min_spacing * scale_factor)),

306 max(2, int(max_spacing * scale_factor))

307 )

310class BidirectionalLayouter:

311 """

312 Core layout engine supporting both forward and backward page rendering.

313 Handles font scaling and maintains position state.

314 """

316 def __init__(self,

317 blocks: List[Block],

318 page_style: PageStyle,

319 page_size: Tuple[int,

320 int] = (800,

321 600),

322 alignment_override=None,

323 font_family_override: Optional[FontFamilyOverride] = None):

324 self.blocks = blocks

325 self.page_style = page_style

326 self.page_size = page_size

327 self.chapter_navigator = ChapterNavigator(blocks)

328 self.alignment_override = alignment_override

329 self.font_family_override = font_family_override

331 # Maps (font_scale, end position) -> the position the page started at.

332 # Filled in as pages are laid out forward, which makes "previous page"

333 # exact and free for anywhere the reader has already been. Keyed by font

334 # scale because changing it repaginates the document.

335 self._page_chain: Dict[Tuple[float, Tuple[int, int, int]],

336 RenderingPosition] = {}

338 # Scaled copies of blocks, keyed by (id(block), font_scale). Rebuilding

339 # a block's words on every page render allocated a fresh Paragraph and

340 # Word per word on the hot path. The original block is kept alongside

341 # the copy so its id cannot be recycled while it is a live key.

342 self._scaled_block_cache: Dict[Tuple[int, float], Tuple[Block, Block]] = {}

344 def render_page_forward(self, position: RenderingPosition,

345 font_scale: float = 1.0) -> Tuple[Page, RenderingPosition]:

346 """

347 Render a page starting from the given position, moving forward through the document.

349 Args:

350 position: Starting position in document

351 font_scale: Font scaling factor

353 Returns:

354 Tuple of (rendered_page, next_position)

355 """

356 page = Page(size=self.page_size, style=self.page_style)

357 current_pos = position.copy()

359 # Start laying out blocks from the current position

360 while current_pos.block_index < len(self.blocks) and page.free_space()[1] > 0:

361 # Additional bounds check to prevent IndexError

362 if current_pos.block_index >= len(self.blocks): 362 ↛ 363line 362 didn't jump to line 363 because the condition on line 362 was never true

363 break

364

365 block = self.blocks[current_pos.block_index]

367 # Apply font scaling to the block

368 scaled_block = self._scale_block_fonts(block, font_scale)

369

370 # Try to fit the block on the current page

371 success, new_pos = self._layout_block_on_page(

372 scaled_block, page, current_pos, font_scale)

373

374 if not success:

375 # The block did not fit in its entirety. It may still have been

376 # laid out partially - a paragraph larger than one page places as

377 # many lines as fit and reports the word it stopped at. Keeping

378 # that resume point is what allows the next page to continue;

379 # discarding it tells the caller no progress was made, which

380 # dead-ends navigation on the block forever.

381 if self._position_compare(new_pos, current_pos) > 0:

382 current_pos = new_pos

383 break

384

385 # Add inter-block spacing after successfully laying out a block

386 # Only add if we're not at the end of the document and there's space

387 if new_pos.block_index < len(self.blocks):

388 page._current_y_offset += self.page_style.inter_block_spacing

389

390 # Ensure new position doesn't go beyond bounds

391 if new_pos.block_index >= len(self.blocks):

392 # We've reached the end of the document

393 current_pos = new_pos

394 break

396 current_pos = new_pos

398 # Remember this link in the chain so stepping back to it later is exact.

399 if self._position_compare(current_pos, position) > 0:

400 self._page_chain[(font_scale, self._position_key(current_pos))] = \

401 position.copy()

402

403 return page, current_pos

405 # How many block starts before the target to try as replay anchors before

406 # settling for the best inexact answer.

407 MAX_BACKWARD_ANCHORS = 4

409 # Ceiling on pages replayed from a single anchor, so a pathologically long

410 # block cannot make one page turn walk an entire chapter.

411 MAX_REPLAY_PAGES = 8

412

413 def render_page_backward(self,

414 end_position: RenderingPosition,

415 font_scale: float = 1.0) -> Tuple[Page,

416 RenderingPosition]:

417 """

418 Render the page that ends at the given position - "previous page".

419

420 Pagination is a pure function: laying out from a position q yields a page

421 and the position where it stopped, next(q). The page before P is therefore

422 the q for which next(q) == P, and it is found by *replaying* the chain

423 forward from an anchor, not by guessing q.

425 The previous implementation searched instead: it estimated a block index

426 and bisected on it, pinning word_index to 0. Pages routinely start

427 mid-block, so the answer was frequently not in the search space at all -

428 the search then exhausted its iterations and fell back to a position that

429 was not the previous page, usually the start of the document.

431 Three sources are tried in order:

432

433 1. The recorded chain, from pages already laid out going forward. Exact,

434 and the common case when the reader is paging back and forth.

435 2. Replay from the start of the block containing P, then from

436 progressively earlier blocks. Exact when P lies on the resulting chain.

437 3. Failing an exact hit - which happens when P was reached by a jump or a

438 restored bookmark rather than by reading forward, so it is on no

439 natural chain - the latest page start before P. That overlaps P's page

440 slightly rather than skipping content, which is the safe direction to

441 be wrong in.

442

443 Args:

444 end_position: Position where the page should end

445 font_scale: Font scaling factor

447 Returns:

448 Tuple of (rendered_page, start_position)

449 """

450 document_start = RenderingPosition()

452 # Nothing precedes the start of the document.

453 if self._position_compare(end_position, document_start) <= 0:

454 page, _ = self.render_page_forward(document_start, font_scale)

455 return page, document_start

457 # 1. The chain we have already walked.

458 remembered = self._page_chain.get((font_scale, self._position_key(end_position)))

459 if remembered is not None:

460 page, actual_end = self.render_page_forward(remembered, font_scale)

461 if self._position_compare(actual_end, end_position) == 0: 461 ↛ 465line 461 didn't jump to line 465 because the condition on line 461 was always true

462 return page, remembered

464 # 2/3. Replay from anchors, keeping the best inexact result as a fallback.

465 fallback = None

466 for anchor in self._backward_anchors(end_position):

467 page, start, exact = self._replay_to(anchor, end_position, font_scale)

468 if page is None:

469 continue

470 if exact: 470 ↛ 472line 470 didn't jump to line 472 because the condition on line 470 was always true

471 return page, start

472 if fallback is None:

473 fallback = (page, start)

475 if fallback is not None: 475 ↛ 476line 475 didn't jump to line 476 because the condition on line 475 was never true

476 return fallback

477

478 page, _ = self.render_page_forward(document_start, font_scale)

479 return page, document_start

481 def _backward_anchors(self, target: RenderingPosition):

482 """

483 Yield positions to replay from, nearest first.

484

485 Block starts are used as anchors because they are the coarsest positions

486 that are certainly valid to lay out from. The block containing the target

487 comes first: when the target is mid-block, the page before it usually

488 starts in that same block or the one before.

489 """

490 first_block = target.block_index if target.word_index > 0 \

491 else target.block_index - 1

493 for offset in range(self.MAX_BACKWARD_ANCHORS):

494 block_index = first_block - offset

495 if block_index < 0:

496 break

497 yield RenderingPosition(

498 chapter_index=target.chapter_index,

499 block_index=block_index,

500 word_index=0,

501 )

502

503 if first_block - self.MAX_BACKWARD_ANCHORS >= 0:

504 yield RenderingPosition()

506 def _replay_to(self,

507 anchor: RenderingPosition,

508 target: RenderingPosition,

509 font_scale: float):

510 """

511 Lay out pages forward from `anchor`, looking for the one ending at `target`.

512

513 Returns:

514 (page, start, exact). `exact` is True when a page ended precisely on

515 the target. When the chain steps over the target instead, the last

516 page starting before it is returned with exact=False. (None, None,

517 False) means the anchor yielded nothing usable.

518 """

519 position = anchor

520 last = (None, None)

521

522 for _ in range(self.MAX_REPLAY_PAGES): 522 ↛ 542line 522 didn't jump to line 542 because the loop on line 522 didn't complete

523 if self._position_compare(position, target) >= 0: 523 ↛ 524line 523 didn't jump to line 524 because the condition on line 523 was never true

524 break

526 page, next_position = self.render_page_forward(position, font_scale)

527 comparison = self._position_compare(next_position, target)

529 if comparison == 0:

530 return page, position, True

532 if comparison > 0:

533 # Stepped over the target: this chain does not pass through it.

534 return last[0], last[1], False

535

536 if self._position_compare(next_position, position) <= 0: 536 ↛ 537line 536 didn't jump to line 537 because the condition on line 536 was never true

537 break # no progress; give up on this anchor

538

539 last = (page, position)

540 position = next_position

541

542 return last[0], last[1], False

543

544 @staticmethod

545 def _position_key(position: RenderingPosition) -> Tuple[int, int, int]:

546 """Hashable identity of a position, for the page chain map."""

547 return (position.chapter_index, position.block_index, position.word_index)

548

549 def _scale_block_fonts(self, block: Block, font_scale: float) -> Block:

550 """

551 Apply font scaling and the font family override to every font in a block.

552

553 Returns the block unchanged when there is nothing to apply. Results are

554 memoised per (block, scale) for the life of the layouter, so a page

555 re-render at an unchanged scale costs a dict lookup.

556 """

557 if font_scale == 1.0 and self.font_family_override is None:

558 return block

559

560 key = (id(block), font_scale)

561 cached = self._scaled_block_cache.get(key)

562 if cached is not None:

563 return cached[1]

565 scaled = self._build_scaled_block(block, font_scale)

566 self._scaled_block_cache[key] = (block, scaled)

567 return scaled

568

569 def _build_scaled_block(self, block: Block, font_scale: float) -> Block:

570 """Construct the scaled copy of a block. See _scale_block_fonts."""

571 def scale(font: Font) -> Font:

572 return FontScaler.scale_font(font, font_scale, self.font_family_override)

574 if isinstance(block, (Paragraph, Heading)):

575 if isinstance(block, Heading):

576 scaled_block = Heading(block.level, scale(block.style))

577 else:

578 scaled_block = Paragraph(scale(block.style))

579

580 # words_iter() yields (position, word) tuples. with_style() keeps

581 # the concrete word class, so a LinkedWord stays linked - rebuilding

582 # these as plain Words silently stripped every hyperlink in the

583 # document as soon as the reader changed font size.

584 for _, word in block.words_iter():

585 if isinstance(word, Word): 585 ↛ 584line 585 didn't jump to line 584 because the condition on line 585 was always true

586 scaled_block.add_word(word.with_style(scale(word.style)))

587 return scaled_block

588

589 if isinstance(block, Quote):

590 scaled_quote = Quote(scale(block.style) if block.style else None)

591 for child in block.blocks():

592 scaled_quote.add_block(self._scale_block_fonts(child, font_scale))

593 return scaled_quote

594

595 if isinstance(block, HList):

596 scaled_list = HList(

597 block.style,

598 scale(block.default_style) if block.default_style else None)

599 for item in block.items():

600 scaled_item = ListItem(

601 item.term,

602 scale(item.style) if item.style else None)

603 for child in item.blocks():

604 scaled_item.add_block(self._scale_block_fonts(child, font_scale))

605 scaled_list.add_item(scaled_item)

606 return scaled_list

607

608 if isinstance(block, Table): 608 ↛ 633line 608 didn't jump to line 633 because the condition on line 608 was always true

609 scaled_table = Table(

610 block.caption,

611 scale(block.style) if block.style else None)

612 # Rows must go back into the section they came from, or a <thead>

613 # row would be re-added as a body row.

614 for section, rows in (('header', block.header_rows()),

615 ('body', block.body_rows()),

616 ('footer', block.footer_rows())):

617 for row in rows:

618 scaled_row = TableRow(scale(row.style) if row.style else None)

619 for cell in row.cells():

620 scaled_cell = TableCell(

621 is_header=cell.is_header,

622 colspan=cell.colspan,

623 rowspan=cell.rowspan,

624 style=scale(cell.style) if cell.style else None)

625 for child in cell.blocks():

626 scaled_cell.add_block(self._scale_block_fonts(child, font_scale))

627 scaled_row.add_cell(scaled_cell)

628 scaled_table.add_row(scaled_row, section)

629 return scaled_table

630

631 # Blocks with no fonts of their own (Image, HorizontalRule, PageBreak,

632 # CodeBlock - which carries raw lines, not styled words) pass through.

633 return block

635 def _layout_block_on_page(self,

636 block: Block,

637 page: Page,

638 position: RenderingPosition,

639 font_scale: float) -> Tuple[bool,

640 RenderingPosition]:

641 """

642 Try to layout a block on the page starting from the given position.

643

644 Returns:

645 Tuple of (success, new_position)

646 """

647 if isinstance(block, Paragraph):

648 return self._layout_paragraph_on_page(block, page, position, font_scale)

649 elif isinstance(block, Heading): 649 ↛ 650line 649 didn't jump to line 650 because the condition on line 649 was never true

650 return self._layout_heading_on_page(block, page, position, font_scale)

651 elif isinstance(block, Table): 651 ↛ 652line 651 didn't jump to line 652 because the condition on line 651 was never true

652 return self._layout_table_on_page(block, page, position, font_scale)

653 elif isinstance(block, HList): 653 ↛ 654line 653 didn't jump to line 654 because the condition on line 653 was never true

654 return self._layout_list_on_page(block, page, position, font_scale)

655 elif isinstance(block, Image):

656 return self._layout_image_on_page(block, page, position, font_scale)

657 else:

658 # Skip unknown block types

659 new_pos = position.copy()

660 new_pos.block_index += 1

661 return True, new_pos

662

663 def _layout_paragraph_on_page(self,

664 paragraph: Paragraph,

665 page: Page,

666 position: RenderingPosition,

667 font_scale: float) -> Tuple[bool,

668 RenderingPosition]:

669 """

670 Layout a paragraph on the page using the core paragraph_layouter.

671 Integrates font scaling and position tracking with the proven layout logic.

672

673 Args:

674 paragraph: The paragraph to layout (already scaled if font_scale != 1.0)

675 page: The page to layout on

676 position: Current rendering position

677 font_scale: Font scaling factor (used for context, paragraph should already be scaled)

679 Returns:

680 Tuple of (success, new_position)

681 """

682 # Convert remaining_pretext from string to Text object if needed

683 pretext_obj = None

684 if position.remaining_pretext:

685 # Create a Text object from the pretext string

686 pretext_obj = Text(

687 position.remaining_pretext,

688 paragraph.style,

689 page.draw,

690 line=None,

691 source=None

692 )

693

694 # Call the core paragraph layouter with alignment override if set

695 success, failed_word_index, remaining_pretext = paragraph_layouter(

696 paragraph,

697 page,

698 start_word=position.word_index,

699 pretext=pretext_obj,

700 alignment_override=self.alignment_override

701 )

703 # Create new position based on the result

704 new_pos = position.copy()

706 if success:

707 # Paragraph was fully laid out, move to next block

708 new_pos.block_index += 1

709 new_pos.word_index = 0

710 new_pos.remaining_pretext = None

711 return True, new_pos

712 else:

713 # Paragraph was not fully laid out

714 if failed_word_index is not None: 714 ↛ 728line 714 didn't jump to line 728 because the condition on line 714 was always true

715 # Update position to the word that didn't fit

716 new_pos.word_index = failed_word_index

717

718 # Convert Text object back to string if there's remaining pretext

719 if remaining_pretext is not None and hasattr(remaining_pretext, 'text'):

720 new_pos.remaining_pretext = remaining_pretext.text

721 else:

722 new_pos.remaining_pretext = None

723

724 return False, new_pos

725 else:

726 # No specific word failed, but layout wasn't successful

727 # This shouldn't normally happen, but handle it gracefully

728 return False, position

729

730 def _layout_heading_on_page(self,

731 heading: Heading,

732 page: Page,

733 position: RenderingPosition,

734 font_scale: float) -> Tuple[bool,

735 RenderingPosition]:

736 """Layout a heading on the page"""

737 # Similar to paragraph but with heading-specific styling

738 return self._layout_paragraph_on_page(heading, page, position, font_scale)

739

740 def _layout_table_on_page(self,

741 table: Table,

742 page: Page,

743 position: RenderingPosition,

744 font_scale: float) -> Tuple[bool,

745 RenderingPosition]:

746 """Layout a table on the page with column fitting and row continuation"""

747 # This is a complex operation that would need full table layout logic

748 # For now, skip tables

749 new_pos = position.copy()

750 new_pos.block_index += 1

751 new_pos.table_row = 0

752 new_pos.table_col = 0

753 return True, new_pos

754

755 def _layout_list_on_page(self,

756 hlist: HList,

757 page: Page,

758 position: RenderingPosition,

759 font_scale: float) -> Tuple[bool,

760 RenderingPosition]:

761 """Layout a list on the page"""

762 # This would need list-specific layout logic

763 # For now, skip lists

764 new_pos = position.copy()

765 new_pos.block_index += 1

766 new_pos.list_item_index = 0

767 return True, new_pos

768

769 def _layout_image_on_page(self,

770 image: Image,

771 page: Page,

772 position: RenderingPosition,

773 font_scale: float) -> Tuple[bool,

774 RenderingPosition]:

775 """

776 Layout an image on the page using the image_layouter.

777

778 Args:

779 image: The Image block to layout

780 page: The page to layout on

781 position: Current rendering position (should be at the start of this image block)

782 font_scale: Font scaling factor (not used for images, but kept for consistency)

783

784 Returns:

785 Tuple of (success, new_position)

786 - success: True if image was laid out, False if page ran out of space

787 - new_position: Updated position (next block if success, same block if failed)

788 """

789 # Try to layout the image on the current page

790 success = image_layouter(

791 image=image,

792 page=page,

793 max_width=None, # Use page available width

794 max_height=None # Use page available height

795 )

796

797 new_pos = position.copy()

798

799 if success:

800 # Image was successfully laid out, move to next block

801 new_pos.block_index += 1

802 new_pos.word_index = 0

803 return True, new_pos

804 else:

805 # Image didn't fit on current page, signal to continue on next page

806 # Keep same position so it will be attempted on the next page

807 return False, position

808

809 def _position_compare(self, pos1: RenderingPosition,

810 pos2: RenderingPosition) -> int:

811 """Compare two positions (-1: pos1 < pos2, 0: equal, 1: pos1 > pos2)"""

812 if pos1.chapter_index != pos2.chapter_index:

813 return 1 if pos1.chapter_index > pos2.chapter_index else -1

814 if pos1.block_index != pos2.block_index:

815 return 1 if pos1.block_index > pos2.block_index else -1

816 if pos1.word_index != pos2.word_index:

817 return 1 if pos1.word_index > pos2.word_index else -1

818 return 0

+ + + diff --git a/cov_info/htmlcov/z_427cc3035faf7633_ereader_manager_py.html b/cov_info/htmlcov/z_427cc3035faf7633_ereader_manager_py.html new file mode 100644 index 0000000..6a6ee7d --- /dev/null +++ b/cov_info/htmlcov/z_427cc3035faf7633_ereader_manager_py.html @@ -0,0 +1,1248 @@ + + + + + Coverage for pyWebLayout/layout/ereader_manager.py: 77% + + + + + +

+ Coverage for pyWebLayout/layout/ereader_manager.py: + 77% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 370 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2High-performance ereader layout manager with sub-second page rendering.

4This module provides the main interface for ereader applications, combining

5position tracking, font scaling, chapter navigation, and intelligent page buffering

6into a unified, easy-to-use API.

7"""

9from __future__ import annotations

10from typing import List, Dict, Optional, Tuple, Any, Callable

11import logging

13from .ereader_layout import RenderingPosition, ChapterNavigator, ChapterInfo

14from .page_buffer import BufferedPageRenderer

15from pyWebLayout.abstract.block import Block, HeadingLevel, Image, BlockType

16from pyWebLayout.concrete.page import Page

17from pyWebLayout.concrete.image import RenderableImage

18from pyWebLayout.style.page_style import PageStyle

19from pyWebLayout.style.fonts import BundledFont

20from pyWebLayout.layout.document_layouter import image_layouter

21from pyWebLayout.core.highlight import Highlight, HighlightColor, HighlightManager, \

22 create_highlight_from_query_result

23from pyWebLayout.core.persistence import ensure_dir, read_json, write_json

24from pyWebLayout.concrete.interaction_handler import InteractionStateManager

25from PIL import Image as Image_

27logger = logging.getLogger(__name__)

30class BookmarkManager:

31 """

32 Manages bookmarks and reading position persistence for ereader applications.

33 """

35 def __init__(self, document_id: str, bookmarks_dir: str = "bookmarks"):

36 """

37 Initialize bookmark manager.

39 Args:

40 document_id: Unique identifier for the document

41 bookmarks_dir: Directory to store bookmark files

42 """

43 self.document_id = document_id

44 self.bookmarks_dir = ensure_dir(bookmarks_dir)

46 self.bookmarks_file = self.bookmarks_dir / f"{document_id}_bookmarks.json"

47 self.position_file = self.bookmarks_dir / f"{document_id}_position.json"

49 self._bookmarks: Dict[str, RenderingPosition] = {}

50 self._load_bookmarks()

52 def _load_bookmarks(self):

53 """Load bookmarks from file"""

54 data = read_json(self.bookmarks_file, {})

55 try:

56 self._bookmarks = {

57 name: RenderingPosition.from_dict(pos_data)

58 for name, pos_data in data.items()

59 }

60 except (AttributeError, TypeError, KeyError):

61 logger.warning("Bookmark file %s is not in the expected shape; ignoring it",

62 self.bookmarks_file, exc_info=True)

63 self._bookmarks = {}

65 def _save_bookmarks(self):

66 """Save bookmarks to file"""

67 write_json(self.bookmarks_file, {

68 name: position.to_dict()

69 for name, position in self._bookmarks.items()

70 })

72 def add_bookmark(self, name: str, position: RenderingPosition):

73 """

74 Add a bookmark at the given position.

76 Args:

77 name: Bookmark name

78 position: Position to bookmark

79 """

80 self._bookmarks[name] = position

81 self._save_bookmarks()

83 def remove_bookmark(self, name: str) -> bool:

84 """

85 Remove a bookmark.

87 Args:

88 name: Bookmark name to remove

90 Returns:

91 True if bookmark was removed, False if not found

92 """

93 if name in self._bookmarks:

94 del self._bookmarks[name]

95 self._save_bookmarks()

96 return True

97 return False

99 def get_bookmark(self, name: str) -> Optional[RenderingPosition]:

100 """

101 Get a bookmark position.

102

103 Args:

104 name: Bookmark name

106 Returns:

107 Bookmark position or None if not found

108 """

109 return self._bookmarks.get(name)

111 def list_bookmarks(self) -> List[Tuple[str, RenderingPosition]]:

112 """

113 Get all bookmarks.

115 Returns:

116 List of (name, position) tuples

117 """

118 return list(self._bookmarks.items())

119

120 def save_reading_position(self, position: RenderingPosition):

121 """

122 Save the current reading position.

123

124 Args:

125 position: Current reading position

126 """

127 write_json(self.position_file, position.to_dict())

129 def load_reading_position(self) -> Optional[RenderingPosition]:

130 """

131 Load the last reading position.

133 Returns:

134 Last reading position or None if not found

135 """

136 data = read_json(self.position_file, None)

137 if data is None:

138 return None

139 try:

140 return RenderingPosition.from_dict(data)

141 except (TypeError, KeyError):

142 logger.warning("Position file %s is not in the expected shape; ignoring it",

143 self.position_file, exc_info=True)

144 return None

147class EreaderLayoutManager:

148 """

149 High-level ereader layout manager providing a complete interface for ereader applications.

151 Features:

152 - Sub-second page rendering with intelligent buffering

153 - Font scaling support

154 - Dynamic font family switching (Sans, Serif, Monospace)

155 - Chapter navigation

156 - Bookmark management

157 - Position persistence

158 - Progress tracking

159 """

161 def __init__(self,

162 blocks: List[Block],

163 page_size: Tuple[int, int],

164 document_id: str = "default",

165 buffer_size: int = 5,

166 page_style: Optional[PageStyle] = None,

167 bookmarks_dir: str = "bookmarks",

168 highlights_dir: Optional[str] = None):

169 """

170 Initialize the ereader layout manager.

172 Args:

173 blocks: Document blocks to render

174 page_size: Page size (width, height) in pixels

175 document_id: Unique identifier for the document (for bookmarks/position)

176 buffer_size: Number of pages to cache in each direction

177 page_style: Custom page styling (uses default if None)

178 bookmarks_dir: Directory to store bookmark files

179 highlights_dir: Directory to store highlights. Defaults to

180 bookmarks_dir, so a document's reading state lives in one place.

181 """

182 self.blocks = blocks

183 self.page_size = page_size

184 self.document_id = document_id

186 # Initialize page style

187 if page_style is None:

188 page_style = PageStyle()

189 self.page_style = page_style

191 # Initialize core components

192 self.renderer = BufferedPageRenderer(blocks, page_style, buffer_size, page_size)

193 self.chapter_navigator = ChapterNavigator(blocks)

194 self.bookmark_manager = BookmarkManager(document_id, bookmarks_dir)

195 self.highlight_manager = HighlightManager(

196 document_id, highlights_dir if highlights_dir is not None else bookmarks_dir)

198 # Current state

199 self.current_position = RenderingPosition()

200 self.font_scale = 1.0

202 # Cover page handling

203 self._has_cover = self._detect_cover()

204 self._on_cover_page = self._has_cover # Start on cover if one exists

205

206 # Page position history for fast backward navigation

207 # List of (position, font_scale) tuples representing the start of each page visited

208 self._page_history: List[Tuple[RenderingPosition, float]] = []

209 self._max_history_size = 50 # Keep last 50 page positions

210

211 # Load last reading position if available

212 saved_position = self.bookmark_manager.load_reading_position()

213 if saved_position:

214 self.current_position = saved_position

215 self._on_cover_page = False # If we have a saved position, we're past the cover

216

217 # Pointer interaction state, rebound whenever the displayed page changes

218 self._interaction_state_manager: Optional[InteractionStateManager] = None

219 self._interaction_page: Optional[Page] = None

221 # Callbacks for UI updates

222 self.position_changed_callback: Optional[Callable[[

223 RenderingPosition], None]] = None

224 self.chapter_changed_callback: Optional[Callable[[

225 Optional[ChapterInfo]], None]] = None

227 def prewarm_caches(self, max_words: int = 2000,

228 budget_bytes: Optional[int] = None) -> Tuple[int, int]:

229 """

230 Preload the text caches with this document's most frequent words.

232 Counts how often each word occurs in the book and rasterises the most

233 common ones ahead of time, so that the work lands at open time rather than

234 on the first page turns. Entries are seeded with their document frequency,

235 which is what keeps them resident under usage-ranked eviction.

237 Safe to call again after a font change; the fonts differ, so the new

238 entries simply take their place in the eviction order alongside the old.

240 Args:

241 max_words: Maximum distinct words to preload.

242 budget_bytes: Bytes of glyph cache to fill. Defaults to half the budget.

244 Returns:

245 Tuple of (words preloaded, bytes preloaded).

246 """

247 from collections import Counter

248 from pyWebLayout.concrete.text import prewarm_text_caches

249 from .ereader_layout import FontScaler

251 override = getattr(self.renderer.layouter, 'font_family_override', None)

253 # Count by (style, text): the same word in a heading and in body text is a

254 # different rasterisation, and both are worth counting separately.

255 counts: Dict[Tuple[int, str], int] = Counter()

256 styles: Dict[int, Any] = {}

257 for block in self.blocks:

258 words = getattr(block, '_words', None)

259 if not words:

260 continue

261 for word in words:

262 style = word.style

263 if style is None:

264 continue

265 key = id(style)

266 styles.setdefault(key, style)

267 counts[(key, word.text)] += 1

269 # Resolve each distinct style once through the same scaling the layouter

270 # applies, so the preloaded keys match what rendering will look up.

271 scaled: Dict[int, Any] = {}

272 for key, style in styles.items():

273 try:

274 scaled[key] = FontScaler.scale_font(style, self.font_scale, override)

275 except Exception:

276 continue

278 entries = []

279 for (style_key, text), count in counts.items():

280 font = scaled.get(style_key)

281 if font is None:

282 continue

283 entries.append((font.font, text, font.colour, count))

285 return prewarm_text_caches(entries, budget_bytes=budget_bytes,

286 max_words=max_words)

288 def set_position_changed_callback(

289 self, callback: Callable[[RenderingPosition], None]):

290 """Set callback for position changes"""

291 self.position_changed_callback = callback

293 def set_chapter_changed_callback(

294 self, callback: Callable[[Optional[ChapterInfo]], None]):

295 """Set callback for chapter changes"""

296 self.chapter_changed_callback = callback

298 def _detect_cover(self) -> bool:

299 """

300 Detect if the document has a cover page.

302 A cover is detected if:

303 1. The first block is an Image block, OR

304 2. The document has cover metadata (future enhancement)

306 Returns:

307 True if a cover page should be rendered

308 """

309 if not self.blocks:

310 return False

312 # Check if first block is an image - treat it as a cover

313 first_block = self.blocks[0]

314 if isinstance(first_block, Image):

315 return True

317 return False

319 def _render_cover_page(self) -> Page:

320 """

321 Render a dedicated cover page.

322

323 The cover page displays the first image block (if it exists)

324 using the standard image layouter with maximum dimensions to fill the page.

325

326 Returns:

327 Rendered cover page

328 """

329 # Create a new page for the cover

330 page = Page(self.page_size, self.page_style)

332 if not self.blocks or not isinstance(self.blocks[0], Image): 332 ↛ 334line 332 didn't jump to line 334 because the condition on line 332 was never true

333 # No cover image, return blank page

334 return page

336 cover_image_block = self.blocks[0]

338 # Use the image layouter to render the cover image

339 # Use full page dimensions (minus borders/padding) for cover

340 try:

341 max_width = self.page_size[0] - 2 * self.page_style.border_width

342 max_height = self.page_size[1] - 2 * self.page_style.border_width

344 # Layout the image on the page

345 success = image_layouter(

346 image=cover_image_block,

347 page=page,

348 max_width=max_width,

349 max_height=max_height

350 )

351

352 if not success: 352 ↛ 359line 352 didn't jump to line 359 because the condition on line 352 was always true

353 print("Warning: Failed to layout cover image")

355 except Exception as e:

356 # If image loading fails, just return the blank page

357 print(f"Warning: Failed to load cover image: {e}")

359 return page

360

361 def _notify_position_changed(self):

362 """Notify UI of position change"""

363 if self.position_changed_callback:

364 self.position_changed_callback(self.current_position)

365

366 # Check if chapter changed

367 current_chapter = self.chapter_navigator.get_current_chapter(

368 self.current_position)

369 if self.chapter_changed_callback:

370 self.chapter_changed_callback(current_chapter)

371

372 # Auto-save reading position

373 self.bookmark_manager.save_reading_position(self.current_position)

375 def get_current_page(self) -> Page:

376 """

377 Get the page at the current reading position.

379 If on the cover page, returns the rendered cover.

380 Otherwise, returns the regular content page.

381

382 Returns:

383 Rendered page

384 """

385 # Check if we're on the cover page

386 if self._on_cover_page and self._has_cover:

387 return self._render_cover_page()

388

389 page, _ = self.renderer.render_page(self.current_position, self.font_scale)

390 return page

392 def next_page(self) -> Optional[Page]:

393 """

394 Advance to the next page.

396 If currently on the cover page, advances to the first content page.

397 Otherwise, advances to the next content page.

399 Returns:

400 Next page or None if at end of document

401 """

402 # Special case: transitioning from cover to first content page

403 if self._on_cover_page and self._has_cover:

404 self._on_cover_page = False

405 # If first block is an image (the cover), skip it and start from block 1

406 if self.blocks and isinstance(self.blocks[0], Image): 406 ↛ 409line 406 didn't jump to line 409 because the condition on line 406 was always true

407 self.current_position = RenderingPosition(chapter_index=0, block_index=1)

408 else:

409 self.current_position = RenderingPosition()

410 self._notify_position_changed()

411 return self.get_current_page()

412

413 # Save current position to history before moving forward

414 self._add_to_history(self.current_position, self.font_scale)

416 page, next_position = self.renderer.render_page(

417 self.current_position, self.font_scale)

418

419 # Check if we made progress

420 if next_position != self.current_position:

421 self.current_position = next_position

422 self._notify_position_changed()

423 return self.get_current_page()

425 # No progress. That is the correct answer only at the end of the

426 # document; anywhere else a block has failed to lay out and would trap

427 # the reader on this page. Skipping the block costs one block, not the

428 # rest of the book.

429 if self.current_position.block_index < len(self.blocks):

430 logger.error(

431 "Block %d made no layout progress; skipping it. This is a layout "

432 "bug - the block placed nothing and reported no resume point.",

433 self.current_position.block_index)

434 self.current_position = RenderingPosition(

435 chapter_index=self.current_position.chapter_index,

436 block_index=self.current_position.block_index + 1)

437 self._notify_position_changed()

438 return self.get_current_page()

439

440 return None # At end of document

442 def previous_page(self) -> Optional[Page]:

443 """

444 Go to the previous page.

445

446 Uses cached page history for instant navigation when available,

447 falls back to iterative refinement algorithm when needed.

448 Can navigate back to the cover page if it exists.

449

450 Returns:

451 Previous page or None if at beginning of document (or on cover)

452 """

453 # Special case: if at the beginning of content and there's a cover, go back to it

454 if self._has_cover and self._is_at_beginning() and not self._on_cover_page:

455 self._on_cover_page = True

456 # Restore the canonical cover position. Being on the cover must have a

457 # single representation: a fresh load sits at block 0 with the cover

458 # showing, so returning to the cover has to land there too. Leaving the

459 # position at the first content block saves a position that reopens past

460 # the cover, silently losing it.

461 self.current_position = RenderingPosition()

462 self._notify_position_changed()

463 return self.get_current_page()

464

465 # Can't go before the cover

466 if self._on_cover_page: 466 ↛ 467line 466 didn't jump to line 467 because the condition on line 466 was never true

467 return None

468

469 if self._is_at_beginning():

470 return None

471

472 # Fast path: Check if we have this position in history

473 previous_position = self._get_from_history(self.current_position, self.font_scale)

475 if previous_position is not None:

476 # Cache hit! Use the cached position for instant navigation

477 self.current_position = previous_position

478 self._notify_position_changed()

479 return self.get_current_page()

481 # Slow path: Use backward rendering to find the previous page

482 # This uses the iterative refinement algorithm we just fixed

483 page, start_position = self.renderer.render_page_backward(

484 self.current_position, self.font_scale)

485

486 if start_position != self.current_position: 486 ↛ 494line 486 didn't jump to line 494 because the condition on line 486 was always true

487 # Save this calculated position to history for future use

488 self._add_to_history(start_position, self.font_scale)

489

490 self.current_position = start_position

491 self._notify_position_changed()

492 return page

493

494 return None # At beginning of document

495

496 def _is_at_beginning(self) -> bool:

497 """

498 Check if we're at the beginning of the document content.

499

500 If a cover exists (first block is an Image), the beginning of content

501 is at block_index=1. Otherwise, it's at block_index=0.

502 """

503 # Determine the first content block index

504 first_content_block = 1 if (self._has_cover and self.blocks and isinstance(self.blocks[0], Image)) else 0

506 return (self.current_position.chapter_index == 0 and

507 self.current_position.block_index == first_content_block and

508 self.current_position.word_index == 0)

509

510 def jump_to_position(self, position: RenderingPosition) -> Page:

511 """

512 Jump to a specific position in the document.

513

514 Args:

515 position: Position to jump to

517 Returns:

518 Page at the new position

519 """

520 self.current_position = position

521 self._on_cover_page = False # Jumping to a position means we're past the cover

522 self._notify_position_changed()

523 return self.get_current_page()

524

525 def jump_to_chapter(self, chapter_title: str) -> Optional[Page]:

526 """

527 Jump to a specific chapter by title.

529 Args:

530 chapter_title: Title of the chapter to jump to

532 Returns:

533 Page at chapter start or None if chapter not found

534 """

535 position = self.chapter_navigator.get_chapter_position(chapter_title)

536 if position:

537 return self.jump_to_position(position)

538 return None

539

540 def jump_to_chapter_index(self, chapter_index: int) -> Optional[Page]:

541 """

542 Jump to a chapter by index.

543

544 Args:

545 chapter_index: Index of the chapter (0-based)

546

547 Returns:

548 Page at chapter start or None if index invalid

549 """

550 chapters = self.chapter_navigator.chapters

551 if 0 <= chapter_index < len(chapters):

552 return self.jump_to_position(chapters[chapter_index].position)

553 return None

554

555 def _add_to_history(self, position: RenderingPosition, font_scale: float):

556 """

557 Add a page position to the navigation history.

558

559 Args:

560 position: The page start position to remember

561 font_scale: The font scale at this position

562 """

563 # Only add if it's different from the last entry

564 if not self._page_history or \

565 self._page_history[-1][0] != position or \

566 self._page_history[-1][1] != font_scale:

567

568 self._page_history.append((position.copy(), font_scale))

569

570 # Trim history if it exceeds max size

571 if len(self._page_history) > self._max_history_size: 571 ↛ 572line 571 didn't jump to line 572 because the condition on line 571 was never true

572 self._page_history.pop(0)

574 def _get_from_history(

575 self,

576 current_position: RenderingPosition,

577 current_font_scale: float) -> Optional[RenderingPosition]:

578 """

579 Get the previous page position from history.

580

581 Searches backward through history to find the last position that

582 comes before the current position at the same font scale.

583

584 Args:

585 current_position: Current page position

586 current_font_scale: Current font scale

587

588 Returns:

589 Previous page position or None if not found in history

590 """

591 # Search backward through history

592 for i in range(len(self._page_history) - 1, -1, -1):

593 hist_position, hist_font_scale = self._page_history[i]

594

595 # Must match font scale

596 if hist_font_scale != current_font_scale: 596 ↛ 597line 596 didn't jump to line 597 because the condition on line 596 was never true

597 continue

598

599 # Must be before current position

600 if (hist_position.chapter_index < current_position.chapter_index or

601 (hist_position.chapter_index == current_position.chapter_index and

602 hist_position.block_index < current_position.block_index) or

603 (hist_position.chapter_index == current_position.chapter_index and

604 hist_position.block_index == current_position.block_index and

605 hist_position.word_index < current_position.word_index)):

606

607 # Found a previous position - remove it and everything after from history

608 # since we're navigating backward

609 self._page_history = self._page_history[:i]

610 return hist_position.copy()

611

612 return None

613

614 def _clear_history(self):

615 """Clear the page navigation history."""

616 self._page_history.clear()

617

618 def set_font_scale(self, scale: float) -> Page:

619 """

620 Change the font scale and re-render current page.

621

622 Clears page history since font changes invalidate all cached positions.

623

624 Args:

625 scale: Font scaling factor (1.0 = normal, 2.0 = double size, etc.)

626

627 Returns:

628 Re-rendered page with new font scale

629 """

630 if scale != self.font_scale:

631 self.font_scale = scale

632 # Clear history since font scale changes invalidate all cached positions

633 self._clear_history()

634 # The renderer will handle cache invalidation

635

636 return self.get_current_page()

637

638 def get_font_scale(self) -> float:

639 """Get the current font scale"""

640 return self.font_scale

641

642 def set_font_family(self, family: Optional[BundledFont]) -> Page:

643 """

644 Change the font family and re-render current page.

645

646 Switches all text in the document to use the specified bundled font family

647 while preserving font weights, styles, sizes, and other attributes.

648 Clears page history and cache since font changes invalidate all cached positions.

649

650 Args:

651 family: Bundled font family to use (SANS, SERIF, MONOSPACE, or None for original fonts)

652

653 Returns:

654 Re-rendered page with new font family

655

656 Example:

657 >>> from pyWebLayout.style.fonts import BundledFont

658 >>> manager.set_font_family(BundledFont.SERIF) # Switch to serif

659 >>> manager.set_font_family(BundledFont.SANS) # Switch to sans

660 >>> manager.set_font_family(None) # Restore original fonts

661 """

662 # Update the renderer's font family

663 self.renderer.set_font_family(family)

664

665 # Clear history since font changes invalidate all cached positions

666 self._clear_history()

667

668 return self.get_current_page()

669

670 def get_font_family(self) -> Optional[BundledFont]:

671 """

672 Get the current font family override.

673

674 Returns:

675 Current font family (SANS, SERIF, MONOSPACE) or None if using original fonts

676 """

677 return self.renderer.get_font_family()

679 def increase_line_spacing(self, amount: int = 2) -> Page:

680 """

681 Increase line spacing and re-render current page.

682

683 Clears page history since spacing changes invalidate all cached positions.

684

685 Args:

686 amount: Pixels to add to line spacing (default: 2)

687

688 Returns:

689 Re-rendered page with increased line spacing

690 """

691 self.page_style.line_spacing += amount

692 self.renderer.page_style = self.page_style # Update renderer's reference

693 self.renderer.buffer.invalidate_all() # Clear cache to force re-render

694 self._clear_history() # Clear position history

695 return self.get_current_page()

696

697 def decrease_line_spacing(self, amount: int = 2) -> Page:

698 """

699 Decrease line spacing and re-render current page.

700

701 Clears page history since spacing changes invalidate all cached positions.

703 Args:

704 amount: Pixels to remove from line spacing (default: 2)

706 Returns:

707 Re-rendered page with decreased line spacing

708 """

709 self.page_style.line_spacing = max(0, self.page_style.line_spacing - amount)

710 self.renderer.page_style = self.page_style # Update renderer's reference

711 self.renderer.buffer.invalidate_all() # Clear cache to force re-render

712 self._clear_history() # Clear position history

713 return self.get_current_page()

714

715 def increase_inter_block_spacing(self, amount: int = 5) -> Page:

716 """

717 Increase spacing between blocks and re-render current page.

718

719 Clears page history since spacing changes invalidate all cached positions.

720

721 Args:

722 amount: Pixels to add to inter-block spacing (default: 5)

723

724 Returns:

725 Re-rendered page with increased block spacing

726 """

727 self.page_style.inter_block_spacing += amount

728 self.renderer.page_style = self.page_style # Update renderer's reference

729 self.renderer.buffer.invalidate_all() # Clear cache to force re-render

730 self._clear_history() # Clear position history

731 return self.get_current_page()

732

733 def decrease_inter_block_spacing(self, amount: int = 5) -> Page:

734 """

735 Decrease spacing between blocks and re-render current page.

736

737 Clears page history since spacing changes invalidate all cached positions.

738

739 Args:

740 amount: Pixels to remove from inter-block spacing (default: 5)

741

742 Returns:

743 Re-rendered page with decreased block spacing

744 """

745 self.page_style.inter_block_spacing = max(

746 0, self.page_style.inter_block_spacing - amount)

747 self.renderer.page_style = self.page_style # Update renderer's reference

748 self.renderer.buffer.invalidate_all() # Clear cache to force re-render

749 self._clear_history() # Clear position history

750 return self.get_current_page()

751

752 def increase_word_spacing(self, amount: int = 2) -> Page:

753 """

754 Increase spacing between words and re-render current page.

755

756 Clears page history since spacing changes invalidate all cached positions.

757

758 Args:

759 amount: Pixels to add to word spacing (default: 2)

760

761 Returns:

762 Re-rendered page with increased word spacing

763 """

764 self.page_style.word_spacing += amount

765 self.renderer.page_style = self.page_style # Update renderer's reference

766 self.renderer.buffer.invalidate_all() # Clear cache to force re-render

767 self._clear_history() # Clear position history

768 return self.get_current_page()

769

770 def decrease_word_spacing(self, amount: int = 2) -> Page:

771 """

772 Decrease spacing between words and re-render current page.

773

774 Clears page history since spacing changes invalidate all cached positions.

775

776 Args:

777 amount: Pixels to remove from word spacing (default: 2)

778

779 Returns:

780 Re-rendered page with decreased word spacing

781 """

782 self.page_style.word_spacing = max(0, self.page_style.word_spacing - amount)

783 self.renderer.page_style = self.page_style # Update renderer's reference

784 self.renderer.buffer.invalidate_all() # Clear cache to force re-render

785 self._clear_history() # Clear position history

786 return self.get_current_page()

787

788 def get_table_of_contents(

789 self) -> List[Tuple[str, HeadingLevel, RenderingPosition]]:

790 """

791 Get the table of contents.

792

793 Returns:

794 List of (title, level, position) tuples

795 """

796 return self.chapter_navigator.get_table_of_contents()

797

798 def get_current_chapter(self) -> Optional[ChapterInfo]:

799 """

800 Get information about the current chapter.

801

802 Returns:

803 Current chapter info or None if no chapters

804 """

805 return self.chapter_navigator.get_current_chapter(self.current_position)

806

807 def add_bookmark(self, name: str) -> bool:

808 """

809 Add a bookmark at the current position.

810

811 Args:

812 name: Bookmark name

813

814 Returns:

815 True if bookmark was added successfully

816 """

817 try:

818 self.bookmark_manager.add_bookmark(name, self.current_position)

819 return True

820 except Exception:

821 return False

822

823 def remove_bookmark(self, name: str) -> bool:

824 """

825 Remove a bookmark.

826

827 Args:

828 name: Bookmark name

829

830 Returns:

831 True if bookmark was removed

832 """

833 return self.bookmark_manager.remove_bookmark(name)

834

835 def jump_to_bookmark(self, name: str) -> Optional[Page]:

836 """

837 Jump to a bookmark.

838

839 Args:

840 name: Bookmark name

841

842 Returns:

843 Page at bookmark position or None if bookmark not found

844 """

845 position = self.bookmark_manager.get_bookmark(name)

846 if position:

847 return self.jump_to_position(position)

848 return None

849

850 def list_bookmarks(self) -> List[Tuple[str, RenderingPosition]]:

851 """

852 Get all bookmarks.

853

854 Returns:

855 List of (name, position) tuples

856 """

857 return self.bookmark_manager.list_bookmarks()

858

859 # ------------------------------------------------------------------

860 # Highlights

861 #

862 # A Highlight carries pixel bounds, which belong to the one rendering it

863 # was taken from: change the font scale or page size and they no longer

864 # describe anything. Each highlight therefore also records the

865 # RenderingPosition of the page it was made on, and page association goes

866 # through that rather than through the bounds.

867 # ------------------------------------------------------------------

868

869 def highlight_point(self,

870 point: Tuple[int, int],

871 color: Tuple[int, int, int, int] = HighlightColor.YELLOW.value,

872 note: Optional[str] = None,

873 tags: Optional[List[str]] = None) -> Optional[Highlight]:

874 """

875 Highlight whatever is at a point on the current page.

876

877 Args:

878 point: (x, y) in page coordinates, as delivered by a tap

879 color: RGBA fill, e.g. one of HighlightColor

880 note: Optional annotation

881 tags: Optional categorization tags

882

883 Returns:

884 The stored Highlight, or None if nothing was at that point.

885 """

886 result = self.get_current_page().query_point(point)

887 if result is None or result.object_type == "empty":

888 return None

889

890 return self._store_highlight(result, color, note, tags)

891

892 def highlight_range(self,

893 start: Tuple[int, int],

894 end: Tuple[int, int],

895 color: Tuple[int, int, int, int] = HighlightColor.YELLOW.value,

896 note: Optional[str] = None,

897 tags: Optional[List[str]] = None) -> Optional[Highlight]:

898 """

899 Highlight the text between two points on the current page.

900

901 Args:

902 start: (x, y) where the selection began

903 end: (x, y) where the selection ended

904 color: RGBA fill, e.g. one of HighlightColor

905 note: Optional annotation

906 tags: Optional categorization tags

907

908 Returns:

909 The stored Highlight, or None if the range selected no text.

910 """

911 selection = self.get_current_page().query_range(start, end)

912 if not selection.results:

913 return None

914

915 return self._store_highlight(selection, color, note, tags)

916

917 def _store_highlight(self, result, color, note, tags) -> Highlight:

918 """Build a Highlight from a query result and persist it."""

919 highlight = create_highlight_from_query_result(

920 result, color=color, note=note, tags=tags,

921 position=self.current_position.to_dict())

922 self.highlight_manager.add_highlight(highlight)

923 return highlight

924

925 def remove_highlight(self, highlight_id: str) -> bool:

926 """

927 Remove a highlight.

928

929 Args:

930 highlight_id: ID of the highlight to remove

931

932 Returns:

933 True if it existed and was removed

934 """

935 return self.highlight_manager.remove_highlight(highlight_id)

936

937 def list_highlights(self) -> List[Highlight]:

938 """Get every highlight in this document."""

939 return self.highlight_manager.list_highlights()

940

941 def get_highlights_for_current_page(self) -> List[Highlight]:

942 """

943 Get the highlights made on the page currently being displayed.

944

945 Matched on the recorded RenderingPosition, so this stays correct across

946 font changes; highlights saved before the position field existed have

947 no position and are never matched.

948 """

949 current = self.current_position.to_dict()

950 return [h for h in self.highlight_manager.list_highlights()

951 if h.position == current]

952

953 def clear_highlights(self) -> None:

954 """Remove every highlight in this document."""

955 self.highlight_manager.clear_all()

956

957 # ------------------------------------------------------------------

958 # Pointer interaction

959 #

960 # Press/hover feedback is state that belongs to one rendered page, so the

961 # state machine is rebound whenever the displayed page changes. Callers get

962 # a fresh frame back when something changed visually, and None when nothing

963 # did - so a UI can skip a redraw it does not need.

964 # ------------------------------------------------------------------

965

966 def _interaction_state(self) -> InteractionStateManager:

967 """The state machine for the page currently displayed."""

968 page = self.get_current_page()

969 if self._interaction_page is not page:

970 if self._interaction_state_manager is not None:

971 self._interaction_state_manager.reset()

972 self._interaction_state_manager = InteractionStateManager(page)

973 self._interaction_page = page

974 return self._interaction_state_manager

975

976 def handle_hover(self, point: Tuple[int, int]) -> Optional[Image_.Image]:

977 """

978 Update hover feedback for a pointer at `point`.

979

980 Args:

981 point: (x, y) in page coordinates

982

983 Returns:

984 A re-rendered frame if the hover state changed, else None.

985 """

986 return self._interaction_state().update_hover(point)

987

988 def handle_touch_down(self, point: Tuple[int, int]) -> Optional[Image_.Image]:

989 """

990 Show pressed feedback for whatever interactive element is at `point`.

991

992 Args:

993 point: (x, y) in page coordinates

994

995 Returns:

996 A frame showing the pressed state, or None if nothing interactive

997 is there.

998 """

999 return self._interaction_state().handle_mouse_down(point)

1000

1001 def handle_touch_up(self, point: Tuple[int, int]) -> Tuple[Optional[Image_.Image], Any]:

1002 """

1003 Release the pressed element and run its action.

1004

1005 Args:

1006 point: (x, y) in page coordinates

1007

1008 Returns:

1009 (frame, callback_result). Both are None if no element was pressed.

1010 """

1011 return self._interaction_state().handle_mouse_up(point)

1012

1013 def reset_interaction_state(self) -> None:

1014 """Clear any hover or press feedback, e.g. when the pointer leaves."""

1015 if self._interaction_state_manager is not None:

1016 self._interaction_state_manager.reset()

1017

1018 def get_reading_progress(self) -> float:

1019 """

1020 Get reading progress as a percentage.

1021

1022 Returns:

1023 Progress from 0.0 to 1.0

1024 """

1025 if not self.blocks:

1026 return 0.0

1027

1028 # Simple progress calculation based on block index

1029 # A more sophisticated version would consider word positions

1030 total_blocks = len(self.blocks)

1031 current_block = min(self.current_position.block_index, total_blocks - 1)

1032

1033 return current_block / max(1, total_blocks - 1)

1034

1035 def has_cover(self) -> bool:

1036 """

1037 Check if the document has a cover page.

1038

1039 Returns:

1040 True if a cover page is available

1041 """

1042 return self._has_cover

1043

1044 def is_on_cover(self) -> bool:

1045 """

1046 Check if currently viewing the cover page.

1047

1048 Returns:

1049 True if on the cover page

1050 """

1051 return self._on_cover_page

1052

1053 def jump_to_cover(self) -> Optional[Page]:

1054 """

1055 Jump to the cover page if one exists.

1056

1057 Returns:

1058 Cover page or None if no cover exists

1059 """

1060 if not self._has_cover: 1060 ↛ 1061line 1060 didn't jump to line 1061 because the condition on line 1060 was never true

1061 return None

1062

1063 self._on_cover_page = True

1064 self._notify_position_changed()

1065 return self.get_current_page()

1066

1067 def get_position_info(self) -> Dict[str, Any]:

1068 """

1069 Get detailed information about the current position.

1070

1071 Returns:

1072 Dictionary with position details

1073 """

1074 current_chapter = self.get_current_chapter()

1075 font_family = self.get_font_family()

1076

1077 return {

1078 'position': self.current_position.to_dict(),

1079 'on_cover': self._on_cover_page,

1080 'has_cover': self._has_cover,

1081 'chapter': {

1082 'title': current_chapter.title if current_chapter else None,

1083 'level': current_chapter.level if current_chapter else None,

1084 'index': current_chapter.block_index if current_chapter else None

1085 },

1086 'progress': self.get_reading_progress(),

1087 'font_scale': self.font_scale,

1088 'font_family': font_family.value if font_family else None,

1089 'page_size': self.page_size

1090 }

1091

1092 def get_cache_stats(self) -> Dict[str, Any]:

1093 """

1094 Get cache statistics for debugging/monitoring.

1095

1096 Returns:

1097 Dictionary with cache statistics

1098 """

1099 return self.renderer.get_cache_stats()

1100

1101 def shutdown(self):

1102 """

1103 Shutdown the ereader manager and clean up resources.

1104 Call this when the application is closing.

1105

1106 Idempotent: calling it twice saves the position once.

1107 """

1108 if getattr(self, '_shutdown_done', False):

1109 return

1110 self._shutdown_done = True

1111

1112 # Save current position

1113 self.bookmark_manager.save_reading_position(self.current_position)

1114

1115 # Release cached pages

1116 self.renderer.shutdown()

1117

1118 def __del__(self):

1119 """

1120 Best-effort cleanup for callers that never called shutdown().

1121

1122 Finalisers run during interpreter teardown, when modules and globals

1123 may already be torn down, so this must never raise and must never

1124 block. Applications should call shutdown() explicitly.

1125 """

1126 try:

1127 self.shutdown()

1128 except Exception:

1129 pass

1130

1131

1132# Convenience function for quick setup

1133def create_ereader_manager(blocks: List[Block],

1134 page_size: Tuple[int, int],

1135 document_id: str = "default",

1136 **kwargs) -> EreaderLayoutManager:

1137 """

1138 Convenience function to create an ereader manager with sensible defaults.

1139

1140 Args:

1141 blocks: Document blocks to render

1142 page_size: Page size (width, height) in pixels

1143 document_id: Unique identifier for the document

1144 **kwargs: Additional arguments passed to EreaderLayoutManager

1145

1146 Returns:

1147 Configured EreaderLayoutManager instance

1148 """

1149 return EreaderLayoutManager(blocks, page_size, document_id, **kwargs)

+ + + diff --git a/cov_info/htmlcov/z_427cc3035faf7633_page_buffer_py.html b/cov_info/htmlcov/z_427cc3035faf7633_page_buffer_py.html new file mode 100644 index 0000000..4c17091 --- /dev/null +++ b/cov_info/htmlcov/z_427cc3035faf7633_page_buffer_py.html @@ -0,0 +1,443 @@ + + + + + Coverage for pyWebLayout/layout/page_buffer.py: 85% + + + + + +

+ Coverage for pyWebLayout/layout/page_buffer.py: + 85% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 110 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Page caching for ereader navigation.

4`PageBuffer` is an LRU cache of rendered pages plus the position links between

5them; `BufferedPageRenderer` wraps it around a `BidirectionalLayouter`.

7This module used to render pages ahead of time in a `ProcessPoolExecutor`. That

8never worked and has been removed — see S12 in docs/LAYOUT_REMEDIATION_SPEC.md

9and R1/R2 in docs/ARCHITECTURE_REVIEW.md. In short: the worker returned

10`pickle.dumps(page)`, and a Page holds a live PIL canvas, which is not

11picklable, so every job failed and the result was discarded. The cost — four

12interpreter copies and the whole block list shipped per job — was paid in full

13for no benefit. On Python 3.14, where the default start method became

14`forkserver`, submitting from module-level code raised outright.

16Prefetch is not needed. Measured on the tests/data Wikipedia fixture (411

17blocks) with the text caches warm, one page render costs:

19 800x600 p50 8.8 ms p95 15.4 ms

20 1072x1448 p50 13.8 ms p95 56.1 ms

22A page turn is cheaper than the IPC that was meant to hide it. If a slower

23target device ever changes that, the fallback is a synchronous `readahead()`

24method on this class, or a single worker *thread* — layout is PIL-bound and PIL

25releases the GIL — not a process pool. Making the concrete tree picklable

26(Page -> Line -> Text -> Font -> FreeTypeFont) is a large surface area to

27maintain for a cache.

28"""

30from __future__ import annotations

31from typing import Dict, Optional, List, Tuple, Any

32from collections import OrderedDict

34from .ereader_layout import RenderingPosition, BidirectionalLayouter, FontFamilyOverride

35from pyWebLayout.concrete.page import Page

36from pyWebLayout.abstract.block import Block

37from pyWebLayout.style.page_style import PageStyle

38from pyWebLayout.style.fonts import BundledFont

41class PageBuffer:

42 """

43 LRU cache of rendered pages, with separate forward and backward buffers and

44 the position links between adjacent pages.

45 """

47 def __init__(self, buffer_size: int = 5):

48 """

49 Initialize the page buffer.

51 Args:

52 buffer_size: Number of pages to cache in each direction

53 """

54 self.buffer_size = buffer_size

56 # LRU caches for forward and backward pages

57 self.forward_buffer: OrderedDict[RenderingPosition, Page] = OrderedDict()

58 self.backward_buffer: OrderedDict[RenderingPosition, Page] = OrderedDict()

60 # Position tracking for next/previous positions

61 self.position_map: Dict[RenderingPosition,

62 RenderingPosition] = {} # current -> next

63 self.reverse_position_map: Dict[RenderingPosition,

64 RenderingPosition] = {} # current -> previous

66 # Document state

67 self.blocks: Optional[List[Block]] = None

68 self.page_style: Optional[PageStyle] = None

69 self.current_font_scale: float = 1.0

70 self.current_font_family: Optional[BundledFont] = None

72 def initialize(

73 self,

74 blocks: List[Block],

75 page_style: PageStyle,

76 font_scale: float = 1.0,

77 font_family: Optional[BundledFont] = None):

78 """

79 Initialize the buffer with document blocks and page style.

81 Args:

82 blocks: Document blocks to render

83 page_style: Page styling configuration

84 font_scale: Current font scaling factor

85 font_family: Optional font family override

86 """

87 self.blocks = blocks

88 self.page_style = page_style

89 self.current_font_scale = font_scale

90 self.current_font_family = font_family

92 def get_page(self, position: RenderingPosition) -> Optional[Page]:

93 """

94 Get a cached page if available.

96 Args:

97 position: Position to get page for

99 Returns:

100 Cached page or None if not available

101 """

102 # Check forward buffer first

103 if position in self.forward_buffer:

104 # Move to end (most recently used)

105 page = self.forward_buffer.pop(position)

106 self.forward_buffer[position] = page

107 return page

109 # Check backward buffer

110 if position in self.backward_buffer:

111 # Move to end (most recently used)

112 page = self.backward_buffer.pop(position)

113 self.backward_buffer[position] = page

114 return page

116 return None

118 def cache_page(

119 self,

120 position: RenderingPosition,

121 page: Page,

122 next_position: Optional[RenderingPosition] = None,

123 is_backward: bool = False):

124 """

125 Cache a rendered page with LRU eviction.

127 Args:

128 position: Position of the page

129 page: Rendered page to cache

130 next_position: Position of the next page (for forward navigation)

131 is_backward: Whether this is a backward-rendered page

132 """

133 target_buffer = self.backward_buffer if is_backward else self.forward_buffer

135 # Add to cache

136 target_buffer[position] = page

138 # Track position relationships

139 if next_position:

140 if is_backward:

141 self.reverse_position_map[next_position] = position

142 else:

143 self.position_map[position] = next_position

145 # Evict oldest if buffer is full

146 if len(target_buffer) > self.buffer_size:

147 oldest_pos, _ = target_buffer.popitem(last=False)

148 # Clean up position maps

149 self.position_map.pop(oldest_pos, None)

150 self.reverse_position_map.pop(oldest_pos, None)

152 def invalidate_all(self):

153 """Clear all cached pages"""

154 self.forward_buffer.clear()

155 self.backward_buffer.clear()

156 self.position_map.clear()

157 self.reverse_position_map.clear()

159 def set_font_scale(self, font_scale: float):

160 """

161 Update font scale and invalidate cache.

162

163 Args:

164 font_scale: New font scaling factor

165 """

166 if font_scale != self.current_font_scale:

167 self.current_font_scale = font_scale

168 self.invalidate_all()

170 def set_font_family(self, font_family: Optional[BundledFont]):

171 """

172 Update font family and invalidate cache.

174 Args:

175 font_family: New font family (None = use original fonts)

176 """

177 if font_family != self.current_font_family:

178 self.current_font_family = font_family

179 self.invalidate_all()

181 def get_cache_stats(self) -> Dict[str, Any]:

182 """Get cache statistics for debugging/monitoring"""

183 return {

184 'forward_buffer_size': len(self.forward_buffer),

185 'backward_buffer_size': len(self.backward_buffer),

186 'position_mappings': len(self.position_map),

187 'reverse_position_mappings': len(self.reverse_position_map),

188 'current_font_scale': self.current_font_scale,

189 'current_font_family': self.current_font_family.value if self.current_font_family else None

190 }

192 def shutdown(self):

193 """

194 Release cached pages.

196 Cheap and idempotent. There is deliberately no __del__ calling this:

197 blocking work in a finaliser is what deadlocked the interpreter at exit

198 while the process pool existed.

199 """

200 self.invalidate_all()

203class BufferedPageRenderer:

204 """

205 High-level interface for page rendering with an LRU cache in front of the

206 layouter.

207 """

208

209 def __init__(self,

210 blocks: List[Block],

211 page_style: PageStyle,

212 buffer_size: int = 5,

213 page_size: Tuple[int,

214 int] = (800,

215 600),

216 font_family: Optional[BundledFont] = None):

217 """

218 Initialize the buffered renderer.

219

220 Args:

221 blocks: Document blocks to render

222 page_style: Page styling configuration

223 buffer_size: Number of pages to cache in each direction

224 page_size: Page size (width, height) in pixels

225 font_family: Optional font family override

226 """

227 # Create font family override if specified

228 font_family_override = FontFamilyOverride(font_family) if font_family else None

230 self.layouter = BidirectionalLayouter(blocks, page_style, page_size, font_family_override=font_family_override)

231 self.buffer = PageBuffer(buffer_size)

232 self.buffer.initialize(blocks, page_style, font_family=font_family)

233 self.page_size = page_size

234 self.blocks = blocks

235 self.page_style = page_style

237 self.current_position = RenderingPosition()

238 self.font_scale = 1.0

239 self.font_family = font_family

241 def render_page(self, position: RenderingPosition,

242 font_scale: float = 1.0) -> Tuple[Page, RenderingPosition]:

243 """

244 Render a page, serving it from cache when possible.

246 Args:

247 position: Position to render from

248 font_scale: Font scaling factor

250 Returns:

251 Tuple of (rendered_page, next_position)

252 """

253 # Update font scale if changed

254 if font_scale != self.font_scale:

255 self.font_scale = font_scale

256 self.buffer.set_font_scale(font_scale)

257

258 # Check cache first

259 cached_page = self.buffer.get_page(position)

260 if cached_page:

261 # Only use the cache if we also know where the next page starts;

262 # otherwise fall through and compute it.

263 next_pos = self.buffer.position_map.get(position)

264 if next_pos is not None:

265 return cached_page, next_pos

266

267 # Render the page directly

268 page, next_pos = self.layouter.render_page_forward(position, font_scale)

270 # Cache the result

271 self.buffer.cache_page(position, page, next_pos)

273 return page, next_pos

275 def render_page_backward(self,

276 end_position: RenderingPosition,

277 font_scale: float = 1.0) -> Tuple[Page,

278 RenderingPosition]:

279 """

280 Render a page ending at the given position, serving it from cache when

281 possible.

282

283 Args:

284 end_position: Position where page should end

285 font_scale: Font scaling factor

287 Returns:

288 Tuple of (rendered_page, start_position)

289 """

290 # Update font scale if changed

291 if font_scale != self.font_scale: 291 ↛ 292line 291 didn't jump to line 292 because the condition on line 291 was never true

292 self.font_scale = font_scale

293 self.buffer.set_font_scale(font_scale)

295 # Check cache first

296 cached_page = self.buffer.get_page(end_position)

297 if cached_page: 297 ↛ 300line 297 didn't jump to line 300 because the condition on line 297 was never true

298 # Only use the cache if we also know where the previous page

299 # starts; otherwise fall through and compute it.

300 prev_pos = self.buffer.reverse_position_map.get(end_position)

301 if prev_pos is not None:

302 return cached_page, prev_pos

304 # Render the page directly

305 page, start_pos = self.layouter.render_page_backward(end_position, font_scale)

307 # Cache the result

308 self.buffer.cache_page(start_pos, page, end_position, is_backward=True)

310 return page, start_pos

312 def set_font_family(self, font_family: Optional[BundledFont]):

313 """

314 Change the font family and invalidate cache.

316 Args:

317 font_family: New font family (None = use original fonts)

318 """

319 if font_family != self.font_family:

320 self.font_family = font_family

322 # Update buffer

323 self.buffer.set_font_family(font_family)

325 # Recreate layouter with new font family override

326 font_family_override = FontFamilyOverride(font_family) if font_family else None

327 self.layouter = BidirectionalLayouter(

328 self.blocks,

329 self.page_style,

330 self.page_size,

331 font_family_override=font_family_override

332 )

333

334 def get_font_family(self) -> Optional[BundledFont]:

335 """Get the current font family override"""

336 return self.font_family

338 def get_cache_stats(self) -> Dict[str, Any]:

339 """Get cache statistics"""

340 return self.buffer.get_cache_stats()

342 def shutdown(self):

343 """Release cached pages"""

344 self.buffer.shutdown()

+ + + diff --git a/cov_info/htmlcov/z_427cc3035faf7633_table_optimizer_py.html b/cov_info/htmlcov/z_427cc3035faf7633_table_optimizer_py.html new file mode 100644 index 0000000..37e6c75 --- /dev/null +++ b/cov_info/htmlcov/z_427cc3035faf7633_table_optimizer_py.html @@ -0,0 +1,495 @@ + + + + + Coverage for pyWebLayout/layout/table_optimizer.py: 88% + + + + + +

+ Coverage for pyWebLayout/layout/table_optimizer.py: + 88% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 151 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Table column width optimization for pyWebLayout.

4This module provides intelligent column width distribution for tables,

5ensuring optimal space usage while respecting content constraints.

6"""

8from typing import List, Tuple, Optional, Dict

9from pyWebLayout.abstract.block import Table, TableRow

12def optimize_table_layout(table: Table,

13 available_width: int,

14 sample_size: int = 5,

15 style=None) -> List[int]:

16 """

17 Optimize column widths for a table.

19 Strategy:

20 1. Check for HTML width overrides (colspan, width attributes)

21 2. Sample first ~5 rows to estimate column requirements (performance)

22 3. Calculate minimum width for each column (longest unbreakable word)

23 4. Calculate preferred width for each column (no wrapping)

24 5. If total preferred fits: use preferred

25 6. Otherwise: distribute available space proportionally

26 7. Ensure no column < min_width

28 Note: Hyphenation threshold is controlled by Font.min_hyphenation_width,

29 not passed as a parameter here to avoid duplication.

31 Args:

32 table: The table to optimize

33 available_width: Total width available

34 sample_size: Number of rows to sample for measurement (default 5)

35 style: Optional table style for border/padding calculations

37 Returns:

38 List of optimized column widths

39 """

40 from pyWebLayout.concrete.dynamic_page import DynamicPage

42 n_cols = get_column_count(table)

43 if n_cols == 0:

44 return []

46 # Account for table borders/padding overhead

47 if style:

48 overhead = calculate_table_overhead(n_cols, style)

49 available_for_content = available_width - overhead

50 else:

51 # Default border overhead

52 border_width = 1

53 overhead = border_width * (n_cols + 1)

54 available_for_content = available_width - overhead

56 # Phase 0: Check for HTML width overrides

57 html_widths = extract_html_column_widths(table)

58 fixed_columns = {i: width for i, width in enumerate(html_widths) if width is not None}

60 # Phase 1: Sample rows and measure constraints for each column

61 min_widths = [] # Minimum without breaking words (Font handles hyphenation)

62 pref_widths = [] # Preferred (no wrapping)

64 # Sample first ~5 rows from each section (header, body, footer)

65 sampled_rows = sample_table_rows(table, sample_size)

67 for col_idx in range(n_cols):

68 # Check if this column has HTML width override

69 if col_idx in fixed_columns: 69 ↛ 70line 69 didn't jump to line 70 because the condition on line 69 was never true

70 fixed_width = fixed_columns[col_idx]

71 min_widths.append(fixed_width)

72 pref_widths.append(fixed_width)

73 continue

75 col_min = 50 # Absolute minimum

76 col_pref = 50

78 # Check sampled cells in this column

79 for row in sampled_rows:

80 cells = list(row.cells())

81 if col_idx >= len(cells): 81 ↛ 82line 81 didn't jump to line 82 because the condition on line 81 was never true

82 continue

84 cell = cells[col_idx]

86 # Create a DynamicPage for this cell with no padding/borders

87 # (we're just measuring content, not rendering a full page)

88 from pyWebLayout.style.page_style import PageStyle

89 measurement_style = PageStyle(padding=(0, 0, 0, 0), border_width=0)

90 cell_page = DynamicPage(style=measurement_style)

92 # Add cell content to page

93 layout_cell_content(cell_page, cell)

95 # Measure minimum width (Font's min_hyphenation_width controls breaking)

96 # DynamicPage returns pure content width (no padding since we set it to 0)

97 # TableRenderer will add cell padding later

98 cell_min = cell_page.get_min_width()

99 col_min = max(col_min, cell_min)

101 # Measure preferred width (no wrapping)

102 cell_pref = cell_page.get_preferred_width()

103 col_pref = max(col_pref, cell_pref)

105 min_widths.append(col_min)

106 pref_widths.append(col_pref)

108 # Phase 2: Distribute width (respecting fixed columns)

109 return distribute_column_widths(

110 min_widths,

111 pref_widths,

112 available_for_content,

113 fixed_columns

114 )

117def layout_cell_content(page, cell):

118 """

119 Layout cell content onto a DynamicPage.

121 This adds all blocks from the cell (paragraphs, images, etc.)

122 as children of the page so they can be measured.

123

124 Args:

125 page: DynamicPage to add content to

126 cell: TableCell containing blocks

127 """

128 from pyWebLayout.concrete.text import Line, Text

129 from pyWebLayout.style.fonts import Font

130 from pyWebLayout.style import FontWeight, Alignment

131 from pyWebLayout.abstract.block import Paragraph, Heading

132 from PIL import Image as PILImage, ImageDraw

133

134 # Default font for measurement

135 font_size = 12

136 font_path = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"

137 font = Font(font_path=font_path, font_size=font_size)

139 # Create a minimal draw context for Text measurement

140 # (Text needs this for width calculation)

141 dummy_img = PILImage.new('RGB', (1, 1))

142 dummy_draw = ImageDraw.Draw(dummy_img)

143

144 # Get all blocks from the cell

145 for block in cell.blocks():

146 if isinstance(block, (Paragraph, Heading)):

147 # Get words from the block

148 word_items = block.words() if callable(block.words) else block.words

149 words = list(word_items)

151 if not words: 151 ↛ 152line 151 didn't jump to line 152 because the condition on line 151 was never true

152 continue

153

154 # Create a line for measurement

155 line = Line(

156 spacing=(3, 6), # word spacing

157 origin=(0, 0),

158 size=(1000, 20), # Large size for measurement

159 draw=dummy_draw,

160 font=font,

161 halign=Alignment.LEFT

162 )

163

164 # Add all words to estimate width

165 for word_item in words:

166 # Handle word tuples (index, word_obj)

167 if isinstance(word_item, tuple) and len(word_item) >= 2: 167 ↛ 168line 167 didn't jump to line 168 because the condition on line 167 was never true

168 word_obj = word_item[1]

169 else:

170 word_obj = word_item

172 # Extract text from the word

173 word_text = word_obj.text if hasattr(word_obj, 'text') else str(word_obj)

175 # Create Text object for the word

176 # Text constructor: (text, style, draw)

177 text_obj = Text(

178 text=word_text,

179 style=font, # Font is the style

180 draw=dummy_draw

181 )

183 line._text_objects.append(text_obj)

185 # Add line to page

186 page.add_child(line)

189def get_column_count(table: Table) -> int:

190 """

191 Get the number of columns in a table.

193 Args:

194 table: The table to analyze

196 Returns:

197 Number of columns

198 """

199 all_rows = list(table.all_rows())

200 if not all_rows:

201 return 0

203 # Get from first row

204 first_row = all_rows[0][1]

205 return first_row.cell_count

208def sample_table_rows(table: Table, sample_size: int) -> List[TableRow]:

209 """

210 Sample first ~sample_size rows from each table section.

212 Args:

213 table: The table to sample

214 sample_size: Number of rows to sample per section

216 Returns:

217 List of sampled rows

218 """

219 sampled = []

221 for section in ["header", "body", "footer"]:

222 section_rows = [row for sec, row in table.all_rows() if sec == section]

223 # Take first sample_size rows (or fewer if section is smaller)

224 sampled.extend(section_rows[:sample_size])

226 return sampled

228

229def extract_html_column_widths(table: Table) -> List[Optional[int]]:

230 """

231 Extract column width overrides from HTML attributes.

232

233 Checks for:

234 - <col width="100px"> elements

235 - <td width="100px"> in first row

236 - <th width="100px"> in header

238 Args:

239 table: The table to check

241 Returns:

242 List of widths (None for auto-layout columns)

243 """

244 n_cols = get_column_count(table)

245 widths = [None] * n_cols

246

247 # Check for <col> elements with width

248 if hasattr(table, 'col_widths'): 248 ↛ 249line 248 didn't jump to line 249 because the condition on line 248 was never true

249 for i, width in enumerate(table.col_widths):

250 if width is not None:

251 widths[i] = parse_html_width(width)

253 # Check first row cells for width attributes

254 all_rows = list(table.all_rows())

255 if all_rows: 255 ↛ 262line 255 didn't jump to line 262 because the condition on line 255 was always true

256 first_row = all_rows[0][1]

257 cells = list(first_row.cells())

258 for i, cell in enumerate(cells):

259 if i < len(widths) and hasattr(cell, 'width') and cell.width is not None:

260 widths[i] = parse_html_width(cell.width)

262 return widths

263

265def parse_html_width(width_value) -> Optional[int]:

266 """

267 Parse HTML width value (e.g., "100px", "20%", "100").

269 Args:

270 width_value: HTML width attribute value

271

272 Returns:

273 Width in pixels, or None if percentage/invalid

274 """

275 if isinstance(width_value, int):

276 return width_value

278 if isinstance(width_value, str): 278 ↛ 299line 278 didn't jump to line 299 because the condition on line 278 was always true

279 # Remove whitespace

280 width_value = width_value.strip()

282 # Percentage widths not supported yet

283 if '%' in width_value:

284 return None

286 # Parse pixel values

287 if width_value.endswith('px'):

288 try:

289 return int(width_value[:-2])

290 except ValueError:

291 return None

293 # Plain number

294 try:

295 return int(width_value)

296 except ValueError:

297 return None

299 return None

302def distribute_column_widths(min_widths: List[int],

303 pref_widths: List[int],

304 available_width: int,

305 fixed_columns: Dict[int, int]) -> List[int]:

306 """

307 Distribute width among columns, respecting fixed column widths.

309 Args:

310 min_widths: Minimum width for each column

311 pref_widths: Preferred width for each column

312 available_width: Total width available

313 fixed_columns: Dict mapping column index to fixed width

314

315 Returns:

316 List of final column widths

317 """

318 n_cols = len(min_widths)

319 if n_cols == 0:

320 return []

322 # Calculate available space for flexible columns

323 fixed_total = sum(fixed_columns.values())

324 flexible_available = available_width - fixed_total

325

326 # Get indices of flexible columns

327 flexible_cols = [i for i in range(n_cols) if i not in fixed_columns]

329 if not flexible_cols:

330 # All columns fixed - return as-is

331 return [fixed_columns.get(i, min_widths[i]) for i in range(n_cols)]

332

333 # Calculate totals for flexible columns only

334 flex_min_total = sum(min_widths[i] for i in flexible_cols)

335 flex_pref_total = sum(pref_widths[i] for i in flexible_cols)

336

337 # Distribute space among flexible columns

338 widths = [0] * n_cols

339

340 # Set fixed columns

341 for i, width in fixed_columns.items():

342 widths[i] = width

344 # Distribute to flexible columns

345 if flex_pref_total <= flexible_available:

346 # Preferred widths fit - distribute remaining space proportionally

347 extra_space = flexible_available - flex_pref_total

349 if extra_space > 0 and flex_pref_total > 0:

350 # Distribute extra space proportionally based on preferred widths

351 for i in flexible_cols:

352 proportion = pref_widths[i] / flex_pref_total

353 widths[i] = int(pref_widths[i] + (extra_space * proportion))

354 else:

355 # No extra space, just use preferred widths

356 for i in flexible_cols:

357 widths[i] = pref_widths[i]

358 elif flex_min_total > flexible_available:

359 # Can't satisfy minimum - force it anyway (graceful degradation)

360 for i in flexible_cols:

361 widths[i] = min_widths[i]

362 else:

363 # Proportional distribution between min and pref

364 extra_space = flexible_available - flex_min_total

365 flex_pref_over_min = flex_pref_total - flex_min_total

367 for i in flexible_cols:

368 if flex_pref_over_min > 0: 368 ↛ 374line 368 didn't jump to line 374 because the condition on line 368 was always true

369 pref_over_min = pref_widths[i] - min_widths[i]

370 proportion = pref_over_min / flex_pref_over_min

371 extra = extra_space * proportion

372 widths[i] = int(min_widths[i] + extra)

373 else:

374 widths[i] = int(min_widths[i])

376 return widths

379def calculate_table_overhead(n_cols: int, style) -> int:

380 """

381 Calculate the pixel overhead for table borders and spacing.

383 Args:

384 n_cols: Number of columns

385 style: TableStyle object

386

387 Returns:

388 Total pixel overhead

389 """

390 # Border on each side of each column + outer borders

391 border_overhead = style.border_width * (n_cols + 1)

393 # Cell spacing if any

394 spacing_overhead = style.cell_spacing * (n_cols - 1) if n_cols > 1 else 0

396 return border_overhead + spacing_overhead

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2___init___py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2___init___py.html new file mode 100644 index 0000000..4d93183 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2___init___py.html @@ -0,0 +1,135 @@ + + + + + Coverage for pyWebLayout/concrete/__init__.py: 100% + + + + + +

+ Coverage for pyWebLayout/concrete/init.py: + 100% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 7 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Concrete layer for the pyWebLayout library.

4This package contains concrete implementations that can be directly rendered.

5"""

7from .text import (

8 Text,

9 Line,

10 configure_text_caches,

11 clear_text_caches,

12 text_cache_stats,

13 prewarm_text_caches,

14)

15from .box import Box

16from .image import RenderableImage

17from .page import Page

18from pyWebLayout.abstract.block import Table, TableRow as Row, TableCell as Cell

19from .functional import LinkText, ButtonText

21__all__ = [

22 'Text',

23 'Line',

24 'Box',

25 'RenderableImage',

26 'Page',

27 'Table',

28 'Row',

29 'Cell',

30 'LinkText',

31 'ButtonText',

32 'configure_text_caches',

33 'clear_text_caches',

34 'text_cache_stats',

35 'prewarm_text_caches',

36]

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_box_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_box_py.html new file mode 100644 index 0000000..40d6192 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_box_py.html @@ -0,0 +1,139 @@ + + + + + Coverage for pyWebLayout/concrete/box.py: 100% + + + + + +

+ Coverage for pyWebLayout/concrete/box.py: + 100% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 19 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

2import numpy as np

3from PIL import Image

5from pyWebLayout.core.base import Renderable, Queriable

6from pyWebLayout.core import Geometric

7from pyWebLayout.style import Alignment

10class Box(Geometric, Renderable, Queriable):

11 """

12 A box with geometric properties (origin and size).

14 Uses Geometric mixin for origin and size management.

15 """

17 def __init__(

18 self,

19 origin,

20 size,

21 callback=None,

22 sheet: Image = None,

23 mode: bool = None,

24 halign=Alignment.CENTER,

25 valign=Alignment.CENTER):

26 super().__init__(origin=origin, size=size)

27 self._end = self._origin + self._size

28 self._callback = callback

29 self._sheet: Image = sheet

30 if self._sheet is None:

31 self._mode = mode

32 else:

33 self._mode = sheet.mode

34 self._halign = halign

35 self._valign = valign

37 # origin and size properties are provided by Geometric mixin

39 def in_shape(self, point):

40 return np.all((point >= self._origin) & (point < self._end), axis=-1)

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_dynamic_page_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_dynamic_page_py.html new file mode 100644 index 0000000..aa51501 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_dynamic_page_py.html @@ -0,0 +1,517 @@ + + + + + Coverage for pyWebLayout/concrete/dynamic_page.py: 68% + + + + + +

+ Coverage for pyWebLayout/concrete/dynamic_page.py: + 68% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 178 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2DynamicPage implementation for pyWebLayout.

4A DynamicPage is a page that dynamically sizes itself based on content and constraints.

5Unlike a regular Page with fixed size, a DynamicPage measures its content first and

6then layouts within the allocated space.

8Use cases:

9- Table cells that need to fit content

10- Containers that should grow with content

11- Responsive layouts that adapt to constraints

12"""

14from typing import Tuple, Optional, List

15from dataclasses import dataclass

16import numpy as np

17from PIL import Image

19from pyWebLayout.concrete.page import Page

20from pyWebLayout.style.page_style import PageStyle

21from pyWebLayout.core.base import Renderable

24@dataclass

25class SizeConstraints:

26 """Size constraints for dynamic layout."""

27 min_width: Optional[int] = None

28 max_width: Optional[int] = None

29 min_height: Optional[int] = None

30 max_height: Optional[int] = None

31 # Note: Hyphenation threshold is controlled by Font.min_hyphenation_width

32 # Don't duplicate that logic here

35class DynamicPage(Page):

36 """

37 A page that dynamically sizes itself based on content and constraints.

39 The layout process has two phases:

40 1. Measurement: Calculate intrinsic size needed for content

41 2. Layout: Position content within allocated size

43 This allows containers (like tables) to optimize space allocation before rendering.

44 """

46 def __init__(self,

47 constraints: Optional[SizeConstraints] = None,

48 style: Optional[PageStyle] = None):

49 """

50 Initialize a dynamic page.

52 Args:

53 constraints: Optional size constraints (min/max width/height)

54 style: The PageStyle defining borders, spacing, and appearance

55 """

56 # Start with zero size - will be determined during measurement/layout

57 super().__init__(size=(0, 0), style=style)

58 self._constraints = constraints if constraints is not None else SizeConstraints()

60 # Measurement state

61 self._is_measured = False

62 self._intrinsic_size: Optional[Tuple[int, int]] = None

63 self._min_width_cache: Optional[int] = None

64 self._preferred_width_cache: Optional[int] = None

65 self._content_height_cache: Optional[int] = None

67 # Pagination state

68 self._render_offset = 0 # For partial rendering (pagination)

69 self._is_laid_out = False

71 @property

72 def constraints(self) -> SizeConstraints:

73 """Get the size constraints for this page."""

74 return self._constraints

76 def measure(self, available_width: Optional[int] = None) -> Tuple[int, int]:

77 """

78 Measure the intrinsic size needed for content.

80 This walks through all children and calculates how much space they need.

81 The measurement respects constraints (min/max width/height).

83 Args:

84 available_width: Optional width constraint for wrapping content

86 Returns:

87 Tuple of (width, height) needed

88 """

89 if self._is_measured and self._intrinsic_size is not None:

90 return self._intrinsic_size

92 # Apply constraints to available width

93 if available_width is not None:

94 if self._constraints.max_width is not None: 94 ↛ 95line 94 didn't jump to line 95 because the condition on line 94 was never true

95 available_width = min(available_width, self._constraints.max_width)

96 if self._constraints.min_width is not None:

97 available_width = max(available_width, self._constraints.min_width)

99 # Measure content

100 # For now, walk through children and sum their sizes

101 total_width = 0

102 total_height = 0

104 for child in self._children: 104 ↛ 105line 104 didn't jump to line 105 because the loop on line 104 never started

105 if hasattr(child, 'measure'):

106 # Child is also dynamic - ask it to measure

107 child_size = child.measure(available_width)

108 child_width, child_height = child_size

109 else:

110 # Child has fixed size

111 child_width = child.size[0] if hasattr(child, 'size') else 0

112 child_height = child.size[1] if hasattr(child, 'size') else 0

113

114 total_width = max(total_width, child_width)

115 total_height += child_height

117 # Add page padding/borders

118 total_width += self._style.total_horizontal_padding + self._style.total_border_width

119 total_height += self._style.total_vertical_padding + self._style.total_border_width

121 # Apply constraints

122 if self._constraints.min_width is not None:

123 total_width = max(total_width, self._constraints.min_width)

124 if self._constraints.max_width is not None: 124 ↛ 125line 124 didn't jump to line 125 because the condition on line 124 was never true

125 total_width = min(total_width, self._constraints.max_width)

126 if self._constraints.min_height is not None:

127 total_height = max(total_height, self._constraints.min_height)

128 if self._constraints.max_height is not None: 128 ↛ 129line 128 didn't jump to line 129 because the condition on line 128 was never true

129 total_height = min(total_height, self._constraints.max_height)

131 self._intrinsic_size = (total_width, total_height)

132 self._is_measured = True

133

134 return self._intrinsic_size

136 def get_min_width(self) -> int:

137 """

138 Get minimum width needed to render content.

140 This finds the widest word/element that cannot be broken,

141 using Font.min_hyphenation_width for hyphenation control.

143 Returns:

144 Minimum width in pixels

145 """

146 # Check cache

147 if self._min_width_cache is not None: 147 ↛ 148line 147 didn't jump to line 148 because the condition on line 147 was never true

148 return self._min_width_cache

150 # Calculate minimum width based on content

151 from pyWebLayout.concrete.text import Line, Text

153 min_width = 0

155 # Walk through children and find longest unbreakable segment

156 for child in self._children:

157 if isinstance(child, Line): 157 ↛ 170line 157 didn't jump to line 170 because the condition on line 157 was always true

158 # Check all words in the line

159 # Font's min_hyphenation_width already controls breaking

160 for text_obj in getattr(child, '_text_objects', []):

161 if isinstance(text_obj, Text) and hasattr(text_obj, '_text'): 161 ↛ 160line 161 didn't jump to line 160 because the condition on line 161 was always true

162 word_text = text_obj._text

163 # Text stores font in _style, not _font

164 font = getattr(text_obj, '_style', None)

166 if font: 166 ↛ 160line 166 didn't jump to line 160 because the condition on line 166 was always true

167 # Just measure the word - Font handles hyphenation rules

168 word_width = int(font.font.getlength(word_text))

169 min_width = max(min_width, word_width)

170 elif hasattr(child, 'get_min_width'):

171 # Child supports min width calculation

172 child_min = child.get_min_width()

173 min_width = max(min_width, child_min)

174 elif hasattr(child, 'size'):

175 # Use actual width

176 min_width = max(min_width, child.size[0])

178 # Add padding/borders

179 min_width += self._style.total_horizontal_padding + self._style.total_border_width

181 # Apply minimum constraint

182 if self._constraints.min_width is not None: 182 ↛ 183line 182 didn't jump to line 183 because the condition on line 182 was never true

183 min_width = max(min_width, self._constraints.min_width)

185 self._min_width_cache = min_width

186 return min_width

188 def get_preferred_width(self) -> int:

189 """

190 Get preferred width (no wrapping).

192 This returns the width needed to render all content without any

193 line wrapping.

195 Returns:

196 Preferred width in pixels

197 """

198 # Check cache

199 if self._preferred_width_cache is not None: 199 ↛ 200line 199 didn't jump to line 200 because the condition on line 199 was never true

200 return self._preferred_width_cache

202 # Calculate preferred width (no wrapping)

203 from pyWebLayout.concrete.text import Line

205 pref_width = 0

207 for child in self._children:

208 if isinstance(child, Line): 208 ↛ 227line 208 didn't jump to line 227 because the condition on line 208 was always true

209 # Get line width without wrapping (including spacing between words)

210 text_objects = getattr(child, '_text_objects', [])

211 if text_objects: 211 ↛ 207line 211 didn't jump to line 207 because the condition on line 211 was always true

212 line_width = 0

213 for i, text_obj in enumerate(text_objects):

214 if hasattr(text_obj, '_text') and hasattr(text_obj, '_style'): 214 ↛ 213line 214 didn't jump to line 213 because the condition on line 214 was always true

215 # Text stores font in _style, not _font

216 word_width = text_obj._style.font.getlength(text_obj._text)

217 line_width += word_width

219 # Add spacing after word (except last word)

220 if i < len(text_objects) - 1:

221 # Get spacing from Line if available, otherwise use default

222 spacing = getattr(child, '_spacing', (3, 6))

223 # Use minimum spacing for preferred width calculation

224 line_width += spacing[0] if isinstance(spacing, tuple) else 3

226 pref_width = max(pref_width, line_width)

227 elif hasattr(child, 'get_preferred_width'):

228 child_pref = child.get_preferred_width()

229 pref_width = max(pref_width, child_pref)

230 elif hasattr(child, 'size'):

231 # Use actual size

232 pref_width = max(pref_width, child.size[0])

234 # Add padding/borders

235 pref_width += self._style.total_horizontal_padding + self._style.total_border_width

237 # Apply constraints

238 if self._constraints.max_width is not None: 238 ↛ 239line 238 didn't jump to line 239 because the condition on line 238 was never true

239 pref_width = min(pref_width, self._constraints.max_width)

240 if self._constraints.min_width is not None: 240 ↛ 241line 240 didn't jump to line 241 because the condition on line 240 was never true

241 pref_width = max(pref_width, self._constraints.min_width)

242

243 self._preferred_width_cache = pref_width

244 return pref_width

246 def measure_content_height(self) -> int:

247 """

248 Measure total height needed to render all content.

250 This is used for pagination to know how much content remains.

252 Returns:

253 Total height in pixels

254 """

255 # Check cache

256 if self._content_height_cache is not None:

257 return self._content_height_cache

259 total_height = 0

260

261 for child in self._children: 261 ↛ 262line 261 didn't jump to line 262 because the loop on line 261 never started

262 if hasattr(child, 'measure_content_height'):

263 child_height = child.measure_content_height()

264 elif hasattr(child, 'size'):

265 child_height = child.size[1]

266 else:

267 child_height = 0

269 total_height += child_height

271 # Add padding/borders

272 total_height += self._style.total_vertical_padding + self._style.total_border_width

273

274 self._content_height_cache = total_height

275 return total_height

277 def layout(self, size: Tuple[int, int]):

278 """

279 Layout content within the given size.

281 This is called after measurement to position children within

282 the allocated space.

284 Args:

285 size: The final size allocated to this page (width, height)

286 """

287 # Set the page size

288 self._size = size

290 # Position children sequentially

291 # Use the same logic as Page but now we know our final size

292 content_x = self._style.border_width + self._style.padding_left

293 content_y = self._style.border_width + self._style.padding_top

295 self._current_y_offset = content_y

296 self._is_first_line = True

298 # Children position themselves, we just track y_offset

299 # The actual positioning happens when children render

301 self._is_laid_out = True

302 self._dirty = True # Mark for re-render

304 def render(self) -> Image.Image:

305 """

306 Render the page with all its children.

307

308 If not yet measured/laid out, use intrinsic sizing.

310 Returns:

311 PIL Image containing the rendered page

312 """

313 # Ensure we have a valid size

314 if self._size[0] == 0 or self._size[1] == 0:

315 if not self._is_measured: 315 ↛ 319line 315 didn't jump to line 319 because the condition on line 315 was always true

316 # Auto-measure with no constraints

317 self.measure()

319 if self._intrinsic_size: 319 ↛ 323line 319 didn't jump to line 323 because the condition on line 319 was always true

320 self._size = self._intrinsic_size

321 else:

322 # Fallback to minimum size

323 self._size = (100, 100)

325 # Use parent's render implementation

326 return super().render()

327

328 # Pagination Support

329 # ------------------

331 def render_partial(self, available_height: int) -> int:

332 """

333 Render as much content as fits in available_height.

335 This is used for pagination when a page needs to be split across

336 multiple output pages.

338 Args:

339 available_height: Height available on current page

341 Returns:

342 Amount of content rendered (in pixels)

343 """

344 # Calculate how many children fit in available height

345 rendered_height = 0

346 content_start_y = self._style.border_width + self._style.padding_top

347

348 for i, child in enumerate(self._children): 348 ↛ 350line 348 didn't jump to line 350 because the loop on line 348 never started

349 # Skip already rendered children

350 if rendered_height < self._render_offset:

351 if hasattr(child, 'size'):

352 rendered_height += child.size[1]

353 continue

355 # Check if this child fits

356 child_height = child.size[1] if hasattr(child, 'size') else 0

357

358 if rendered_height + child_height <= available_height:

359 # Child fits - render it

360 if hasattr(child, 'render'):

361 child.render()

362 rendered_height += child_height

363 else:

364 # No more space

365 break

367 # Update render offset for next call

368 self._render_offset = rendered_height

369

370 return rendered_height

371

372 def has_more_content(self) -> bool:

373 """

374 Check if there's unrendered content remaining.

376 Returns:

377 True if more content needs to be rendered

378 """

379 total_height = self.measure_content_height()

380 return self._render_offset < total_height

381

382 def reset_pagination(self):

383 """Reset pagination to render from beginning."""

384 self._render_offset = 0

385

386 def invalidate_caches(self):

387 """Invalidate all measurement caches (call when children change)."""

388 self._is_measured = False

389 self._intrinsic_size = None

390 self._min_width_cache = None

391 self._preferred_width_cache = None

392 self._content_height_cache = None

393 self._is_laid_out = False

395 def add_child(self, child: Renderable) -> 'DynamicPage':

396 """

397 Add a child and invalidate caches.

399 Args:

400 child: The renderable object to add

401

402 Returns:

403 Self for method chaining

404 """

405 super().add_child(child)

406 self.invalidate_caches()

407 return self

409 def clear_children(self) -> 'DynamicPage':

410 """

411 Remove all children and invalidate caches.

412

413 Returns:

414 Self for method chaining

415 """

416 super().clear_children()

417 self.invalidate_caches()

418 return self

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_functional_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_functional_py.html new file mode 100644 index 0000000..6b259f3 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_functional_py.html @@ -0,0 +1,623 @@ + + + + + Coverage for pyWebLayout/concrete/functional.py: 89% + + + + + +

+ Coverage for pyWebLayout/concrete/functional.py: + 89% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 190 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

2from typing import Optional, Tuple

3import numpy as np

4from PIL import ImageDraw

6from pyWebLayout.core.base import Interactable, Queriable

7from pyWebLayout.abstract.functional import Link, Button, FormField, LinkType, FormFieldType

8from pyWebLayout.style import Font, TextDecoration

9from .text import Text

12class LinkText(Text, Interactable, Queriable):

13 """

14 A Text subclass that can handle Link interactions.

15 Combines text rendering with clickable link functionality.

16 """

18 def __init__(self, link: Link, text: str, font: Font, draw: ImageDraw.Draw,

19 source=None, line=None, page=None):

20 """

21 Initialize a linkable text object.

23 Args:

24 link: The abstract Link object to handle interactions

25 text: The text content to render

26 font: The base font style

27 draw: The drawing context

28 source: Optional source object

29 line: Optional line container

30 page: Optional parent page (for dirty flag management)

31 """

32 # Create link-styled font (underlined and colored based on link type)

33 link_font = font.with_decoration(TextDecoration.UNDERLINE)

34 if link.link_type == LinkType.INTERNAL:

35 link_font = link_font.with_colour((0, 0, 200)) # Blue for internal links

36 elif link.link_type == LinkType.EXTERNAL:

37 link_font = link_font.with_colour(

38 (0, 0, 180)) # Darker blue for external links

39 elif link.link_type == LinkType.API:

40 link_font = link_font.with_colour((150, 0, 0)) # Red for API links

41 elif link.link_type == LinkType.FUNCTION: 41 ↛ 45line 41 didn't jump to line 45 because the condition on line 41 was always true

42 link_font = link_font.with_colour((0, 120, 0)) # Green for function links

44 # Initialize Text with the styled font

45 Text.__init__(self, text, link_font, draw, source, line)

47 # Initialize Interactable with the link's execute method

48 Interactable.__init__(self, link.execute)

50 # Store the link object and page reference

51 self._link = link

52 self._page = page

53 self._hovered = False

54 self._pressed = False

56 # Ensure _origin is initialized as numpy array

57 if not hasattr(self, '_origin') or self._origin is None: 57 ↛ 58line 57 didn't jump to line 58 because the condition on line 57 was never true

58 self._origin = np.array([0, 0])

60 @property

61 def link(self) -> Link:

62 """Get the associated Link object"""

63 return self._link

65 def set_hovered(self, hovered: bool):

66 """Set the hover state for visual feedback"""

67 self._hovered = hovered

68 self._mark_page_dirty()

70 def set_pressed(self, pressed: bool):

71 """Set the pressed state for visual feedback"""

72 self._pressed = pressed

73 self._mark_page_dirty()

75 def _mark_page_dirty(self):

76 """Mark the parent page as dirty if available"""

77 if self._page and hasattr(self._page, 'mark_dirty'): 77 ↛ 78line 77 didn't jump to line 78 because the condition on line 77 was never true

78 self._page.mark_dirty()

80 def render(self, next_text: Optional['Text'] = None, spacing: int = 0):

81 """

82 Render the link text with optional hover and pressed effects.

84 Args:

85 next_text: The next Text object in the line (if any)

86 spacing: The spacing to the next text object

87 """

88 # Handle mock objects in tests

89 size = self.size

90 if hasattr(size, '__call__'): # It's a Mock 90 ↛ 92line 90 didn't jump to line 92 because the condition on line 90 was never true

91 # Use default size for tests

92 size = np.array([100, 20])

93 else:

94 size = np.array(size)

96 # Ensure origin is a numpy array

97 origin = np.array(

98 self._origin) if not isinstance(

99 self._origin,

100 np.ndarray) else self._origin

101

102 # Draw background based on state (before text is rendered).

103 # PIL wants a flat sequence of four scalars; handing it a list of two

104 # numpy arrays raises "coordinate list must contain exactly 2

105 # coordinates".

106 if self._pressed or self._hovered:

107 far = origin + size

108 box = (int(origin[0]), int(origin[1]), int(far[0]), int(far[1]))

109 if self._pressed:

110 # Pressed state - stronger, darker highlight

111 bg_color = (180, 180, 255, 180)

112 else:

113 # Hover state - subtle highlight

114 bg_color = (220, 220, 255, 100)

115 self._draw.rectangle(box, fill=bg_color)

117 # Call the parent Text render method with parameters

118 super().render(next_text, spacing)

119

121class ButtonText(Text, Interactable, Queriable):

122 """

123 A Text subclass that can handle Button interactions.

124 Renders text as a clickable button with visual states.

125 """

127 def __init__(self, button: Button, font: Font, draw: ImageDraw.Draw,

128 padding: Tuple[int, int, int, int] = (4, 8, 4, 8),

129 source=None, line=None, page=None):

130 """

131 Initialize a button text object.

133 Args:

134 button: The abstract Button object to handle interactions

135 font: The base font style

136 draw: The drawing context

137 padding: Padding around the button text (top, right, bottom, left)

138 source: Optional source object

139 line: Optional line container

140 page: Optional parent page (for dirty flag management)

141 """

142 # Initialize Text with the button label

143 Text.__init__(self, button.label, font, draw, source, line)

145 # Initialize Interactable with the button's execute method

146 Interactable.__init__(self, button.execute)

148 # Store button properties

149 self._button = button

150 self._padding = padding

151 self._page = page

152 self._pressed = False

153 self._hovered = False

155 # Recalculate dimensions to include padding

156 # Use getattr to handle mock objects in tests

157 text_width = getattr(

158 self, '_width', 0) if not hasattr(

159 self._width, '__call__') else 0

160 self._padded_width = text_width + padding[1] + padding[3]

162 # Size the button from the text's visual height (ascent + descent), not

163 # from the nominal font size. The two differ by several pixels - DejaVu at

164 # 14px measures 17 - so sizing by font_size leaves the button too short to

165 # centre its own label in.

166 self._text_height = self._visual_text_height()

167 self._padded_height = self._text_height + padding[0] + padding[2]

169 def _visual_text_height(self) -> int:

170 """Height of the rendered text, ascender to descender."""

171 try:

172 ascent, descent = self._style.font.getmetrics()

173 return int(ascent + descent)

174 except (AttributeError, TypeError, ValueError):

175 # Mock or unusual font object; the nominal size is the best guess.

176 return int(getattr(self._style, 'font_size', 0) or 0)

178 @property

179 def button(self) -> Button:

180 """Get the associated Button object"""

181 return self._button

183 @property

184 def size(self) -> np.ndarray:

185 """Get the padded size of the button"""

186 return np.array([self._padded_width, self._padded_height])

188 def set_pressed(self, pressed: bool):

189 """Set the pressed state"""

190 self._pressed = pressed

191 self._mark_page_dirty()

193 def set_hovered(self, hovered: bool):

194 """Set the hover state"""

195 self._hovered = hovered

196 self._mark_page_dirty()

198 def set_page(self, page):

199 """

200 Set the parent page reference for dirty flag management.

202 Args:

203 page: The Page object containing this element

204 """

205 self._page = page

207 def _mark_page_dirty(self):

208 """Mark the parent page as dirty if available"""

209 if self._page and hasattr(self._page, 'mark_dirty'): 209 ↛ 210line 209 didn't jump to line 210 because the condition on line 209 was never true

210 self._page.mark_dirty()

212 def render(self):

213 """

214 Render the button with background, border, and text.

215 """

216 # Determine button colors based on state

217 if not self._button.enabled:

218 # Disabled button

219 bg_color = (200, 200, 200)

220 border_color = (150, 150, 150)

221 text_color = (100, 100, 100)

222 elif self._pressed: 222 ↛ 224line 222 didn't jump to line 224 because the condition on line 222 was never true

223 # Pressed button

224 bg_color = (70, 130, 180)

225 border_color = (50, 100, 150)

226 text_color = (255, 255, 255)

227 elif self._hovered: 227 ↛ 229line 227 didn't jump to line 229 because the condition on line 227 was never true

228 # Hovered button

229 bg_color = (100, 160, 220)

230 border_color = (70, 130, 180)

231 text_color = (255, 255, 255)

232 else:

233 # Normal button

234 bg_color = (100, 150, 200)

235 border_color = (70, 120, 170)

236 text_color = (255, 255, 255)

238 # Draw button background with rounded corners

239 # rounded_rectangle expects [x0, y0, x1, y1] format

240 button_rect = [

241 int(self._origin[0]),

242 int(self._origin[1]),

243 int(self._origin[0] + self.size[0]),

244 int(self._origin[1] + self.size[1])

245 ]

246 self._draw.rounded_rectangle(button_rect, fill=bg_color,

247 outline=border_color, width=1, radius=4)

249 # Update text color and render text centered within padding

250 self._style = self._style.with_colour(text_color)

251 text_x = self._origin[0] + self._padding[3] # left padding

253 # Center text vertically within button

254 # Get font metrics to properly center the baseline

255 ascent, descent = self._style.font.getmetrics()

257 # Total button height minus top and bottom padding gives us text area height

258 text_area_height = self._padded_height - self._padding[0] - self._padding[2]

259

260 # Centre the text's visual height (ascent + descent) within the text area.

261 # text_y is the baseline, since Text renders with anchor "ls".

262 #

263 # top of glyphs = area_top + (area_height - (ascent + descent)) / 2

264 # baseline = top of glyphs + ascent

265 #

266 # The previous form, area_top + area_height/2 + descent/2, is only

267 # equivalent when ascent == 2 * descent. Real fonts sit nearer 4:1, so the

268 # label rendered several pixels above centre, against the top edge.

269 text_top = self._origin[1] + self._padding[0] \

270 + (text_area_height - (ascent + descent)) / 2

271 text_y = text_top + ascent

273 # Temporarily set origin for text rendering

274 original_origin = self._origin.copy()

275 self._origin = np.array([text_x, text_y])

277 # Call parent render method for the text

278 super().render()

280 # Restore original origin

281 self._origin = original_origin

282

283 def in_object(self, point) -> bool:

284 """

285 Check if a point is within this button.

287 Args:

288 point: The coordinates to check

290 Returns:

291 True if the point is within the button bounds (including padding)

292 """

293 point_array = np.array(point)

294 relative_point = point_array - self._origin

295

296 # Check if the point is within the padded button boundaries

297 return (0 <= relative_point[0] < self._padded_width and

298 0 <= relative_point[1] < self._padded_height)

301class FormFieldText(Text, Interactable, Queriable):

302 """

303 A Text subclass that can handle FormField interactions.

304 Renders form field labels and input areas.

306 The origin is the top-left of the whole control: label, then a gap, then the

307 input box. Text itself draws from a baseline, so the label is offset down by

308 its ascent when rendering; without that the glyphs would sit above the origin

309 and overprint whatever is above, which for a stacked form is the previous

310 field's input box.

311 """

313 # Vertical gap between the label and its input box, in pixels.

314 LABEL_GAP = 5

316 def __init__(self, field: FormField, font: Font, draw: ImageDraw.Draw,

317 field_height: int = 24, source=None, line=None):

318 """

319 Initialize a form field text object.

321 Args:

322 field: The abstract FormField object to handle interactions

323 font: The base font style for the label

324 draw: The drawing context

325 field_height: Height of the input field area

326 source: Optional source object

327 line: Optional line container

328 """

329 # Initialize Text with the field label

330 Text.__init__(self, field.label, font, draw, source, line)

332 # Initialize Interactable - form fields don't have direct callbacks

333 # but can notify of focus/value changes

334 Interactable.__init__(self, None)

336 # Store field properties

337 self._field = field

338 self._field_height = field_height

339 self._focused = False

341 # Calculate total height (label + gap + field). The label's height is its

342 # ink height, ascender to descender, not the nominal font size - the two

343 # differ by several pixels and the gap between label and box is only 5.

344 self._label_height = self._visual_label_height()

345 self._total_height = self._label_height + self.LABEL_GAP + field_height

347 # Field width should be at least as wide as the label

348 # Use getattr to handle mock objects in tests

349 text_width = getattr(

350 self, '_width', 0) if not hasattr(

351 self._width, '__call__') else 0

352 self._field_width = max(text_width, 150)

353

354 def _visual_label_height(self) -> int:

355 """Height of the rendered label, ascender to descender."""

356 try:

357 ascent, descent = self._style.font.getmetrics()

358 return int(ascent + descent)

359 except (AttributeError, TypeError, ValueError):

360 # Mock or unusual font object; the nominal size is the best guess.

361 return int(getattr(self._style, 'font_size', 0) or 0)

363 @property

364 def field_area_offset(self) -> int:

365 """Distance from this control's origin to the top of its input box."""

366 return self._label_height + self.LABEL_GAP

368 @property

369 def field(self) -> FormField:

370 """Get the associated FormField object"""

371 return self._field

373 @property

374 def size(self) -> np.ndarray:

375 """Get the total size including label and field"""

376 return np.array([self._field_width, self._total_height])

378 def set_focused(self, focused: bool):

379 """Set the focus state"""

380 self._focused = focused

381

382 def render(self):

383 """

384 Render the form field with label and input area.

385 """

386 # Render the label. Text draws from the baseline, so shift down by the

387 # ascent to make the origin the top of the label rather than its baseline.

388 try:

389 label_ascent = self._style.font.getmetrics()[0]

390 except (AttributeError, TypeError, ValueError):

391 label_ascent = self._label_height

393 label_origin = self._origin

394 self._origin = np.array([label_origin[0], label_origin[1] + label_ascent])

395 super().render()

396 self._origin = label_origin

398 # Calculate field position (below the label, with the standard gap)

399 field_x = self._origin[0]

400 field_y = self._origin[1] + self.field_area_offset

401

402 # Draw field background and border

403 bg_color = (255, 255, 255)

404 border_color = (100, 150, 200) if self._focused else (200, 200, 200)

405

406 field_rect = [(field_x, field_y),

407 (field_x + self._field_width, field_y + self._field_height)]

408 self._draw.rectangle(field_rect, fill=bg_color, outline=border_color, width=1)

410 # Render field value if present

411 if self._field.value is not None:

412 value_text = str(self._field.value)

414 # For password fields, mask the text

415 if self._field.field_type == FormFieldType.PASSWORD:

416 value_text = "•" * len(value_text)

418 # Create a temporary Text object for the value

419 value_font = self._style.with_colour((0, 0, 0))

420

421 # Position value text within field (with some padding)

422 # Get font metrics to properly center the baseline

423 ascent, descent = value_font.font.getmetrics()

425 # Centre the value within the input box. As in ButtonText, the

426 # baseline sits at the top of the glyphs plus the ascent; centring on

427 # half the box height plus half the descent only works for a 2:1

428 # ascent/descent ratio and otherwise rides high.

429 value_x = field_x + 5

430 value_y = field_y + (self._field_height - (ascent + descent)) / 2 + ascent

432 # Draw the value text

433 self._draw.text((value_x, value_y), value_text,

434 font=value_font.font, fill=value_font.colour, anchor="ls")

436 def handle_click(self, point) -> bool:

437 """

438 Handle clicks on the form field.

439

440 Args:

441 point: The click coordinates relative to this field

442

443 Returns:

444 True if the field was clicked and focused

445 """

446 # Calculate field area

447 field_y = self.field_area_offset

448

449 # Check if click is within the input field area (not just the label)

450 if (0 <= point[0] <= self._field_width and

451 field_y <= point[1] <= field_y + self._field_height):

452 self.set_focused(True)

453 return True

454

455 return False

457 def in_object(self, point) -> bool:

458 """

459 Check if a point is within this form field (including label and input area).

461 Args:

462 point: The coordinates to check

464 Returns:

465 True if the point is within the field bounds

466 """

467 point_array = np.array(point)

468 relative_point = point_array - self._origin

469

470 # Check if the point is within the total field area

471 return (0 <= relative_point[0] < self._field_width and

472 0 <= relative_point[1] < self._total_height)

473

475# Factory functions for creating functional text objects

476def create_link_text(link: Link, text: str, font: Font,

477 draw: ImageDraw.Draw) -> LinkText:

478 """

479 Factory function to create a LinkText object.

481 Args:

482 link: The Link object to associate with the text

483 text: The text content to display

484 font: The base font style

485 draw: The drawing context

486

487 Returns:

488 A LinkText object ready for rendering and interaction

489 """

490 return LinkText(link, text, font, draw)

491

493def create_button_text(button: Button, font: Font, draw: ImageDraw.Draw,

494 padding: Tuple[int, int, int, int] = (4, 8, 4, 8)) -> ButtonText:

495 """

496 Factory function to create a ButtonText object.

497

498 Args:

499 button: The Button object to associate with the text

500 font: The base font style

501 draw: The drawing context

502 padding: Padding around the button text

504 Returns:

505 A ButtonText object ready for rendering and interaction

506 """

507 return ButtonText(button, font, draw, padding)

508

509

510def create_form_field_text(field: FormField, font: Font, draw: ImageDraw.Draw,

511 field_height: int = 24) -> FormFieldText:

512 """

513 Factory function to create a FormFieldText object.

514

515 Args:

516 field: The FormField object to associate with the text

517 font: The base font style for the label

518 draw: The drawing context

519 field_height: Height of the input field area

520

521 Returns:

522 A FormFieldText object ready for rendering and interaction

523 """

524 return FormFieldText(field, font, draw, field_height)

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_image_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_image_py.html new file mode 100644 index 0000000..be2f220 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_image_py.html @@ -0,0 +1,379 @@ + + + + + Coverage for pyWebLayout/concrete/image.py: 93% + + + + + +

+ Coverage for pyWebLayout/concrete/image.py: + 93% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 134 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1import os

2from typing import Optional

3import numpy as np

4from PIL import Image as PILImage, ImageDraw, ImageFont

5from pyWebLayout.core.base import Renderable, Queriable

6from pyWebLayout.abstract.block import Image as AbstractImage

7from pyWebLayout.style import Alignment

10class RenderableImage(Renderable, Queriable):

11 """

12 A concrete implementation for rendering Image objects.

13 """

15 def __init__(self, image: AbstractImage, canvas: PILImage.Image,

16 max_width: Optional[int] = None, max_height: Optional[int] = None,

17 origin=None, size=None, callback=None, sheet=None, mode=None,

18 halign=Alignment.CENTER, valign=Alignment.CENTER):

19 """

20 Initialize a renderable image.

22 Args:

23 image: The abstract Image object to render

24 draw: The PIL ImageDraw object to draw on

25 max_width: Maximum width constraint for the image

26 max_height: Maximum height constraint for the image

27 origin: Optional origin coordinates

28 size: Optional size override

29 callback: Optional callback function

30 sheet: Optional sheet for rendering

31 mode: Optional image mode

32 halign: Horizontal alignment

33 valign: Vertical alignment

34 """

35 super().__init__()

36 self._abstract_image = image

37 self._canvas = canvas

38 self._pil_image = None

39 self._error_message = None

40 self._halign = halign

41 self._valign = valign

43 # Set origin as numpy array

44 self._origin = np.array(origin) if origin is not None else np.array([0, 0])

46 # Try to load the image

47 self._load_image()

49 # Calculate the size if not provided

50 if size is None:

51 size = image.calculate_scaled_dimensions(max_width, max_height)

52 # Ensure we have valid dimensions, fallback to defaults if None

53 if size[0] is None or size[1] is None:

54 size = (100, 100) # Default size when image dimensions are unavailable

56 # Ensure dimensions are positive (can be negative if calculated from insufficient space)

57 size = (max(1, size[0]), max(1, size[1]))

59 # Set size as numpy array

60 self._size = np.array(size)

62 @property

63 def origin(self) -> np.ndarray:

64 """Get the origin of the image"""

65 return self._origin

67 @property

68 def size(self) -> np.ndarray:

69 """Get the size of the image"""

70 return self._size

72 @property

73 def width(self) -> int:

74 """Get the width of the image"""

75 return self._size[0]

77 def set_origin(self, origin: np.ndarray):

78 """Set the origin of this image element"""

79 self._origin = origin

81 def _load_image(self):

82 """Load the image from the source path"""

83 try:

84 # Check if the image has already been loaded into memory

85 if hasattr( 85 ↛ 88line 85 didn't jump to line 88 because the condition on line 85 was never true

86 self._abstract_image,

87 '_loaded_image') and self._abstract_image._loaded_image is not None:

88 self._pil_image = self._abstract_image._loaded_image

89 return

91 source = self._abstract_image.source

93 # Handle different types of sources

94 if os.path.isfile(source):

95 # Local file

96 self._pil_image = PILImage.open(source)

97 self._abstract_image._loaded_image = self._pil_image

98 elif source.startswith(('http://', 'https://')):

99 # URL - requires requests library

100 try:

101 import requests

102 from io import BytesIO

104 response = requests.get(source, stream=True)

105 if response.status_code == 200:

106 self._pil_image = PILImage.open(BytesIO(response.content))

107 self._abstract_image._loaded_image = self._pil_image

108 else:

109 self._error_message = f"Failed to load image: HTTP status {response.status_code}"

110 except ImportError:

111 self._error_message = "Requests library not available for URL loading"

112 else:

113 self._error_message = f"Unable to load image from source: {source}"

115 except Exception as e:

116 self._error_message = f"Error loading image: {str(e)}"

117 self._abstract_image._error = self._error_message

118

119 def render(self):

120 """

121 Render the image directly into the canvas using the provided draw object.

122 """

123 if self._pil_image:

124 # Resize the image to fit the box while maintaining aspect ratio

125 resized_image = self._resize_image()

127 # Calculate position based on alignment

128 img_width, img_height = resized_image.size

129 box_width, box_height = self._size

131 # Horizontal alignment

132 if self._halign == Alignment.LEFT:

133 x_offset = 0

134 elif self._halign == Alignment.RIGHT:

135 x_offset = box_width - img_width

136 else: # CENTER is default

137 x_offset = (box_width - img_width) // 2

139 # Vertical alignment

140 if self._valign == Alignment.TOP:

141 y_offset = 0

142 elif self._valign == Alignment.BOTTOM:

143 y_offset = box_height - img_height

144 else: # CENTER is default

145 y_offset = (box_height - img_height) // 2

147 # Calculate final position on canvas

148 final_x = int(self._origin[0] + x_offset)

149 final_y = int(self._origin[1] + y_offset)

151 # Get the underlying image from the draw object to paste onto

153 self._canvas.paste(

154 resized_image,

155 (final_x,

156 final_y,

157 final_x +

158 img_width,

159 final_y +

160 img_height))

161 else:

162 # Draw error placeholder

163 self._draw_error_placeholder()

165 def _resize_image(self) -> PILImage.Image:

166 """

167 Resize the image to fit within the box while maintaining aspect ratio.

169 Returns:

170 A resized PIL Image

171 """

172 if not self._pil_image:

173 return PILImage.new('RGBA', tuple(self._size), (200, 200, 200, 100))

175 # Get the target dimensions

176 target_width, target_height = self._size

178 # Ensure target dimensions are positive

179 target_width = max(1, int(target_width))

180 target_height = max(1, int(target_height))

182 # Get the original dimensions

183 orig_width, orig_height = self._pil_image.size

185 # Calculate the scaling factor to maintain aspect ratio

186 width_ratio = target_width / orig_width

187 height_ratio = target_height / orig_height

189 # Use the smaller ratio to ensure the image fits within the box

190 ratio = min(width_ratio, height_ratio)

192 # Calculate new dimensions

193 new_width = max(1, int(orig_width * ratio))

194 new_height = max(1, int(orig_height * ratio))

196 # Resize the image

197 if self._pil_image.mode == 'RGBA': 197 ↛ 198line 197 didn't jump to line 198 because the condition on line 197 was never true

198 resized = self._pil_image.resize((new_width, new_height), PILImage.LANCZOS)

199 else:

200 # Convert to RGBA if needed

201 resized = self._pil_image.convert('RGBA').resize(

202 (new_width, new_height), PILImage.LANCZOS)

203

204 return resized

205

206 def _draw_error_placeholder(self):

207 """

208 Draw a placeholder for when the image can't be loaded.

209 """

210 # Calculate the rectangle coordinates with origin offset

211 x1 = int(self._origin[0])

212 y1 = int(self._origin[1])

213 x2 = int(self._origin[0] + self._size[0])

214 y2 = int(self._origin[1] + self._size[1])

216 self._draw = ImageDraw.Draw(self._canvas)

217 # Draw a gray box with a border

218 self._draw.rectangle([(x1, y1), (x2, y2)], fill=(

219 240, 240, 240), outline=(180, 180, 180), width=2)

221 # Draw an X across the box

222 self._draw.line([(x1, y1), (x2, y2)], fill=(180, 180, 180), width=2)

223 self._draw.line([(x1, y2), (x2, y1)], fill=(180, 180, 180), width=2)

224

225 # Add error text if available

226 if self._error_message: 226 ↛ exitline 226 didn't return from function '_draw_error_placeholder' because the condition on line 226 was always true

227 try:

228 # Try to use a basic font

229 font = ImageFont.load_default()

230

231 # Draw the error message, wrapped to fit

232 error_text = "Error: " + self._error_message

234 # Simple text wrapping - split by words and add lines

235 words = error_text.split()

236 lines = []

237 current_line = ""

239 for word in words:

240 test_line = current_line + " " + word if current_line else word

241 text_bbox = self._draw.textbbox((0, 0), test_line, font=font)

242 text_width = text_bbox[2] - text_bbox[0]

244 if text_width <= self._size[0] - 20: # 10px padding on each side

245 current_line = test_line

246 else:

247 lines.append(current_line)

248 current_line = word

250 if current_line: 250 ↛ 254line 250 didn't jump to line 254 because the condition on line 250 was always true

251 lines.append(current_line)

253 # Draw each line

254 y_pos = y1 + 10

255 for line in lines:

256 text_bbox = self._draw.textbbox((0, 0), line, font=font)

257 text_width = text_bbox[2] - text_bbox[0]

258 text_height = text_bbox[3] - text_bbox[1]

259

260 # Center the text horizontally

261 x_pos = x1 + (self._size[0] - text_width) // 2

262

263 # Draw the text

264 self._draw.text((x_pos, y_pos), line, fill=(80, 80, 80), font=font)

265

266 # Move to the next line

267 y_pos += text_height + 2

269 except Exception:

270 # If text rendering fails, just draw a generic error indicator

271 pass

273 def in_object(self, point):

274 """Check if a point is within this image"""

275 point_array = np.array(point)

276 relative_point = point_array - self._origin

278 # Check if the point is within the image boundaries

279 return (0 <= relative_point[0] < self._size[0] and

280 0 <= relative_point[1] < self._size[1])

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_interaction_handler_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_interaction_handler_py.html new file mode 100644 index 0000000..7af4705 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_interaction_handler_py.html @@ -0,0 +1,409 @@ + + + + + Coverage for pyWebLayout/concrete/interaction_handler.py: 55% + + + + + +

+ Coverage for pyWebLayout/concrete/interaction_handler.py: + 55% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 99 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Interaction handler for managing button/link press-release lifecycle with visual feedback.

4This module provides utilities for handling interactive element states and rendering

5frames at different stages of interaction (pressed, released).

6"""

8from typing import Optional, Tuple, Callable, Any

9from PIL import Image

10import time

11import numpy as np

13from pyWebLayout.concrete.functional import LinkText, ButtonText

14from pyWebLayout.concrete.page import Page

17class InteractionHandler:

18 """

19 Manages the press-release lifecycle for interactive elements.

21 This class handles the timing and state management needed to show

22 visual feedback when buttons or links are clicked. It can generate

23 multiple rendered frames showing the pressed and released states.

25 Usage patterns:

27 Pattern A - Simple one-shot with automatic frames:

28 handler = InteractionHandler(page)

29 frames = handler.execute_with_feedback(button_element, point)

30 # Returns: [pressed_frame, released_frame]

31 # Show frames in sequence with brief delay

33 Pattern B - Manual state management for custom event loops:

34 handler = InteractionHandler(page)

35 handler.set_pressed_state(button_element, True)

36 pressed_frame = handler.render_current_state()

37 # ... show frame, wait, execute action ...

38 handler.set_pressed_state(button_element, False)

39 released_frame = handler.render_current_state()

40 """

42 def __init__(self, page: Page, press_duration_ms: int = 150):

43 """

44 Initialize the interaction handler.

46 Args:

47 page: The Page object containing the interactive elements

48 press_duration_ms: How long to show the pressed state (default: 150ms)

49 """

50 self._page = page

51 self._press_duration_ms = press_duration_ms

53 def set_pressed_state(self, element, pressed: bool):

54 """

55 Set the pressed state of an interactive element.

57 Args:

58 element: A LinkText or ButtonText object

59 pressed: True to show pressed, False to show released

60 """

61 if isinstance(element, (LinkText, ButtonText)):

62 # Ensure element has page reference for dirty flag

63 if not hasattr(element, '_page') or element._page is None:

64 element.set_page(self._page)

65 element.set_pressed(pressed)

66 else:

67 raise TypeError(

68 f"Element must be LinkText or ButtonText, got {type(element)}")

70 def set_hovered_state(self, element, hovered: bool):

71 """

72 Set the hovered state of an interactive element.

74 Args:

75 element: A LinkText or ButtonText object

76 hovered: True to show hovered, False for normal

77 """

78 if isinstance(element, (LinkText, ButtonText)):

79 # Ensure element has page reference for dirty flag

80 if not hasattr(element, '_page') or element._page is None:

81 element.set_page(self._page)

82 element.set_hovered(hovered)

83 else:

84 raise TypeError(

85 f"Element must be LinkText or ButtonText, got {type(element)}")

87 def render_current_state(self) -> Image.Image:

88 """

89 Render the page with current element states.

91 Returns:

92 PIL Image of the rendered page

93 """

94 return self._page.render()

96 def execute_with_feedback(

97 self,

98 element,

99 point: Optional[np.ndarray] = None,

100 callback: Optional[Callable] = None) -> Tuple[Image.Image, Image.Image, Any]:

101 """

102 Execute an interaction with visual feedback at each stage.

104 This is the high-level "all-in-one" method that:

105 1. Sets pressed state and renders

106 2. Waits for press_duration_ms

107 3. Executes the element's callback (or provided callback)

108 4. Sets released state and renders

110 Args:

111 element: A LinkText or ButtonText object

112 point: Optional point where interaction occurred

113 callback: Optional custom callback (overrides element's callback)

115 Returns:

116 Tuple of (pressed_frame, released_frame, callback_result)

117 """

118 # Step 1: Render pressed state

119 self.set_pressed_state(element, True)

120 pressed_frame = self.render_current_state()

122 # Step 2: Wait for visual feedback duration

123 time.sleep(self._press_duration_ms / 1000.0)

125 # Step 3: Execute callback

126 callback_result = None

127 if callback:

128 callback_result = callback(point) if point is not None else callback()

129 elif hasattr(element, 'interact'):

130 callback_result = element.interact(point)

131

132 # Step 4: Render released state

133 self.set_pressed_state(element, False)

134 released_frame = self.render_current_state()

136 return pressed_frame, released_frame, callback_result

138 def execute_async_with_feedback(

139 self,

140 element,

141 point: Optional[np.ndarray] = None) -> Tuple[Image.Image, Callable, Image.Image]:

142 """

143 Execute an interaction with visual feedback, returning frames immediately

144 without blocking.

146 This method returns the frames and a callback to execute later, allowing

147 the caller to control when the action actually happens.

148

149 Args:

150 element: A LinkText or ButtonText object

151 point: Optional point where interaction occurred

153 Returns:

154 Tuple of (pressed_frame, execute_callback, released_frame)

155 where execute_callback is a function that will execute the interaction

156 """

157 # Render pressed state

158 self.set_pressed_state(element, True)

159 pressed_frame = self.render_current_state()

161 # Create callback that will execute the interaction and reset state

162 def execute_callback():

163 result = None

164 if hasattr(element, 'interact'):

165 result = element.interact(point)

166 self.set_pressed_state(element, False)

167 return result

169 # Pre-render the released state (element state is still pressed)

170 # We'll return this frame but the caller controls when to show it

171 self.set_pressed_state(element, False)

172 released_frame = self.render_current_state()

174 # Reset back to pressed for consistency

175 # (caller will call execute_callback which sets to False)

176 self.set_pressed_state(element, True)

178 return pressed_frame, execute_callback, released_frame

179

181class InteractionStateManager:

182 """

183 Manages interaction states for multiple elements on a page.

185 Useful for applications that need to track hover/press states

186 across many interactive elements simultaneously.

187 """

189 def __init__(self, page: Page):

190 """

191 Initialize the state manager.

193 Args:

194 page: The Page object containing interactive elements

195 """

196 self._page = page

197 self._hovered_element = None

198 self._pressed_element = None

200 def update_hover(self, point: Tuple[int, int]) -> Optional[Image.Image]:

201 """

202 Update hover state based on cursor position.

203

204 Queries the page to find what's under the cursor and updates

205 hover states accordingly.

207 Args:

208 point: Cursor position (x, y)

209

210 Returns:

211 New rendered frame if hover state changed, None otherwise

212 """

213 # Query what's at this point

214 result = self._page.query_point(point)

216 if not result or not result.is_interactive:

217 # Nothing interactive under cursor

218 if self._hovered_element: 218 ↛ 224line 218 didn't jump to line 224 because the condition on line 218 was always true

219 # Clear previous hover

220 if isinstance(self._hovered_element, (LinkText, ButtonText)): 220 ↛ 222line 220 didn't jump to line 222 because the condition on line 220 was always true

221 self._hovered_element.set_hovered(False)

222 self._hovered_element = None

223 return self._page.render()

224 return None

226 # Something interactive is under cursor

227 element = result.object

228 if element != self._hovered_element:

229 # Hover changed

230 # Clear old hover

231 if self._hovered_element and isinstance( 231 ↛ 233line 231 didn't jump to line 233 because the condition on line 231 was never true

232 self._hovered_element, (LinkText, ButtonText)):

233 self._hovered_element.set_hovered(False)

234

235 # Set new hover

236 if isinstance(element, (LinkText, ButtonText)): 236 ↛ 239line 236 didn't jump to line 239 because the condition on line 236 was always true

237 element.set_hovered(True)

239 self._hovered_element = element

240 return self._page.render()

241

242 return None

244 def handle_mouse_down(self, point: Tuple[int, int]) -> Optional[Image.Image]:

245 """

246 Handle mouse button press at a point.

247

248 Args:

249 point: Click position (x, y)

251 Returns:

252 New rendered frame showing pressed state, or None if nothing interactive

253 """

254 result = self._page.query_point(point)

256 if not result or not result.is_interactive:

257 return None

259 element = result.object

260 if isinstance(element, (LinkText, ButtonText)): 260 ↛ 265line 260 didn't jump to line 265 because the condition on line 260 was always true

261 element.set_pressed(True)

262 self._pressed_element = element

263 return self._page.render()

265 return None

266

267 def handle_mouse_up(

268 self,

269 point: Tuple[int,

270 int]) -> Tuple[Optional[Image.Image],

271 Any]:

272 """

273 Handle mouse button release at a point.

275 Args:

276 point: Release position (x, y)

278 Returns:

279 Tuple of (rendered_frame, callback_result)

280 Frame shows released state, result is from executing the callback

281 """

282 if not self._pressed_element:

283 return None, None

285 # Execute the interaction

286 callback_result = None

287 if hasattr(self._pressed_element, 'interact'): 287 ↛ 292line 287 didn't jump to line 292 because the condition on line 287 was always true

288 callback_result = self._pressed_element.interact(

289 np.array(point))

290

291 # Release the pressed state

292 if isinstance(self._pressed_element, (LinkText, ButtonText)): 292 ↛ 295line 292 didn't jump to line 295 because the condition on line 292 was always true

293 self._pressed_element.set_pressed(False)

295 self._pressed_element = None

297 return self._page.render(), callback_result

299 def reset(self):

300 """Reset all interaction states."""

301 if self._hovered_element and isinstance( 301 ↛ 303line 301 didn't jump to line 303 because the condition on line 301 was never true

302 self._hovered_element, (LinkText, ButtonText)):

303 self._hovered_element.set_hovered(False)

304

305 if self._pressed_element and isinstance(

306 self._pressed_element, (LinkText, ButtonText)):

307 self._pressed_element.set_pressed(False)

309 self._hovered_element = None

310 self._pressed_element = None

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_page_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_page_py.html new file mode 100644 index 0000000..0fc82fe --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_page_py.html @@ -0,0 +1,566 @@ + + + + + Coverage for pyWebLayout/concrete/page.py: 95% + + + + + +

+ Coverage for pyWebLayout/concrete/page.py: + 95% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 176 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from typing import List, Tuple, Optional

2import numpy as np

3from PIL import Image, ImageDraw

5from pyWebLayout.core.base import Renderable, Queriable

6from pyWebLayout.core.query import QueryResult, SelectionRange

7from pyWebLayout.core.callback_registry import CallbackRegistry

8from pyWebLayout.style.page_style import PageStyle

11class Page(Renderable, Queriable):

12 """

13 A page represents a canvas that can hold and render child renderable objects.

14 It handles layout, rendering, and provides query capabilities to find which child

15 contains a given point.

16 """

18 # Mode of the render canvas. The measurement context matches it so that text

19 # width caching keys stay consistent between layout and rendering.

20 _CANVAS_MODE = 'RGBA'

22 def __init__(self, size: Tuple[int, int], style: Optional[PageStyle] = None,

23 origin: Tuple[int, int] = (0, 0)):

24 """

25 Initialize a new page.

27 Args:

28 size: The total size of the page (width, height) including borders

29 style: The PageStyle defining borders, spacing, and appearance

30 origin: Absolute position of the page's top-left corner. Non-zero for

31 a page nested inside another surface, such as a table cell.

32 """

33 self._size = size

34 self._origin = origin

35 self._style = style if style is not None else PageStyle()

36 self._children: List[Renderable] = []

37 self._canvas: Optional[Image.Image] = None

38 self._draw: Optional[ImageDraw.Draw] = None

39 self._measurement_draw: Optional[ImageDraw.ImageDraw] = None

40 # Initialize y_offset to start of content area

41 # Position the first line so its baseline is close to the top boundary

42 # For subsequent lines, baseline-to-baseline spacing is used

43 self._current_y_offset = (self._origin[1] + self._style.border_width

44 + self._style.padding_top)

45 self._is_first_line = True # Track if we're placing the first line

46 # Callback registry for managing interactable elements

47 self._callbacks = CallbackRegistry()

48 # Dirty flag to track if page needs re-rendering due to state changes

49 self._dirty = True

51 def free_space(self) -> Tuple[int, int]:

52 """

53 Get the remaining space in the content area.

55 Deprecated: use content_rect and remaining_height, which this delegates to.

56 """

57 return (self.content_rect[2], self.remaining_height)

59 def can_fit_line(

60 self,

61 baseline_spacing: int,

62 ascent: int = 0,

63 descent: int = 0) -> bool:

64 """

65 Check if a line with the given metrics can fit on the page.

67 Args:

68 baseline_spacing: Distance from current position to next baseline

69 ascent: Font ascent (height above baseline), defaults to 0 for backward compat

70 descent: Font descent (height below baseline), defaults to 0 for backward compat

72 Returns:

73 True if the line fits within page boundaries

74 """

75 # Calculate the maximum Y position allowed (bottom boundary)

76 content_y, content_h = self.content_rect[1], self.content_rect[3]

77 max_y = content_y + content_h

79 # If ascent/descent not provided, use simple check (backward compatibility)

80 if ascent == 0 and descent == 0:

81 return (self._current_y_offset + baseline_spacing) <= max_y

83 # Calculate where the bottom of the text would be

84 # Text bottom = current_y_offset + ascent + descent

85 text_bottom = self._current_y_offset + ascent + descent

87 # Check if text bottom would exceed the boundary

88 return text_bottom <= max_y

90 @property

91 def size(self) -> Tuple[int, int]:

92 """Get the total page size including borders"""

93 return self._size

95 @property

96 def origin(self) -> Tuple[int, int]:

97 """Absolute position of the page's top-left corner"""

98 return self._origin

100 @property

101 def content_origin(self) -> Tuple[int, int]:

102 """

103 Absolute top-left of the content box: the page origin plus its border and

104 top/left padding. Layout starts here.

105 """

106 return (

107 self._origin[0] + self._style.border_width + self._style.padding_left,

108 self._origin[1] + self._style.border_width + self._style.padding_top,

109 )

111 @property

112 def content_rect(self) -> Tuple[int, int, int, int]:

113 """(x, y, width, height) of the content box, in absolute coordinates"""

114 x, y = self.content_origin

115 return (x, y, self.content_size[0], self.content_size[1])

117 @property

118 def remaining_height(self) -> int:

119 """Content-box height still available below the current layout cursor"""

120 _, y, _, h = self.content_rect

121 return max(0, y + h - self._current_y_offset)

123 @property

124 def canvas_size(self) -> Tuple[int, int]:

125 """Get the canvas size (page size minus borders)"""

126 border_reduction = self._style.total_border_width

127 return (

128 self._size[0] - border_reduction,

129 self._size[1] - border_reduction

130 )

131

132 @property

133 def content_size(self) -> Tuple[int, int]:

134 """Get the content area size (canvas minus padding)"""

135 canvas_w, canvas_h = self.canvas_size

136 return (

137 canvas_w - self._style.total_horizontal_padding,

138 canvas_h - self._style.total_vertical_padding

139 )

141 @property

142 def border_size(self) -> int:

143 """Get the border width"""

144 return self._style.border_width

146 @property

147 def available_width(self) -> int:

148 """Get the available width for content (content area width)"""

149 return self.content_size[0]

151 @property

152 def style(self) -> PageStyle:

153 """Get the page style"""

154 return self._style

156 @property

157 def callbacks(self) -> CallbackRegistry:

158 """Get the callback registry for managing interactable elements"""

159 return self._callbacks

161 @property

162 def is_dirty(self) -> bool:

163 """Check if the page needs re-rendering due to state changes"""

164 return self._dirty

166 def mark_dirty(self):

167 """Mark the page as needing re-rendering"""

168 self._dirty = True

170 def mark_clean(self):

171 """Mark the page as clean (up-to-date render)"""

172 self._dirty = False

174 @property

175 def draw(self) -> Optional[ImageDraw.Draw]:

176 """

177 Get the ImageDraw object bound to this page's render canvas.

179 Rebuilt whenever the canvas has been invalidated: a draw context

180 outlives the image it was created from, so checking only _draw would

181 hand back a context pointing at a discarded canvas.

182 """

183 if self._draw is None or self._canvas is None:

184 # Initialize canvas and draw context if not already done

185 self._canvas = self._create_canvas()

186 self._draw = ImageDraw.Draw(self._canvas)

187 return self._draw

189 @property

190 def measurement_draw(self) -> ImageDraw.ImageDraw:

191 """

192 A scratch draw context for text metrics during layout.

194 Layout asks for text widths constantly, but has no reason to touch the

195 render canvas - and the canvas is invalidated on every add_child, so

196 measuring through `draw` would allocate a full-page image per line.

197 This context is 1x1 and never invalidated.

199 Its mode matches the render canvas because Text keys its width cache on

200 the draw mode; a mismatch would double every cache entry. Children built

201 against it are re-bound to the real canvas by render_children.

202 """

203 if self._measurement_draw is None:

204 scratch = Image.new(self._CANVAS_MODE, (1, 1))

205 self._measurement_draw = ImageDraw.Draw(scratch)

206 return self._measurement_draw

208 def add_child(self, child: Renderable) -> 'Page':

209 """

210 Add a child renderable object to this page.

212 Args:

213 child: The renderable object to add

215 Returns:

216 Self for method chaining

217 """

218 self._children.append(child)

219 self._current_y_offset = child.origin[1] + child.size[1]

220 # Invalidate the canvas when children change

221 self._canvas = None

222 return self

223

224 def remove_child(self, child: Renderable) -> bool:

225 """

226 Remove a child from the page.

228 Args:

229 child: The child to remove

230

231 Returns:

232 True if the child was found and removed, False otherwise

233 """

234 try:

235 self._children.remove(child)

236 self._canvas = None

237 return True

238 except ValueError:

239 return False

241 def clear_children(self) -> 'Page':

242 """

243 Remove all children from the page.

245 Returns:

246 Self for method chaining

247 """

248 self._children.clear()

249 self._canvas = None

250 # Clear callback registry when clearing children

251 self._callbacks.clear()

252 # Reset y_offset to start of content area (after border and padding)

253 self._current_y_offset = self.content_origin[1]

254 return self

256 @property

257 def children(self) -> List[Renderable]:

258 """Get a copy of the children list"""

259 return self._children.copy()

260

261 def render_children(self):

262 """

263 Call render on all children in the list.

264 Children draw directly onto the page's canvas via the shared ImageDraw object.

265 """

266 for child in self._children:

267 # Synchronize draw context for Line objects before rendering

268 if hasattr(child, '_draw'):

269 child._draw = self._draw

270 # Synchronize canvas for Image objects before rendering

271 if hasattr(child, '_canvas'): 271 ↛ 272line 271 didn't jump to line 272 because the condition on line 271 was never true

272 child._canvas = self._canvas

273 if hasattr(child, 'render'): 273 ↛ 266line 273 didn't jump to line 266 because the condition on line 273 was always true

274 child.render()

276 def render(self) -> Image.Image:

277 """

278 Render the page with all its children.

280 Returns:

281 PIL Image containing the rendered page

282 """

283 # Create the base canvas and draw object

284 self._canvas = self._create_canvas()

285 self._draw = ImageDraw.Draw(self._canvas)

287 # Render all children - they draw directly onto the canvas

288 self.render_children()

290 # Mark as clean after rendering

291 self._dirty = False

293 return self._canvas

295 def _create_canvas(self) -> Image.Image:

296 """

297 Create the base canvas with background and borders.

299 Returns:

300 PIL Image with background and borders applied

301 """

302 # Create base image

303 canvas = Image.new(self._CANVAS_MODE, self._size, (*self._style.background_color, 255))

304

305 # Draw borders if needed

306 if self._style.border_width > 0:

307 draw = ImageDraw.Draw(canvas)

308 border_color = (*self._style.border_color, 255)

310 # Draw border rectangle inside the content area

311 border_offset = self._style.border_width

312 draw.rectangle([

313 (border_offset, border_offset),

314 (self._size[0] - border_offset - 1, self._size[1] - border_offset - 1)

315 ], outline=border_color)

317 return canvas

319 def query_point(self, point: Tuple[int, int]) -> Optional[QueryResult]:

320 """

321 Query a point to find the deepest object at that location.

322 Traverses children and uses Queriable.in_object() for hit-testing.

323

324 Args:

325 point: The (x, y) coordinates to query

327 Returns:

328 QueryResult with metadata about what was found, or None if nothing hit

329 """

330 point_array = np.array(point)

332 # Check each child (in reverse order so topmost child is found first)

333 for child in reversed(self._children):

334 # Use Queriable mixin's in_object() for hit-testing

335 if isinstance(child, Queriable) and child.in_object(point_array):

336 # If child can also query (has children of its own), recurse

337 if hasattr(child, 'query_point'):

338 result = child.query_point(point)

339 if result:

340 result.parent_page = self

341 return result

342 # If child's query returned None, continue to next child

343 continue

345 # Otherwise, package this child as the result

346 return self._make_query_result(child, point)

347

348 # Nothing hit - return empty result

349 return QueryResult(

350 object=self,

351 object_type="empty",

352 bounds=(int(point[0]), int(point[1]), 0, 0)

353 )

355 def _make_query_result(self, obj, point: Tuple[int, int]) -> QueryResult:

356 """

357 Package an object into a QueryResult with metadata.

359 Args:

360 obj: The object to package

361 point: The query point

363 Returns:

364 QueryResult with extracted metadata

365 """

366 from .text import Text

367 from .functional import LinkText, ButtonText

368

369 # Extract bounds

370 origin = getattr(obj, '_origin', np.array([0, 0]))

371 size = getattr(obj, 'size', np.array([0, 0]))

372 bounds = (

373 int(origin[0]),

374 int(origin[1]),

375 int(size[0]) if hasattr(size, '__getitem__') else 0,

376 int(size[1]) if hasattr(size, '__getitem__') else 0

377 )

379 # Determine type and extract metadata

380 if isinstance(obj, LinkText):

381 return QueryResult(

382 object=obj,

383 object_type="link",

384 bounds=bounds,

385 text=obj._text,

386 is_interactive=True,

387 link_target=obj._link.location if hasattr(obj, '_link') else None

388 )

389 elif isinstance(obj, ButtonText): 389 ↛ 390line 389 didn't jump to line 390 because the condition on line 389 was never true

390 return QueryResult(

391 object=obj,

392 object_type="button",

393 bounds=bounds,

394 text=obj._text,

395 is_interactive=True,

396 callback=obj._callback if hasattr(obj, '_callback') else None

397 )

398 elif isinstance(obj, Text):

399 return QueryResult(

400 object=obj,

401 object_type="text",

402 bounds=bounds,

403 text=obj._text if hasattr(obj, '_text') else None

404 )

405 else:

406 return QueryResult(

407 object=obj,

408 object_type="unknown",

409 bounds=bounds

410 )

411

412 def query_range(self, start: Tuple[int, int],

413 end: Tuple[int, int]) -> SelectionRange:

414 """

415 Query all text objects between two points (for text selection).

416 Uses Queriable.in_object() to determine which objects are in range.

418 Args:

419 start: Starting (x, y) point

420 end: Ending (x, y) point

421

422 Returns:

423 SelectionRange with all text objects between the points

424 """

425 results = []

426 in_selection = False

428 start_result = self.query_point(start)

429 end_result = self.query_point(end)

431 if not start_result or not end_result: 431 ↛ 432line 431 didn't jump to line 432 because the condition on line 431 was never true

432 return SelectionRange(start, end, [])

433

434 # Walk through all children (Lines) and their text objects

435 from .text import Line, Text

436

437 for child in self._children:

438 if isinstance(child, Line) and hasattr(child, '_text_objects'): 438 ↛ 437line 438 didn't jump to line 437 because the condition on line 438 was always true

439 for text_obj in child._text_objects:

440 # Check if this text is the start or is between start and end

441 if text_obj == start_result.object:

442 in_selection = True

443

444 if in_selection and isinstance(text_obj, Text):

445 result = self._make_query_result(text_obj, start)

446 results.append(result)

448 if text_obj == end_result.object:

449 in_selection = False

450 break

452 return SelectionRange(start, end, results)

453

454 def in_object(self, point: Tuple[int, int]) -> bool:

455 """

456 Check if a point is within this page's bounds.

457

458 Args:

459 point: The (x, y) coordinates to check

461 Returns:

462 True if the point is within the page bounds

463 """

464 return (

465 self._origin[0] <= point[0] < self._origin[0] + self._size[0] and

466 self._origin[1] <= point[1] < self._origin[1] + self._size[1]

467 )

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_table_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_table_py.html new file mode 100644 index 0000000..5213c84 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_table_py.html @@ -0,0 +1,805 @@ + + + + + Coverage for pyWebLayout/concrete/table.py: 78% + + + + + +

+ Coverage for pyWebLayout/concrete/table.py: + 78% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 303 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Concrete table rendering implementation for pyWebLayout.

4This module provides the concrete rendering classes for tables, including:

5- TableRenderer: Main table rendering with borders and spacing

6- TableRowRenderer: Individual row rendering

7- TableCellRenderer: Cell rendering with support for nested content (text, images, links)

8"""

10from __future__ import annotations

11from typing import Tuple, List, Optional, Dict

12from PIL import Image, ImageDraw

13from dataclasses import dataclass

15from pyWebLayout.core.base import Renderable

16from pyWebLayout.concrete.box import Box

17from pyWebLayout.abstract.block import Table, TableRow, TableCell, Paragraph, Heading, Image as AbstractImage

18from pyWebLayout.abstract.interactive_image import InteractiveImage

21@dataclass

22class TableStyle:

23 """Styling configuration for table rendering."""

25 # Border configuration

26 border_width: int = 1

27 border_color: Tuple[int, int, int] = (0, 0, 0)

29 # Cell padding

30 cell_padding: Tuple[int, int, int, int] = (5, 5, 5, 5) # top, right, bottom, left

32 # Header styling

33 header_bg_color: Tuple[int, int, int] = (240, 240, 240)

34 header_text_bold: bool = True

36 # Cell background

37 cell_bg_color: Tuple[int, int, int] = (255, 255, 255)

38 alternate_row_color: Optional[Tuple[int, int, int]] = (250, 250, 250)

40 # Spacing

41 cell_spacing: int = 0 # Space between cells (for separated borders model)

44class TableCellRenderer(Box):

45 """

46 Renders a single table cell with its content.

47 Supports paragraphs, headings, images, and links within cells.

48 """

50 def __init__(self,

51 cell: TableCell,

52 origin: Tuple[int,

53 int],

54 size: Tuple[int,

55 int],

56 draw: ImageDraw.Draw,

57 style: TableStyle,

58 is_header_section: bool = False,

59 canvas: Optional[Image.Image] = None):

60 """

61 Initialize a table cell renderer.

63 Args:

64 cell: The abstract TableCell to render

65 origin: Top-left position of the cell

66 size: Width and height of the cell

67 draw: PIL ImageDraw object for rendering

68 style: Table styling configuration

69 is_header_section: Whether this cell is in the header section

70 canvas: Optional PIL Image for pasting images (required for image rendering)

71 """

72 super().__init__(origin, size)

73 self._cell = cell

74 self._draw = draw

75 self._style = style

76 self._is_header_section = is_header_section or cell.is_header

77 self._canvas = canvas

78 self._children: List[Renderable] = []

80 def render(self) -> Image.Image:

81 """Render the table cell."""

82 # Determine background color

83 if self._is_header_section:

84 bg_color = self._style.header_bg_color

85 else:

86 bg_color = self._style.cell_bg_color

88 # Draw cell background

89 x, y = self._origin

90 w, h = self._size

91 self._draw.rectangle(

92 [x, y, x + w, y + h],

93 fill=bg_color,

94 outline=self._style.border_color,

95 width=self._style.border_width

96 )

98 # Calculate content area (inside padding)

99 padding = self._style.cell_padding

100 content_x = x + padding[3] # left padding

101 content_y = y + padding[0] # top padding

102 content_width = w - (padding[1] + padding[3]) # minus left and right padding

103 content_height = h - (padding[0] + padding[2]) # minus top and bottom padding

105 # Render cell content (text)

106 self._render_cell_content(content_x, content_y, content_width, content_height)

108 return None # Cell rendering is done directly on the page

110 def _render_cell_content(self, x: int, y: int, width: int, height: int):

111 """Render the content inside the cell (text and images) with line wrapping."""

112 from pyWebLayout.concrete.text import Line, Text

113 from pyWebLayout.style.fonts import Font

114 from pyWebLayout.style import FontWeight, Alignment

116 current_y = y + 2

117 available_height = height - 4 # Account for top/bottom padding

118

119 # Create font for the cell

120 font_size = 12

121 font_path = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"

122 if self._is_header_section and self._style.header_text_bold:

123 font_path = "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"

125 font = Font(

126 font_path=font_path,

127 font_size=font_size,

128 weight=FontWeight.BOLD if self._is_header_section and self._style.header_text_bold else FontWeight.NORMAL

129 )

131 # Word spacing constraints (min, max)

132 min_spacing = int(font_size * 0.25)

133 max_spacing = int(font_size * 0.5)

134 word_spacing = (min_spacing, max_spacing)

136 # Line height (baseline spacing)

137 line_height = font_size + 4

138 ascent, descent = font.font.getmetrics()

140 # Render each block in the cell

141 for block in self._cell.blocks():

142 if isinstance(block, AbstractImage):

143 # Render image

144 current_y = self._render_image_in_cell(

145 block, x, current_y, width, height - (current_y - y))

146 elif isinstance(block, (Paragraph, Heading)): 146 ↛ 225line 146 didn't jump to line 225 because the condition on line 146 was always true

147 # Get words from the block

148 from pyWebLayout.abstract.inline import Word as AbstractWord

150 word_items = block.words() if callable(block.words) else block.words

151 words = list(word_items)

153 if not words: 153 ↛ 154line 153 didn't jump to line 154 because the condition on line 153 was never true

154 continue

156 # Create new Word objects with the table cell's font

157 # The words from the paragraph may have AbstractStyle, but we need Font objects

158 wrapped_words = []

159 for word_item in words:

160 # Handle word tuples (index, word_obj)

161 if isinstance(word_item, tuple) and len(word_item) >= 2: 161 ↛ 162line 161 didn't jump to line 162 because the condition on line 161 was never true

162 word_obj = word_item[1]

163 else:

164 word_obj = word_item

166 # Extract text from the word

167 word_text = word_obj.text if hasattr(word_obj, 'text') else str(word_obj)

169 # Create a new Word with the cell's Font

170 new_word = AbstractWord(word_text, font)

171 wrapped_words.append(new_word)

172

173 # Layout words using Line objects with wrapping

174 word_index = 0

175 pretext = None

176

177 while word_index < len(wrapped_words):

178 # Check if we have space for another line

179 if current_y + ascent + descent > y + available_height: 179 ↛ 180line 179 didn't jump to line 180 because the condition on line 179 was never true

180 break # No more space in cell

182 # Create a new line

183 line = Line(

184 spacing=word_spacing,

185 origin=(x + 2, current_y),

186 size=(width - 4, line_height),

187 draw=self._draw,

188 font=font,

189 halign=Alignment.LEFT

190 )

192 # Add words to this line until it's full

193 line_has_content = False

194 while word_index < len(wrapped_words):

195 word = wrapped_words[word_index]

197 # Try to add word to line

198 success, overflow = line.add_word(word, pretext)

199 pretext = None # Clear pretext after use

200

201 if success: 201 ↛ 214line 201 didn't jump to line 214 because the condition on line 201 was always true

202 line_has_content = True

203 if overflow: 203 ↛ 207line 203 didn't jump to line 207 because the condition on line 203 was never true

204 # Word was hyphenated, carry over to next line

205 # DON'T increment word_index - we need to add the overflow

206 # to the next line with the same word

207 pretext = overflow

208 break # Move to next line

209 else:

210 # Word fit completely, move to next word

211 word_index += 1

212 else:

213 # Word doesn't fit on this line

214 if not line_has_content:

215 # Even first word doesn't fit, force it anyway and advance

216 # This prevents infinite loops with words that truly can't fit

217 word_index += 1

218 break

219

220 # Render the line if it has content

221 if line_has_content or len(line.text_objects) > 0: 221 ↛ 177line 221 didn't jump to line 177 because the condition on line 221 was always true

222 line.render()

223 current_y += line_height

224

225 if current_y > y + height - 10: # Don't overflow cell 225 ↛ 226line 225 didn't jump to line 226 because the condition on line 225 was never true

226 break

228 # If no structured content, try to get any text representation

229 if current_y == y + 2 and hasattr(self._cell, '_text_content'): 229 ↛ 231line 229 didn't jump to line 231 because the condition on line 229 was never true

230 # Use simple text rendering for fallback case

231 from PIL import ImageFont

232 try:

233 pil_font = ImageFont.truetype(font_path, font_size)

234 except BaseException:

235 pil_font = ImageFont.load_default()

237 self._draw.text(

238 (x + 2, current_y),

239 self._cell._text_content,

240 fill=(0, 0, 0),

241 font=pil_font

242 )

244 def _render_image_in_cell(self, image_block: AbstractImage, x: int, y: int,

245 max_width: int, max_height: int) -> int:

246 """

247 Render an image block inside a table cell.

249 Returns:

250 The new Y position after the image

251 """

252 try:

253 # Get the image path from the block

254 image_path = None

255 if hasattr(image_block, 'source'): 255 ↛ 257line 255 didn't jump to line 257 because the condition on line 255 was always true

256 image_path = image_block.source

257 elif hasattr(image_block, '_source'):

258 image_path = image_block._source

259 elif hasattr(image_block, 'path'):

260 image_path = image_block.path

261 elif hasattr(image_block, 'src'):

262 image_path = image_block.src

263 elif hasattr(image_block, '_path'):

264 image_path = image_block._path

265 elif hasattr(image_block, '_src'):

266 image_path = image_block._src

268 if not image_path: 268 ↛ 269line 268 didn't jump to line 269 because the condition on line 268 was never true

269 return y + 20 # Skip if no image path

271 # Load and resize image to fit in cell

272 img = Image.open(image_path)

273

274 # Calculate scaling to fit within max dimensions

275 # Use more of the cell space for images

276 img_width, img_height = img.size

277 scale_w = max_width / img_width if img_width > max_width else 1

278 scale_h = (max_height - 10) / \

279 img_height if img_height > (max_height - 10) else 1

280 scale = min(scale_w, scale_h, 1.0) # Don't upscale

282 new_width = int(img_width * scale)

283 new_height = int(img_height * scale)

285 if scale < 1.0: 285 ↛ 286line 285 didn't jump to line 286 because the condition on line 285 was never true

286 img = img.resize((new_width, new_height), Image.Resampling.LANCZOS)

288 # Center image horizontally in cell

289 img_x = x + (max_width - new_width) // 2

290

291 # Paste the image onto the canvas if available

292 if self._canvas is not None: 292 ↛ 299line 292 didn't jump to line 299 because the condition on line 292 was always true

293 if img.mode == 'RGBA': 293 ↛ 294line 293 didn't jump to line 294 because the condition on line 293 was never true

294 self._canvas.paste(img, (img_x, y), img)

295 else:

296 self._canvas.paste(img, (img_x, y))

297 else:

298 # Fallback: draw a placeholder if no canvas provided

299 self._draw.rectangle(

300 [img_x, y, img_x + new_width, y + new_height],

301 fill=(200, 200, 200),

302 outline=(150, 150, 150)

303 )

304

305 # Draw image indicator text

306 from PIL import ImageFont

307 try:

308 small_font = ImageFont.truetype(

309 "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", 9)

310 except BaseException:

311 small_font = ImageFont.load_default()

313 text = f"[Image: {new_width}x{new_height}]"

314 bbox = self._draw.textbbox((0, 0), text, font=small_font)

315 text_width = bbox[2] - bbox[0]

316 text_x = img_x + (new_width - text_width) // 2

317 text_y = y + (new_height - 12) // 2

318 self._draw.text(

319 (text_x, text_y), text, fill=(

320 100, 100, 100), font=small_font)

322 # Set bounds on InteractiveImage objects for tap detection

323 if isinstance(image_block, InteractiveImage): 323 ↛ 324line 323 didn't jump to line 324 because the condition on line 323 was never true

324 image_block.set_rendered_bounds(

325 origin=(img_x, y),

326 size=(new_width, new_height)

327 )

329 return y + new_height + 5 # Add some spacing after image

331 except Exception:

332 # If image loading fails, just return current position

333 return y + 20

336class TableRowRenderer(Box):

337 """

338 Renders a single table row containing multiple cells.

339 """

341 def __init__(self,

342 row: TableRow,

343 origin: Tuple[int,

344 int],

345 column_widths: List[int],

346 row_height: int,

347 draw: ImageDraw.Draw,

348 style: TableStyle,

349 is_header_section: bool = False,

350 canvas: Optional[Image.Image] = None):

351 """

352 Initialize a table row renderer.

353

354 Args:

355 row: The abstract TableRow to render

356 origin: Top-left position of the row

357 column_widths: List of widths for each column

358 row_height: Height of this row

359 draw: PIL ImageDraw object for rendering

360 style: Table styling configuration

361 is_header_section: Whether this row is in the header section

362 canvas: Optional PIL Image for pasting images

363 """

364 width = sum(column_widths) + style.border_width * (len(column_widths) + 1)

365 super().__init__(origin, (width, row_height))

366 self._row = row

367 self._column_widths = column_widths

368 self._row_height = row_height

369 self._draw = draw

370 self._style = style

371 self._is_header_section = is_header_section

372 self._canvas = canvas

373 self._cell_renderers: List[TableCellRenderer] = []

375 def render(self) -> Image.Image:

376 """Render the table row by rendering each cell."""

377 x, y = self._origin

378 current_x = x

379

380 # Render each cell

381 cells = list(self._row.cells())

382 for i, cell in enumerate(cells):

383 if i < len(self._column_widths): 383 ↛ 382line 383 didn't jump to line 382 because the condition on line 383 was always true

384 cell_width = self._column_widths[i]

385

386 # Handle colspan

387 if cell.colspan > 1 and i + cell.colspan <= len(self._column_widths):

388 # Sum up widths for spanned columns

389 cell_width = sum(self._column_widths[i:i + cell.colspan])

390 cell_width += self._style.border_width * (cell.colspan - 1)

392 # Create and render cell

393 cell_renderer = TableCellRenderer(

394 cell,

395 (current_x, y),

396 (cell_width, self._row_height),

397 self._draw,

398 self._style,

399 self._is_header_section,

400 self._canvas

401 )

402 cell_renderer.render()

403 self._cell_renderers.append(cell_renderer)

405 current_x += cell_width + self._style.border_width

406

407 return None # Row rendering is done directly on the page

410class TableRenderer(Box):

411 """

412 Main table renderer that orchestrates the rendering of an entire table.

413 Handles layout calculation, row/cell placement, and overall table structure.

414 """

416 def __init__(self,

417 table: Table,

418 origin: Tuple[int,

419 int],

420 available_width: int,

421 draw: ImageDraw.Draw,

422 style: Optional[TableStyle] = None,

423 canvas: Optional[Image.Image] = None):

424 """

425 Initialize a table renderer.

427 Args:

428 table: The abstract Table to render

429 origin: Top-left position where the table should be rendered

430 available_width: Maximum width available for the table

431 draw: PIL ImageDraw object for rendering

432 style: Optional table styling configuration

433 canvas: Optional PIL Image for pasting images

434 """

435 self._table = table

436 self._draw = draw

437 self._style = style or TableStyle()

438 self._available_width = available_width

439 self._canvas = canvas

440

441 # Calculate table dimensions

442 self._column_widths, self._row_heights = self._calculate_dimensions()

443 total_width = sum(self._column_widths) + \

444 self._style.border_width * (len(self._column_widths) + 1)

445 total_height = sum(self._row_heights.values()) + \

446 self._style.border_width * (len(self._row_heights) + 1)

448 super().__init__(origin, (total_width, total_height))

449 self._row_renderers: List[TableRowRenderer] = []

450

451 def _calculate_dimensions(self) -> Tuple[List[int], Dict[str, int]]:

452 """

453 Calculate column widths and row heights for the table.

454

455 Uses the table optimizer for intelligent column width distribution.

457 Returns:

458 Tuple of (column_widths, row_heights_dict)

459 """

460 from pyWebLayout.layout.table_optimizer import optimize_table_layout

461

462 all_rows = list(self._table.all_rows())

464 if not all_rows:

465 return ([100], {"header": 30, "body": 30, "footer": 30})

466

467 # Use optimizer for column widths!

468 column_widths = optimize_table_layout(

469 self._table,

470 self._available_width,

471 sample_size=5,

472 style=self._style

473 )

475 if not column_widths: 475 ↛ 477line 475 didn't jump to line 477 because the condition on line 475 was never true

476 # Fallback if table is empty

477 column_widths = [100]

478

479 # Calculate row heights dynamically based on optimized column widths

480 header_height = self._calculate_row_height_for_section(

481 all_rows, "header", column_widths) if any(

482 1 for section, _ in all_rows if section == "header") else 0

483

484 body_height = self._calculate_row_height_for_section(

485 all_rows, "body", column_widths)

486

487 footer_height = self._calculate_row_height_for_section(

488 all_rows, "footer", column_widths) if any(

489 1 for section, _ in all_rows if section == "footer") else 0

490

491 row_heights = {

492 "header": header_height,

493 "body": body_height,

494 "footer": footer_height

495 }

496

497 return (column_widths, row_heights)

498

499 def _calculate_row_height_for_section(

500 self,

501 all_rows: List,

502 section: str,

503 column_widths: List[int]) -> int:

504 """

505 Calculate the maximum required height for rows in a specific section.

506

507 Args:

508 all_rows: List of all rows in the table

509 section: Section name ('header', 'body', or 'footer')

510 column_widths: List of column widths

512 Returns:

513 Maximum height needed for rows in this section

514 """

515 from pyWebLayout.concrete.text import Text

516 from pyWebLayout.style.fonts import Font

517 from pyWebLayout.abstract.inline import Word as AbstractWord

518

519 # Font configuration

520 font_size = 12

521 line_height = font_size + 4

522 padding = self._style.cell_padding

523 vertical_padding = padding[0] + padding[2] # top + bottom

524 horizontal_padding = padding[1] + padding[3] # left + right

526 max_height = 40 # Minimum height

527

528 for row_section, row in all_rows:

529 if row_section != section:

530 continue

532 row_max_height = 40 # Minimum for this row

533

534 for cell_idx, cell in enumerate(row.cells()):

535 if cell_idx >= len(column_widths): 535 ↛ 536line 535 didn't jump to line 536 because the condition on line 535 was never true

536 continue

538 # Get cell width (accounting for colspan)

539 cell_width = column_widths[cell_idx]

540 if cell.colspan > 1 and cell_idx + \ 540 ↛ 542line 540 didn't jump to line 542 because the condition on line 540 was never true

541 cell.colspan <= len(column_widths):

542 cell_width = sum(

543 column_widths[cell_idx:cell_idx + cell.colspan])

544 cell_width += self._style.border_width * (cell.colspan - 1)

545

546 # Calculate content width (minus padding)

547 content_width = cell_width - horizontal_padding - 4 # Extra margin

548

549 cell_height = vertical_padding + 4 # Base height with padding

550

551 # Analyze each block in the cell

552 for block in cell.blocks():

553 if isinstance(block, AbstractImage):

554 # Images need more space

555 cell_height = max(cell_height, 120)

556 elif isinstance(block, (Paragraph, Heading)): 556 ↛ 552line 556 didn't jump to line 552 because the condition on line 556 was always true

557 # Calculate text wrapping height

558 word_items = block.words() if callable(

559 block.words) else block.words

560 words = list(word_items)

561

562 if not words: 562 ↛ 563line 562 didn't jump to line 563 because the condition on line 562 was never true

563 continue

565 # Simulate text wrapping to count lines

566 lines_needed = self._estimate_wrapped_lines(

567 words, content_width, font_size)

568 text_height = lines_needed * line_height

569 cell_height = max(

570 cell_height, text_height + vertical_padding + 4)

571

572 row_max_height = max(row_max_height, cell_height)

574 max_height = max(max_height, row_max_height)

576 return max_height

577

578 def _estimate_wrapped_lines(

579 self,

580 words: List,

581 available_width: int,

582 font_size: int) -> int:

583 """

584 Estimate how many lines are needed to render the given words.

585

586 Args:

587 words: List of word objects

588 available_width: Available width for text

589 font_size: Font size in pixels

590

591 Returns:

592 Number of lines needed

593 """

594 from pyWebLayout.concrete.text import Text

595 from pyWebLayout.style.fonts import Font

596

597 # Create a temporary font for measurement

598 font_path = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"

599 font = Font(font_path=font_path, font_size=font_size)

600

601 # Word spacing (approximate)

602 word_spacing = int(font_size * 0.25)

603

604 lines = 1

605 current_line_width = 0

606

607 for word_item in words:

608 # Handle word tuples (index, word_obj)

609 if isinstance(word_item, tuple) and len(word_item) >= 2: 609 ↛ 610line 609 didn't jump to line 610 because the condition on line 609 was never true

610 word_obj = word_item[1]

611 else:

612 word_obj = word_item

613

614 # Extract text from the word

615 word_text = word_obj.text if hasattr(

616 word_obj, 'text') else str(word_obj)

617

618 # Measure word width

619 word_width = font.font.getlength(word_text)

620

621 # Check if word fits on current line

622 if current_line_width > 0: # Not first word on line

623 needed_width = current_line_width + word_spacing + word_width

624 if needed_width > available_width: 624 ↛ 626line 624 didn't jump to line 626 because the condition on line 624 was never true

625 # Need new line

626 lines += 1

627 current_line_width = word_width

628 else:

629 current_line_width = needed_width

630 else:

631 # First word on line

632 if word_width > available_width: 632 ↛ 634line 632 didn't jump to line 634 because the condition on line 632 was never true

633 # Word needs to be hyphenated, assume it takes 1 line

634 lines += 1

635 current_line_width = 0

636 else:

637 current_line_width = word_width

638

639 return lines

640

641 def render(self) -> Image.Image:

642 """Render the complete table."""

643 x, y = self._origin

644 current_y = y

645

646 # Render caption if present

647 if self._table.caption:

648 current_y = self._render_caption(x, current_y)

649 current_y += 10 # Space after caption

650

651 # Render header rows

652 for section, row in self._table.all_rows():

653 if section == "header":

654 row_height = self._row_heights["header"]

655 elif section == "footer":

656 row_height = self._row_heights["footer"]

657 else:

658 row_height = self._row_heights["body"]

659

660 is_header = (section == "header")

661

662 row_renderer = TableRowRenderer(

663 row,

664 (x, current_y),

665 self._column_widths,

666 row_height,

667 self._draw,

668 self._style,

669 is_header,

670 self._canvas

671 )

672 row_renderer.render()

673 self._row_renderers.append(row_renderer)

674

675 current_y += row_height + self._style.border_width

676

677 return None # Table rendering is done directly on the page

679 def _render_caption(self, x: int, y: int) -> int:

680 """Render the table caption and return the new Y position."""

681 from PIL import ImageFont

682

683 try:

684 font = ImageFont.truetype(

685 "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf", 13)

686 except BaseException:

687 font = ImageFont.load_default()

688

689 # Center the caption

690 bbox = self._draw.textbbox((0, 0), self._table.caption, font=font)

691 text_width = bbox[2] - bbox[0]

692 caption_x = x + (self._size[0] - text_width) // 2

693

694 self._draw.text((caption_x, y), self._table.caption, fill=(0, 0, 0), font=font)

695

696 return y + 20 # Caption height

697

698 @property

699 def height(self) -> int:

700 """Get the total height of the rendered table."""

701 return int(self._size[1])

703 @property

704 def width(self) -> int:

705 """Get the total width of the rendered table."""

706 return int(self._size[0])

+ + + diff --git a/cov_info/htmlcov/z_7d48e1f4c6486fa2_text_py.html b/cov_info/htmlcov/z_7d48e1f4c6486fa2_text_py.html new file mode 100644 index 0000000..28a4bc7 --- /dev/null +++ b/cov_info/htmlcov/z_7d48e1f4c6486fa2_text_py.html @@ -0,0 +1,1290 @@ + + + + + Coverage for pyWebLayout/concrete/text.py: 77% + + + + + +

+ Coverage for pyWebLayout/concrete/text.py: + 77% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 462 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

2from pyWebLayout.core.base import Renderable, Queriable

3from pyWebLayout.core.query import QueryResult

4from .box import Box

5from pyWebLayout.style import Alignment, Font, TextDecoration

6from pyWebLayout.abstract import Word

7from pyWebLayout.abstract.inline import LinkedWord

8from pyWebLayout.abstract.functional import Link

9from pyWebLayout.core.cache import UsageCache, SizedUsageCache

10from PIL import ImageDraw, ImageFont

11from typing import Tuple, List, Optional, Any, Dict

12import logging

13import math

14import numpy as np

15from abc import ABC, abstractmethod

17logger = logging.getLogger(__name__)

20# ---------------------------------------------------------------------------

21# Text rendering caches

22#

23# A page re-measures and re-rasterises the same words constantly: measured over a

24# novel at 1404x1872, a page issues ~2800 width measurements and ~2500 glyph

25# rasterisations for fewer than 1000 distinct (font, string) pairs. Caching both

26# turns a ~225ms page into a ~30ms page. Both caches are bounded so that a long

27# reading session cannot grow without limit on a memory-constrained device.

28# ---------------------------------------------------------------------------

30# Word widths are small floats; 8192 entries costs well under 1MB and comfortably

31# spans the working set of several chapters at a couple of font sizes.

32DEFAULT_WIDTH_CACHE_ENTRIES = 8192

34# Glyph bitmaps are the expensive ones: ~700 bytes each on average at 1404x1872,

35# so an unbounded cache reaches ~12MB after 40 pages. 4MB holds several pages'

36# worth of distinct words while leaving headroom on a 512MB Pi Zero 2.

37DEFAULT_GLYPH_CACHE_BYTES = 4 * 1024 * 1024

39# PIL rasterises text at sub-pixel horizontal offsets, so a cache keyed only on

40# (font, string) would quantise every word to a whole pixel. Bucketing the

41# sub-pixel phase keeps that error negligible at the cost of more entries. 2 steps

42# holds the mean error to ~3.6/255 -- a fifth of one step of a 16-level e-ink

43# panel -- while keeping the cache four times smaller than 4 steps would.

44DEFAULT_GLYPH_SUBPIXEL_STEPS = 2

47def _glyph_entry_bytes(entry: Tuple[Any, Tuple[int, int]]) -> int:

48 """Approximate footprint of a cached (mask, offset) pair, in bytes."""

49 mask = entry[0]

50 try:

51 width, height = mask.size

52 except (AttributeError, TypeError, ValueError):

53 return 0

54 return width * height

57_width_cache: UsageCache = UsageCache(DEFAULT_WIDTH_CACHE_ENTRIES)

58_glyph_cache: SizedUsageCache = SizedUsageCache(DEFAULT_GLYPH_CACHE_BYTES, _glyph_entry_bytes)

59_glyph_subpixel_steps: int = DEFAULT_GLYPH_SUBPIXEL_STEPS

61# Every Line asks its font for the advance width of a space. That single

62# FreeTypeFont.getlength(" ") call costs ~18us -- two orders of magnitude more

63# than getmetrics() -- because PIL shapes the string from scratch each time, and

64# it lands once per line created, which dominates the cost of laying a line out.

65# There are only ever a handful of distinct fonts in play, so memoise per font

66# object. Values are wrapped in a 1-tuple because None is itself a legitimate

67# result (fonts that cannot report a length) and must not read as a cache miss.

68_space_advance_cache: Dict[Any, Tuple[Optional[int]]] = {}

70# Set to False the first time the fast rasterisation path is found to be

71# unavailable (e.g. a PIL build without the private ImageDraw internals it uses),

72# after which every Text falls back to ImageDraw.text().

73_glyph_fast_path_available: bool = True

76def configure_text_caches(width_entries: Optional[int] = None,

77 glyph_bytes: Optional[int] = None,

78 subpixel_steps: Optional[int] = None):

79 """

80 Tune the text rendering caches.

82 Memory-constrained targets should shrink these; a desktop rendering many font

83 sizes may benefit from raising them.

85 Args:

86 width_entries: Maximum cached word-width measurements.

87 glyph_bytes: Maximum total size of cached glyph bitmaps, in bytes.

88 subpixel_steps: Sub-pixel phase buckets per axis. 1 disables sub-pixel

89 positioning entirely (smallest cache, slightly softer text).

90 """

91 global _glyph_subpixel_steps

93 if width_entries is not None:

94 _width_cache.resize(width_entries)

95 if glyph_bytes is not None:

96 _glyph_cache.resize(glyph_bytes)

97 if subpixel_steps is not None:

98 if subpixel_steps <= 0:

99 raise ValueError(f"subpixel_steps must be positive, got {subpixel_steps}")

100 if subpixel_steps != _glyph_subpixel_steps:

101 # Cached entries embed the phase bucket in their key.

102 _glyph_cache.clear()

103 _glyph_subpixel_steps = subpixel_steps

106def clear_text_caches():

107 """Drop all cached widths and glyph bitmaps."""

108 _width_cache.clear()

109 _glyph_cache.clear()

110 _space_advance_cache.clear()

113def _space_advance(font) -> Optional[int]:

114 """

115 The font's own advance width for a space, in whole pixels.

117 None when the font cannot report one, which is the signal for callers to fall

118 back to their configured spacing range.

119 """

120 try:

121 cached = _space_advance_cache.get(font)

122 except TypeError:

123 # Unhashable font object; measure without caching.

124 cached = None

125 else:

126 if cached is not None:

127 return cached[0]

129 try:

130 value = int(round(font.getlength(" ")))

131 except (AttributeError, TypeError, ValueError):

132 value = None

133

134 try:

135 _space_advance_cache[font] = (value,)

136 except TypeError:

137 pass

138 return value

141def text_cache_stats() -> Dict[str, Any]:

142 """Occupancy and hit rates for both text caches, for tuning and diagnostics."""

143 return {

144 'width': _width_cache.stats(),

145 'glyph': _glyph_cache.stats(),

146 'glyph_subpixel_steps': _glyph_subpixel_steps,

147 'glyph_fast_path': _glyph_fast_path_available,

148 }

151def prewarm_text_caches(entries,

152 draw: Optional[ImageDraw.ImageDraw] = None,

153 budget_bytes: Optional[int] = None,

154 max_words: Optional[int] = None) -> Tuple[int, int]:

155 """

156 Preload the caches with a document's most frequent words.

157

158 A document states its own access distribution up front: the words it uses most

159 are the words every page will draw. Rasterising them once at open time moves

160 that work off the page-turn path, and seeding each entry with its document

161 frequency puts it in the right place in the eviction order immediately, rather

162 than after the cache has learned it.

163

164 This depends on eviction ranking by use count. Under recency eviction the

165 preloaded entries would be discarded by the first page of unfamiliar text; under

166 usage ranking a word occurring 4000 times outranks anything met while scanning

167 and stays resident. Measured over a 50-page trace, preloading cut misses by 27%

168 with usage ranking against 12% with recency.

170 Args:

171 entries: Iterable of ``(font, text, colour, frequency)``, where `font` is a

172 PIL font object, `colour` the fill the text will be drawn in, and

173 `frequency` the number of times the word occurs in the document.

174 draw: An ImageDraw sharing the page's mode, used to resolve ink and font

175 mode. A scratch RGBA context is used if omitted.

176 budget_bytes: Cap on bytes to preload. Defaults to half the glyph budget so

177 that live rendering keeps room to cache what preloading missed.

178 max_words: Cap on distinct words to preload, before sub-pixel variants.

179

180 Returns:

181 Tuple of (words preloaded, bytes preloaded).

182 """

183 if not _glyph_fast_path_available:

184 return 0, 0

186 if draw is None:

187 from PIL import Image

188 draw = ImageDraw.Draw(Image.new('RGBA', (1, 1)))

189

190 if budget_bytes is None:

191 budget_bytes = _glyph_cache.max_bytes // 2

192 budget_bytes = min(budget_bytes, _glyph_cache.max_bytes)

194 ranked = sorted(entries, key=lambda e: -e[3])

195 if max_words is not None:

196 ranked = ranked[:max_words]

198 steps = _glyph_subpixel_steps

199 mode = draw.fontmode

200 draw_mode = draw.mode

201 ink_cache: Dict[Any, Any] = {}

202 words = 0

203 used = 0

205 for font, text, colour, frequency in ranked:

206 if frequency <= 1 or used >= budget_bytes:

207 break

208 if not isinstance(font, ImageFont.FreeTypeFont):

209 continue

210

211 try:

212 ink = ink_cache.get(colour)

213 if ink is None:

214 ink, _ = draw._getink(colour)

215 if ink is None:

216 continue

217 ink_cache[colour] = ink

219 # Measuring is cheap and every layout pass needs it.

220 _width_cache.put((font, text, draw_mode),

221 draw.textlength(text, font=font), count=frequency)

222

223 # Words land on arbitrary sub-pixel offsets, so cover every horizontal

224 # phase. Baselines are whole pixels, so only phase 0 is needed

225 # vertically.

226 for x_bucket in range(steps):

227 entry = font.getmask2(text, mode, anchor="ls", ink=ink,

228 start=(x_bucket / steps, 0.0))

229 _glyph_cache.put((font, text, mode, ink, x_bucket, 0), entry,

230 count=frequency)

231 used += _glyph_entry_bytes(entry)

232 words += 1

234 except AttributeError:

235 logger.warning("Glyph cache unavailable for this Pillow build; "

236 "skipping prewarm.", exc_info=True)

237 return words, used

238 except (TypeError, ValueError):

239 continue

241 logger.debug("Prewarmed %d words (%.2fMB) into the text caches",

242 words, used / 1e6)

243 return words, used

246class AlignmentHandler(ABC):

247 """

248 Abstract base class for text alignment handlers.

249 Each handler implements a specific alignment strategy.

250 """

252 @abstractmethod

253 def calculate_spacing_and_position(self, text_objects: List['Text'],

254 available_width: int, min_spacing: int,

255 max_spacing: int,

256 natural_spacing: Optional[int] = None,

257 total_width: Optional[float] = None

258 ) -> Tuple[int, int, bool]:

259 """

260 Calculate the spacing between words and starting position for the line.

262 Args:

263 text_objects: List of Text objects in the line

264 available_width: Total width available for the line

265 min_spacing: Minimum spacing between words

266 max_spacing: Maximum spacing between words

267 natural_spacing: The font's own space width. Ragged alignments use it

268 as a constant gap; justification ignores it. Defaults to

269 min_spacing when not supplied.

270 total_width: The summed width of `text_objects`, when the caller

271 already knows it. Purely an optimisation: a line asks its handler

272 to re-measure once per candidate word, and summing the whole line

273 each time makes filling a line quadratic in its word count. Omit

274 it and the sum is taken here as before.

276 Returns:

277 Tuple of (spacing_between_words, starting_x_position, overflow)

278 """

281class LeftAlignmentHandler(AlignmentHandler):

282 """Handler for left-aligned text."""

284 def calculate_spacing_and_position(self,

285 text_objects: List['Text'],

286 available_width: int,

287 min_spacing: int,

288 max_spacing: int,

289 natural_spacing: Optional[int] = None,

290 total_width: Optional[float] = None

291 ) -> Tuple[int, int, bool]:

292 """

293 Calculate spacing and position for left-aligned text objects.

295 Left-aligned text uses a constant word space and leaves whatever is left

296 over as a ragged right edge. It must not spread the residual space across

297 the gaps: that stretches each line by a different amount, which reads as

298 badly-set justified text rather than as ragged-right.

300 Args:

301 text_objects (List[Text]): A list of text objects to be laid out.

302 available_width (int): The total width available for layout.

303 min_spacing (int): Minimum spacing between text objects.

304 max_spacing (int): Maximum spacing between text objects.

305 natural_spacing (Optional[int]): The font's own space width.

307 Returns:

308 Tuple[int, int, bool]: Spacing, start position, and overflow flag.

309 """

310 # Handle single word case

311 if len(text_objects) <= 1:

312 return 0, 0, False

313

314 spacing = min_spacing if natural_spacing is None else natural_spacing

315 spacing = max(min_spacing, min(max_spacing, int(spacing)))

317 text_length = (sum([text.width for text in text_objects])

318 if total_width is None else total_width)

319 num_gaps = len(text_objects) - 1

321 # The spacing is constant whether or not the content fits: tightening a

322 # full line here would make it differ from its neighbours, which is the

323 # variation this alignment is supposed to avoid. Report the overflow and

324 # let line breaking move the offending word instead.

325 overflow = text_length + (spacing * num_gaps) > available_width

327 return spacing, 0, overflow

329

330class CenterRightAlignmentHandler(AlignmentHandler):

331 """Handler for center and right-aligned text."""

332

333 def __init__(self, alignment: Alignment):

334 self._alignment = alignment

336 def calculate_spacing_and_position(self, text_objects: List['Text'],

337 available_width: int, min_spacing: int,

338 max_spacing: int,

339 natural_spacing: Optional[int] = None,

340 total_width: Optional[float] = None

341 ) -> Tuple[int, int, bool]:

342 """

343 Centre/right alignment: constant word space, line shifted as a block.

345 Like left alignment, the residual space must not be spread across the

346 gaps - it belongs in the margin. The start position is then derived from

347 the same spacing that will actually be used, so the line lands where it

348 was measured to land.

349 """

350 word_length = (sum([word.width for word in text_objects])

351 if total_width is None else total_width)

353 # Handle single word case

354 if len(text_objects) <= 1:

355 if self._alignment == Alignment.CENTER:

356 start_position = (available_width - word_length) // 2

357 else: # RIGHT

358 start_position = available_width - word_length

359 return 0, max(0, int(start_position)), False

360

361 spacing = min_spacing if natural_spacing is None else natural_spacing

362 spacing = max(min_spacing, min(max_spacing, int(spacing)))

364 num_gaps = len(text_objects) - 1

365 overflow = word_length + (spacing * num_gaps) > available_width

367 content_length = word_length + num_gaps * spacing

368 if self._alignment == Alignment.CENTER:

369 start_position = (available_width - content_length) // 2

370 else:

371 start_position = available_width - content_length

373 return spacing, max(0, int(start_position)), overflow

376class JustifyAlignmentHandler(AlignmentHandler):

377 """Handler for justified text with full justification."""

379 def __init__(self):

380 # The per-gap spacings are described by a plan rather than stored outright,

381 # and materialised on demand by the _gap_spacings property below. Fitting a

382 # line calls this handler once per candidate word and only ever looks at the

383 # first gap; building the whole list on each of those probes made adding n

384 # words to a line O(n^2). Only render() reads the full list.

385 self._gap_uniform: Optional[int] = None

386 self._gap_residual: int = 0

387 self._gap_count: int = 0

388 self._gap_cache: Optional[List[int]] = []

389

390 @property

391 def _gap_spacings(self) -> List[int]:

392 """The spacing to apply at each gap, left to right."""

393 if self._gap_cache is None:

394 if self._gap_uniform is not None: 394 ↛ 395line 394 didn't jump to line 395 because the condition on line 394 was never true

395 self._gap_cache = [self._gap_uniform] * self._gap_count

396 else:

397 self._gap_cache = self._distribute(self._gap_residual, self._gap_count)

398 return self._gap_cache

399

400 @staticmethod

401 def _distribute(total: int, num_gaps: int) -> List[int]:

402 """Split `total` pixels across `num_gaps` gaps by cumulative rounding."""

403 gaps = []

404 placed = 0

405 for i in range(1, num_gaps + 1):

406 cumulative = int(round(total * i / num_gaps))

407 gaps.append(cumulative - placed)

408 placed = cumulative

409 return gaps

410

411 def calculate_spacing_and_position(self, text_objects: List['Text'],

412 available_width: int, min_spacing: int,

413 max_spacing: int,

414 natural_spacing: Optional[int] = None,

415 total_width: Optional[float] = None

416 ) -> Tuple[int, int, bool]:

417 """

418 Justified alignment distributes space to fill the entire line width.

419

420 natural_spacing is ignored: filling the measure is the whole point.

421

422 For justified text, we ALWAYS try to fill the entire width by distributing

423 space between words, regardless of max_spacing constraints. The only limit

424 is min_spacing to ensure readability.

425 """

427 word_length = (sum([word.width for word in text_objects])

428 if total_width is None else total_width)

429 residual_space = available_width - word_length

430 num_gaps = max(1, len(text_objects) - 1)

432 # Check if we have enough space for minimum spacing

433 if residual_space // num_gaps < min_spacing:

434 # Not enough space - this is overflow

435 self._gap_uniform = min_spacing

436 self._gap_count = num_gaps

437 self._gap_cache = None

438 return min_spacing, 0, True

439

440 # Distribute the residual by cumulative rounding rather than by taking a

441 # floor per gap and scattering the remainder. Word widths are fractional,

442 # so flooring each gap loses part of a pixel and truncating the remainder

443 # loses up to another - the line then stops one or two pixels short of the

444 # margin, and by a different amount on each line, which is visible as a

445 # ragged right edge on otherwise justified text. Rounding the running

446 # total makes the gaps sum to the residual exactly.

447 total = int(round(residual_space))

448 self._gap_uniform = None

449 self._gap_residual = total

450 self._gap_count = num_gaps

451 self._gap_cache = None

452

453 # The first gap is the whole of the plan that fitting needs, and it falls

454 # out of the same cumulative rounding as _distribute would give it.

455 return int(round(total / num_gaps)), 0, False

457

458class Text(Renderable, Queriable):

459 """

460 Concrete implementation for rendering text.

461 This class handles the visual representation of text fragments.

462 """

464 def __init__(

465 self,

466 text: str,

467 style: Font,

468 draw: ImageDraw.Draw,

469 source: Optional[Word] = None,

470 line: Optional[Line] = None):

471 """

472 Initialize a Text object.

473

474 Args:

475 text: The text content to render

476 style: The font style to use for rendering

477 """

478 super().__init__()

479 self._text = text

480 self._style = style

481 self._line = line

482 self._source = source

483 self._origin = np.array([0, 0])

484 self._draw = draw

485

486 # Calculate dimensions

487 self._calculate_dimensions()

488

489 def _calculate_dimensions(self):

490 """Calculate the width and height of the text based on the font metrics"""

491 # Measuring a word costs a FreeType shaping pass, and the same words recur

492 # constantly within a document, so results are cached per (font, string).

493 # The draw's image mode is part of the key because PIL derives advance

494 # widths differently for bilevel ("1") targets.

495 font = self._style.font

496 key = (font, self._text, self._draw.mode)

497

498 width = _width_cache.get(key)

499 if width is None:

500 width = self._draw.textlength(self._text, font=font)

501 _width_cache.put(key, width)

502 self._width = width

504 ascent, descent = font.getmetrics()

505 self._ascent = ascent

506 self._middle_y = ascent - descent / 2

507

508 @classmethod

509 def from_word(cls, word: Word, draw: ImageDraw.Draw):

510 return cls(word.text, word.style, draw)

512 @property

513 def text(self) -> str:

514 """Get the text content"""

515 return self._text

517 @property

518 def style(self) -> Font:

519 """Get the text style"""

520 return self._style

521

522 @property

523 def origin(self) -> np.ndarray:

524 """Get the origin of the text"""

525 return self._origin

526

527 @property

528 def line(self) -> Optional[Line]:

529 """Get the line containing this text"""

530 return self._line

532 @line.setter

533 def line(self, line):

534 """Set the line containing this text"""

535 self._line = line

536

537 @property

538 def width(self) -> int:

539 """Get the width of the text"""

540 return self._width

541

542 @property

543 def size(self) -> int:

544 """Get the width and height of the text"""

545 # Return actual rendered height (ascent + descent) not just font_size

546 ascent, descent = self._style.font.getmetrics()

547 actual_height = ascent + descent

548 return np.array((self._width, actual_height))

549

550 def set_origin(self, origin: np.generic):

551 """Set the origin (left baseline ("ls")) of this text element"""

552 self._origin = origin

553

554 def add_line(self, line):

555 """Add this text to a line"""

556 self._line = line

557

558 def in_object(self, point: np.generic):

559 """

560 Check if a point is in the text object.

561

562 Override Queriable.in_object() because Text uses baseline-anchored positioning.

563 The origin is at the baseline (anchor="ls"), not the top-left corner.

565 Args:

566 point: The coordinates to check

567

568 Returns:

569 True if the point is within the text bounds

570 """

571 point_array = np.array(point)

572

573 # Text origin is at baseline, so visual top is origin[1] - ascent

574 visual_top = self._origin[1] - self._ascent

575 visual_bottom = self._origin[1] + (self.size[1] - self._ascent)

576

577 # Check if point is within bounds

578 # X: origin[0] to origin[0] + width

579 # Y: visual_top to visual_bottom

580 return (self._origin[0] <= point_array[0] < self._origin[0] + self.size[0] and

581 visual_top <= point_array[1] < visual_bottom)

582

583 def _apply_decoration(self, next_text: Optional['Text'] = None, spacing: int = 0):

584 """

585 Apply text decoration (underline or strikethrough).

586

587 Args:

588 next_text: The next Text object in the line (if any)

589 spacing: The spacing to the next text object

590 """

591 if self._style.decoration == TextDecoration.UNDERLINE: 591 ↛ 609line 591 didn't jump to line 609 because the condition on line 591 was always true

592 # Draw underline at about 90% of the height

593 y_position = self._origin[1] - 0.1 * self._style.font_size

594 line_width = max(1, int(self._style.font_size / 15))

595

596 # Determine end x-coordinate

597 end_x = self._origin[0] + self._width

598

599 # If next text also has underline decoration, extend to connect them

600 if (next_text is not None and

601 next_text.style.decoration == TextDecoration.UNDERLINE and

602 next_text.style.colour == self._style.colour):

603 # Extend the underline through the spacing to connect with next word

604 end_x += spacing

605

606 self._draw.line([(self._origin[0], y_position), (end_x, y_position)],

607 fill=self._style.colour, width=line_width)

608

609 elif self._style.decoration == TextDecoration.STRIKETHROUGH:

610 # Draw strikethrough at about 50% of the height

611 y_position = self._origin[1] + self._middle_y

612 line_width = max(1, int(self._style.font_size / 15))

613

614 # Determine end x-coordinate

615 end_x = self._origin[0] + self._width

616

617 # If next text also has strikethrough decoration, extend to connect them

618 if (next_text is not None and

619 next_text.style.decoration == TextDecoration.STRIKETHROUGH and

620 next_text.style.colour == self._style.colour):

621 # Extend the strikethrough through the spacing to connect with next word

622 end_x += spacing

623

624 self._draw.line([(self._origin[0], y_position), (end_x, y_position)],

625 fill=self._style.colour, width=line_width)

626

627 def render(self, next_text: Optional['Text'] = None, spacing: int = 0):

628 """

629 Render the text to an image.

630

631 Args:

632 next_text: The next Text object in the line (if any)

633 spacing: The spacing to the next text object

635 Returns:

636 A PIL Image containing the rendered text

637 """

638

639 style = self._style

640

641 # Draw the text background if specified

642 if style.background and style.background[3] > 0: # If alpha > 0 642 ↛ 643line 642 didn't jump to line 643 because the condition on line 642 was never true

643 self._draw.rectangle([tuple(self._origin), tuple(self._origin + self.size)],

644 fill=style.background)

645

646 # Draw the text using baseline as anchor point ("ls" = left-baseline)

647 # This ensures the origin represents the baseline, not the top-left

648 if not self._render_from_glyph_cache(style): 648 ↛ 649line 648 didn't jump to line 649 because the condition on line 648 was never true

649 self._draw.text(

650 (self.origin[0],

651 self._origin[1]),

652 self._text,

653 font=style.font,

654 fill=style.colour,

655 anchor="ls")

656

657 # Apply any text decorations with knowledge of next text

658 if style.decoration != TextDecoration.NONE:

659 self._apply_decoration(next_text, spacing)

660

661 def _render_from_glyph_cache(self, style) -> bool:

662 """

663 Blit this word from the cached glyph bitmap.

664

665 Rasterising a word is the single most expensive step in drawing a page, and

666 the same words recur constantly, so the bitmap PIL would produce is cached

667 and blitted directly. This reproduces what ImageDraw.text() does internally

668 (getmask2 followed by draw_bitmap) minus the per-call setup.

669

670 Returns:

671 True if the word was drawn. False means the caller must fall back to

672 ImageDraw.text().

673 """

674 global _glyph_fast_path_available

675

676 if not _glyph_fast_path_available: 676 ↛ 677line 676 didn't jump to line 677 because the condition on line 676 was never true

677 return False

679 draw = self._draw

680 font = style.font

681

682 # Bitmap and other non-FreeType fonts do not expose getmask2's anchor and

683 # sub-pixel arguments; let PIL handle them.

684 if not isinstance(font, ImageFont.FreeTypeFont): 684 ↛ 685line 684 didn't jump to line 685 because the condition on line 684 was never true

685 return False

686

687 try:

688 ink, _ = draw._getink(style.colour)

689 if ink is None: 689 ↛ 690line 689 didn't jump to line 690 because the condition on line 689 was never true

690 return False

692 # floor() rather than modf() so the fraction is always in [0, 1),

693 # keeping bucket indices non-negative for negative coordinates.

694 x = float(self._origin[0])

695 y = float(self._origin[1])

696 x_whole = math.floor(x)

697 y_whole = math.floor(y)

698

699 steps = _glyph_subpixel_steps

700 x_bucket = int((x - x_whole) * steps)

701 y_bucket = int((y - y_whole) * steps)

703 mode = draw.fontmode

704 key = (font, self._text, mode, ink, x_bucket, y_bucket)

706 entry = _glyph_cache.get(key)

707 if entry is None:

708 entry = font.getmask2(

709 self._text, mode, anchor="ls", ink=ink,

710 start=(x_bucket / steps, y_bucket / steps))

711 _glyph_cache.put(key, entry)

712

713 mask, offset = entry

714 draw.draw.draw_bitmap((x_whole + offset[0], y_whole + offset[1]), mask, ink)

715 return True

716

717 except AttributeError:

718 # A PIL build without the internals this path relies on. Stop trying.

719 logger.warning(

720 "Glyph cache unavailable for this Pillow build; falling back to "

721 "ImageDraw.text() for all text rendering.", exc_info=True)

722 _glyph_fast_path_available = False

723 return False

724 except (TypeError, ValueError):

725 # This particular colour/mode combination is not supported by the fast

726 # path (e.g. an ink PIL cannot resolve). Others may still be.

727 return False

728

729

730class Line(Box):

731 """

732 A line of text consisting of Text objects with consistent spacing.

733 Each Text represents a word or word fragment that can be rendered.

734 """

735

736 def __init__(self,

737 spacing: Tuple[int,

738 int],

739 origin,

740 size,

741 draw: ImageDraw.Draw,

742 font: Optional[Font] = None,

743 callback=None,

744 sheet=None,

745 mode=None,

746 halign=Alignment.CENTER,

747 valign=Alignment.CENTER,

748 previous=None,

749 min_word_length_for_brute_force: int = 8,

750 min_chars_before_hyphen: int = 2,

751 min_chars_after_hyphen: int = 2):

752 """

753 Initialize a new line.

754

755 Args:

756 spacing: A tuple of (min_spacing, max_spacing) between words

757 origin: The top-left position of the line

758 size: The width and height of the line

759 font: The default font to use for text in this line

760 callback: Optional callback function

761 sheet: Optional image sheet

762 mode: Optional image mode

763 halign: Horizontal alignment of text within the line

764 valign: Vertical alignment of text within the line

765 previous: Reference to the previous line

766 min_word_length_for_brute_force: Minimum word length to attempt brute force hyphenation (default: 8)

767 min_chars_before_hyphen: Minimum characters before hyphen in any split (default: 2)

768 min_chars_after_hyphen: Minimum characters after hyphen in any split (default: 2)

769 """

770 super().__init__(origin, size, callback, sheet, mode, halign, valign)

771 self._text_objects: List['Text'] = [] # Store Text objects directly

772 # Prefix sums of the widths in _text_objects, kept in step by _push_text /

773 # _pop_text. Element 0 is the empty sum. See _push_text for the rationale.

774 self._width_prefix: List[float] = [0.0]

775 self._spacing = spacing # (min_spacing, max_spacing)

776 self._font = font if font else Font() # Use default font if none provided

777 self._current_width = 0 # Track the current width used

778 self._words: List['Word'] = []

779 self._previous = previous

780 self._next = None

781 ascent, descent = self._font.font.getmetrics()

782 # Store baseline as offset from line origin (top), not absolute position

783 self._baseline = ascent

784 self._draw = draw

785 self._spacing_render = (spacing[0] + spacing[1]) // 2

786 self._position_render = 0

787

788 # The font's own space advance. Ragged alignments use this as their

789 # constant word gap rather than stretching to fill the measure.

790 self._natural_spacing = _space_advance(self._font.font)

791

792 # Hyphenation configuration parameters

793 self._min_word_length_for_brute_force = min_word_length_for_brute_force

794 self._min_chars_before_hyphen = min_chars_before_hyphen

795 self._min_chars_after_hyphen = min_chars_after_hyphen

796

797 # Create the appropriate alignment handler

798 self._alignment_handler = self._create_alignment_handler(halign)

799

800 # Set on the final line of a paragraph. Justification stretches a line to

801 # fill the column, which is wrong for the last line - a three-word tail

802 # would be spread across the full measure. The last line takes its

803 # natural width instead, as in every other typesetting system.

804 self._is_paragraph_end = False

805

806 @property

807 def is_paragraph_end(self) -> bool:

808 """Whether this is the final line of its paragraph"""

809 return self._is_paragraph_end

810

811 @is_paragraph_end.setter

812 def is_paragraph_end(self, value: bool):

813 self._is_paragraph_end = value

814

815 @property

816 def render_alignment_handler(self) -> AlignmentHandler:

817 """

818 The handler used to position text when rendering.

819

820 This differs from the fitting handler only for the last line of a

821 justified paragraph, which is rendered flush left.

822 """

823 if self._is_paragraph_end and isinstance(

824 self._alignment_handler, JustifyAlignmentHandler):

825 return LeftAlignmentHandler()

826 return self._alignment_handler

827

828 def _create_alignment_handler(self, alignment: Alignment) -> AlignmentHandler:

829 """

830 Create the appropriate alignment handler based on the alignment type.

831

832 Args:

833 alignment: The alignment type

834

835 Returns:

836 The appropriate alignment handler instance

837 """

838 if alignment == Alignment.LEFT:

839 return LeftAlignmentHandler()

840 elif alignment == Alignment.JUSTIFY:

841 return JustifyAlignmentHandler()

842 else: # CENTER or RIGHT

843 return CenterRightAlignmentHandler(alignment)

844

845 @property

846 def text_objects(self) -> List[Text]:

847 """Get the list of Text objects in this line"""

848 return self._text_objects

849

850 def set_next(self, line: Line):

851 """Set the next line in sequence"""

852 self._next = line

853

854 @property

855 def _content_width(self) -> float:

856 """Summed width of the line's current contents."""

857 return self._width_prefix[-1]

858

859 def _push_text(self, text: 'Text'):

860 """

861 Append a Text to the line, keeping the running width sum in step.

862

863 Fitting a word is a trial: the candidate is pushed, measured, and popped

864 again if it did not fit, so the line's contents churn far more often than

865 they grow. Tracking the sum here rather than re-adding every width on each

866 measurement is what keeps filling a line linear in its word count.

867

868 The sum is kept as a prefix list rather than as one accumulator that is

869 added to and subtracted from. Widths are floats, so `(total + w) - w` need

870 not give back `total` exactly, and a drift of one ulp is enough to flip an

871 overflow decision on a line that ends flush. Truncating a prefix list

872 restores the earlier total bit for bit, and each entry is built by the same

873 left-to-right addition sum() would perform.

874 """

875 self._text_objects.append(text)

876 self._width_prefix.append(self._width_prefix[-1] + text.width)

877

878 def _pop_text(self) -> 'Text':

879 """Remove the last Text from the line, keeping the width sum in step."""

880 text = self._text_objects.pop()

881 self._width_prefix.pop()

882 return text

883

884 def _measure(self, handler: Optional[AlignmentHandler] = None

885 ) -> Tuple[int, int, bool]:

886 """Ask an alignment handler to place the line's current contents."""

887 if handler is None:

888 handler = self._alignment_handler

889 return handler.calculate_spacing_and_position(

890 self._text_objects, self._size[0], self._spacing[0], self._spacing[1],

891 self._natural_spacing, self._content_width)

892

893 def add_word(self,

894 word: 'Word',

895 part: Optional[Text] = None) -> Tuple[bool,

896 Optional['Text']]:

897 """

898 Add a word to this line using intelligent word fitting strategies.

899

900 Args:

901 word: The word to add to the line

902 part: Optional pretext from a previous hyphenated word

903

904 Returns:

905 Tuple of (success, overflow_text):

906 - success: True if word/part was added, False if it couldn't fit

907 - overflow_text: Remaining text if word was hyphenated, None otherwise

908 """

909 # First, add any pretext from previous hyphenation

910 if part is not None:

911 self._push_text(part)

912 self._words.append(word)

913 part.add_line(self)

914

915 # Try to add the full word - create LinkText for LinkedWord, regular Text

916 # otherwise

917 if isinstance(word, LinkedWord):

918 # Import here to avoid circular dependency

919 from .functional import LinkText

920 # Create a LinkText which includes the link functionality

921 # LinkText constructor needs: (link, text, font, draw, source, line)

922 # But LinkedWord itself contains the link properties

923 # We'll create a Link object from the LinkedWord properties

924 link = Link(

925 location=word.location,

926 link_type=word.link_type,

927 callback=word.link_callback,

928 params=word.params,

929 title=word.link_title

930 )

931 text = LinkText(

932 link,

933 word.text,

934 word.style,

935 self._draw,

936 source=word,

937 line=self)

938 else:

939 text = Text.from_word(word, self._draw)

940 self._push_text(text)

941 spacing, position, overflow = self._measure()

942

943 if not overflow:

944 # Word fits! Add it completely

945 self._words.append(word)

946 word.add_concete(text)

947 text.add_line(self)

948 self._position_render = position

949 self._spacing_render = spacing

950 return True, None

951

952 # Word doesn't fit, remove it and try hyphenation

953 self._pop_text()

954

955 # Step 1: Try pyphen hyphenation

956 pyphen_splits = word.possible_hyphenation()

957 valid_splits = []

958

959 if pyphen_splits:

960 # Create Text objects for each possible split and check if they fit

961 for pair in pyphen_splits:

962 first_part_text = pair[0] + "-"

963 second_part_text = pair[1]

964

965 # Validate minimum character requirements

966 if len(pair[0]) < self._min_chars_before_hyphen: 966 ↛ 967line 966 didn't jump to line 967 because the condition on line 966 was never true

967 continue

968 if len(pair[1]) < self._min_chars_after_hyphen: 968 ↛ 969line 968 didn't jump to line 969 because the condition on line 968 was never true

969 continue

970

971 # Create Text objects

972 first_text = Text(

973 first_part_text,

974 word.style,

975 self._draw,

976 line=self,

977 source=word)

978 second_text = Text(

979 second_part_text,

980 word.style,

981 self._draw,

982 line=self,

983 source=word)

984

985 # Check if first part fits

986 self._push_text(first_text)

987 spacing, position, overflow = self._measure()

988 self._pop_text()

989

990 if not overflow:

991 # This split fits! Add it to valid options

992 valid_splits.append((first_text, second_text, spacing, position))

993

994 # Step 2: If we have valid pyphen splits, choose the best one

995 if valid_splits:

996 # Select the split with the best (minimum) spacing

997 best_split = min(valid_splits, key=lambda x: x[2])

998 first_text, second_text, spacing, position = best_split

999

1000 # Apply the split

1001 self._push_text(first_text)

1002 first_text.line = self

1003 word.add_concete((first_text, second_text))

1004 self._spacing_render = spacing

1005 self._position_render = position

1006 self._words.append(word)

1007 return True, second_text

1008

1009 # Step 3: Try brute force hyphenation (only for long words)

1010 if len(word.text) >= self._min_word_length_for_brute_force:

1011 # Calculate available space for the word

1012 word_length = self._content_width

1013 spacing_length = self._spacing[0] * max(0, len(self._text_objects) - 1)

1014 remaining = self._size[0] - word_length - spacing_length

1015

1016 if remaining > 0: 1016 ↛ 1073line 1016 didn't jump to line 1073 because the condition on line 1016 was always true

1017 # Create a hyphenated version to measure

1018 test_text = Text(word.text + "-", word.style, self._draw)

1019

1020 if test_text.width > 0: 1020 ↛ 1073line 1020 didn't jump to line 1073 because the condition on line 1020 was always true

1021 # Calculate what fraction of the hyphenated word fits

1022 fraction = remaining / test_text.width

1023

1024 # Convert fraction to character position

1025 # We need at least min_chars_before_hyphen and leave at least

1026 # min_chars_after_hyphen

1027 max_split_pos = len(word.text) - self._min_chars_after_hyphen

1028 min_split_pos = self._min_chars_before_hyphen

1029

1030 # Calculate ideal split position based on available space

1031 ideal_split = int(fraction * len(word.text))

1032 split_pos = max(min_split_pos, min(ideal_split, max_split_pos))

1033

1034 # Ensure we meet minimum requirements

1035 if (split_pos >= self._min_chars_before_hyphen and 1035 ↛ 1073line 1035 didn't jump to line 1073 because the condition on line 1035 was always true

1036 len(word.text) - split_pos >= self._min_chars_after_hyphen):

1037

1038 # Create the split

1039 first_part_text = word.text[:split_pos] + "-"

1040 second_part_text = word.text[split_pos:]

1041

1042 first_text = Text(

1043 first_part_text,

1044 word.style,

1045 self._draw,

1046 line=self,

1047 source=word)

1048 second_text = Text(

1049 second_part_text,

1050 word.style,

1051 self._draw,

1052 line=self,

1053 source=word)

1054

1055 # Verify the first part actually fits

1056 self._push_text(first_text)

1057 spacing, position, overflow = self._measure()

1058

1059 if not overflow:

1060 # Brute force split works!

1061 first_text.line = self

1062 second_text.line = self

1063 word.add_concete((first_text, second_text))

1064 self._spacing_render = spacing

1065 self._position_render = position

1066 self._words.append(word)

1067 return True, second_text

1068 else:

1069 # Doesn't fit, remove it

1070 self._pop_text()

1071

1072 # Step 4: Word cannot be hyphenated or split, move to next line

1073 return False, None

1074

1075 def render(self):

1076 """

1077 Render the line with all its text objects using the alignment handler system.

1078

1079 Returns:

1080 A PIL Image containing the rendered line

1081 """

1082 # Recalculate spacing and position for current text objects to ensure

1083 # accuracy. Word fitting used the paragraph's alignment; rendering uses

1084 # render_alignment_handler, which differs only for the last line of a

1085 # justified paragraph.

1086 handler = self.render_alignment_handler

1087 if len(self._text_objects) > 0:

1088 spacing, position, overflow = self._measure(handler)

1089 self._spacing_render = spacing

1090 self._position_render = position

1091

1092 y_cursor = self._origin[1] + self._baseline

1093

1094 # Start x_cursor at line origin plus any alignment offset

1095 x_cursor = self._origin[0] + self._position_render

1096

1097 # Everything the loop needs that does not vary per word is resolved once.

1098 # Only justified lines carry per-gap spacings; every other alignment uses

1099 # the single spacing figured above.

1100 texts = self._text_objects

1101 last = len(texts) - 1

1102 draw = self._draw

1103 default_spacing = self._spacing_render

1104 gaps = handler._gap_spacings if isinstance(handler, JustifyAlignmentHandler) else ()

1105 gap_count = len(gaps)

1106

1107 for i, text in enumerate(texts):

1108 # Update text draw context to current draw context

1109 text._draw = draw

1110 text.set_origin(np.array([x_cursor, y_cursor]))

1111

1112 # Determine next text object for continuous decoration

1113 next_text = texts[i + 1] if i < last else None

1114

1115 # Get the spacing for this specific gap (variable for justified text)

1116 current_spacing = gaps[i] if i < gap_count else default_spacing

1117

1118 # Render with next text information for continuous underline/strikethrough

1119 text.render(next_text, current_spacing)

1120 # Add text width, then spacing only if there are more words

1121 x_cursor += text.width

1122 if i < last:

1123 x_cursor += current_spacing

1124

1125 def query_point(self, point: Tuple[int, int]) -> Optional['QueryResult']:

1126 """

1127 Find which Text object contains the given point.

1128 Uses Queriable.in_object() mixin for hit-testing.

1129

1130 Args:

1131 point: (x, y) coordinates to query

1132

1133 Returns:

1134 QueryResult from the text object at that point, or None

1135 """

1136 point_array = np.array(point)

1137

1138 # Check each text object in this line

1139 for text_obj in self._text_objects:

1140 # Use Queriable mixin's in_object() for hit-testing

1141 if isinstance(text_obj, Queriable) and text_obj.in_object(point_array):

1142 # Extract metadata based on text type

1143 origin = text_obj._origin

1144 size = text_obj.size

1145

1146 # Text origin is at baseline (anchor="ls"), so visual top is origin[1] - ascent

1147 # Bounds should be (x, visual_top, width, height) for proper

1148 # highlighting

1149 visual_top = int(origin[1] - text_obj._ascent)

1150 bounds = (

1151 int(origin[0]),

1152 visual_top,

1153 int(size[0]) if hasattr(size, '__getitem__') else 0,

1154 int(size[1]) if hasattr(size, '__getitem__') else 0

1155 )

1156

1157 # Import here to avoid circular dependency

1158 from .functional import LinkText, ButtonText

1159

1160 if isinstance(text_obj, LinkText):

1161 result = QueryResult(

1162 object=text_obj,

1163 object_type="link",

1164 bounds=bounds,

1165 text=text_obj._text,

1166 is_interactive=True,

1167 link_target=text_obj._link.location if hasattr(

1168 text_obj,

1169 '_link') else None)

1170 elif isinstance(text_obj, ButtonText): 1170 ↛ 1171line 1170 didn't jump to line 1171 because the condition on line 1170 was never true

1171 result = QueryResult(

1172 object=text_obj,

1173 object_type="button",

1174 bounds=bounds,

1175 text=text_obj._text,

1176 is_interactive=True,

1177 callback=text_obj._callback if hasattr(

1178 text_obj,

1179 '_callback') else None)

1180 else:

1181 result = QueryResult(

1182 object=text_obj,

1183 object_type="text",

1184 bounds=bounds,

1185 text=text_obj._text if hasattr(text_obj, '_text') else None

1186 )

1187

1188 result.parent_line = self

1189 return result

1190

1191 return None

+ + + diff --git a/cov_info/htmlcov/z_af715639580e2d86___init___py.html b/cov_info/htmlcov/z_af715639580e2d86___init___py.html new file mode 100644 index 0000000..06a7d14 --- /dev/null +++ b/cov_info/htmlcov/z_af715639580e2d86___init___py.html @@ -0,0 +1,121 @@ + + + + + Coverage for pyWebLayout/abstract/__init__.py: 100% + + + + + +

+ Coverage for pyWebLayout/abstract/init.py: + 100% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 5 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Abstract layer for the pyWebLayout library.

4This package contains abstract representations of document elements that are

5independent of rendering specifics.

6"""

8from .inline import Word, FormattedSpan

9from .block import Paragraph, Heading, Image, HeadingLevel

10from .document import Document

11from .functional import LinkType

13__all__ = [

14 'Word',

15 'FormattedSpan',

16 'Paragraph',

17 'Heading',

18 'Image',

19 'HeadingLevel',

20 'Document',

21 'LinkType',

22]

+ + + diff --git a/cov_info/htmlcov/z_af715639580e2d86_block_py.html b/cov_info/htmlcov/z_af715639580e2d86_block_py.html new file mode 100644 index 0000000..43757b7 --- /dev/null +++ b/cov_info/htmlcov/z_af715639580e2d86_block_py.html @@ -0,0 +1,1514 @@ + + + + + Coverage for pyWebLayout/abstract/block.py: 80% + + + + + +

+ Coverage for pyWebLayout/abstract/block.py: + 80% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 489 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from typing import List, Iterator, Tuple, Dict, Optional, Any

2from enum import Enum

3import os

4import tempfile

5import urllib.request

6import urllib.parse

7from PIL import Image as PILImage

8from .inline import Word, FormattedSpan

9from ..core import Hierarchical, Styleable, FontRegistry, ContainerAware, BlockContainer

12class BlockType(Enum):

13 """Enumeration of different block types for classification purposes"""

14 PARAGRAPH = 1

15 HEADING = 2

16 QUOTE = 3

17 CODE_BLOCK = 4

18 LIST = 5

19 LIST_ITEM = 6

20 TABLE = 7

21 TABLE_ROW = 8

22 TABLE_CELL = 9

23 HORIZONTAL_RULE = 10

24 LINE_BREAK = 11

25 IMAGE = 12

26 PAGE_BREAK = 13

29class Block(Hierarchical):

30 """

31 Base class for all block-level elements.

32 Block elements typically represent visual blocks of content that stack vertically.

34 Uses Hierarchical mixin for parent-child relationship management.

35 """

37 def __init__(self, block_type: BlockType):

38 """

39 Initialize a block element.

41 Args:

42 block_type: The type of block this element represents

43 """

44 super().__init__()

45 self._block_type = block_type

47 @property

48 def block_type(self) -> BlockType:

49 """Get the type of this block element"""

50 return self._block_type

53class Paragraph(Styleable, FontRegistry, ContainerAware, Block):

54 """

55 A paragraph is a block-level element that contains a sequence of words.

57 Uses Styleable mixin for style property management.

58 Uses FontRegistry mixin for font caching with parent delegation.

59 """

61 def __init__(self, style=None):

62 """

63 Initialize an empty paragraph

65 Args:

66 style: Optional default style for words in this paragraph

67 """

68 super().__init__(style=style, block_type=BlockType.PARAGRAPH)

69 self._words: List[Word] = []

70 self._spans: List[FormattedSpan] = []

72 @classmethod

73 def create_and_add_to(cls, container, style=None) -> 'Paragraph':

74 """

75 Create a new Paragraph and add it to a container, inheriting style from

76 the container if not explicitly provided.

78 Args:

79 container: The container to add the paragraph to (must have add_block method and style property)

80 style: Optional style override. If None, inherits from container

82 Returns:

83 The newly created Paragraph object

85 Raises:

86 AttributeError: If the container doesn't have the required add_block method

87 """

88 # Validate container and inherit style using ContainerAware utilities

89 cls._validate_container(container)

90 style = cls._inherit_style(container, style)

92 # Create the new paragraph

93 paragraph = cls(style)

95 # Add the paragraph to the container

96 container.add_block(paragraph)

98 return paragraph

100 def add_word(self, word: Word):

101 """

102 Add a word to this paragraph.

104 Args:

105 word: The Word object to add

106 """

107 self._words.append(word)

109 def create_word(self, text: str, style=None, background=None) -> Word:

110 """

111 Create a new word and add it to this paragraph, inheriting paragraph's style if not specified.

113 This is a convenience method that uses Word.create_and_add_to() to create words

114 that automatically inherit styling from this paragraph.

116 Args:

117 text: The text content of the word

118 style: Optional Font style override. If None, attempts to inherit from paragraph

119 background: Optional background color override

121 Returns:

122 The newly created Word object

123 """

124 return Word.create_and_add_to(text, self, style, background)

126 def add_span(self, span: FormattedSpan):

127 """

128 Add a formatted span to this paragraph.

129

130 Args:

131 span: The FormattedSpan object to add

132 """

133 self._spans.append(span)

135 def create_span(self, style=None, background=None) -> FormattedSpan:

136 """

137 Create a new formatted span with inherited style.

139 Args:

140 style: Optional Font style override. If None, inherits from paragraph

141 background: Optional background color override

143 Returns:

144 The newly created FormattedSpan object

145 """

146 return FormattedSpan.create_and_add_to(self, style, background)

148 @property

149 def words(self) -> List[Word]:

150 """Get the list of words in this paragraph"""

151 return self._words

153 def words_iter(self) -> Iterator[Tuple[int, Word]]:

154 """

155 Iterate over the words in this paragraph.

157 Yields:

158 Tuples of (index, word) for each word in the paragraph

159 """

160 for i, word in enumerate(self._words):

161 yield i, word

162

163 def spans(self) -> Iterator[FormattedSpan]:

164 """

165 Iterate over the formatted spans in this paragraph.

166

167 Yields:

168 Each FormattedSpan in the paragraph

169 """

170 for span in self._spans:

171 yield span

172

173 @property

174 def word_count(self) -> int:

175 """Get the number of words in this paragraph"""

176 return len(self._words)

178 def __len__(self):

179 return self.word_count

181 # get_or_create_font() is provided by FontRegistry mixin

184class HeadingLevel(Enum):

185 """Enumeration representing HTML heading levels (h1-h6)"""

186 H1 = 1

187 H2 = 2

188 H3 = 3

189 H4 = 4

190 H5 = 5

191 H6 = 6

194class Heading(Paragraph):

195 """

196 A heading element (h1, h2, h3, etc.) that contains text with a specific heading level.

197 Headings inherit from Paragraph as they contain words but have additional properties.

198 """

200 def __init__(self, level: HeadingLevel = HeadingLevel.H1, style=None):

201 """

202 Initialize a heading element.

203

204 Args:

205 level: The heading level (h1-h6)

206 style: Optional default style for words in this heading

207 """

208 super().__init__(style)

209 self._block_type = BlockType.HEADING

210 self._level = level

212 @classmethod

213 def create_and_add_to(

214 cls,

215 container,

216 level: HeadingLevel = HeadingLevel.H1,

217 style=None) -> 'Heading':

218 """

219 Create a new Heading and add it to a container, inheriting style from

220 the container if not explicitly provided.

221

222 Args:

223 container: The container to add the heading to (must have add_block method and style property)

224 level: The heading level (h1-h6)

225 style: Optional style override. If None, inherits from container

227 Returns:

228 The newly created Heading object

230 Raises:

231 AttributeError: If the container doesn't have the required add_block method

232 """

233 # Validate container and inherit style using ContainerAware utilities

234 cls._validate_container(container)

235 style = cls._inherit_style(container, style)

237 # Create the new heading

238 heading = cls(level, style)

240 # Add the heading to the container

241 container.add_block(heading)

242

243 return heading

245 @property

246 def level(self) -> HeadingLevel:

247 """Get the heading level"""

248 return self._level

250 @level.setter

251 def level(self, level: HeadingLevel):

252 """Set the heading level"""

253 self._level = level

254

256class Quote(BlockContainer, ContainerAware, Block):

257 """

258 A blockquote element that can contain other block elements.

259 """

260

261 def __init__(self, style=None):

262 """

263 Initialize an empty blockquote

265 Args:

266 style: Optional default style for child blocks

267 """

268 super().__init__(BlockType.QUOTE)

269 self._style = style

271 @classmethod

272 def create_and_add_to(cls, container, style=None) -> 'Quote':

273 """

274 Create a new Quote and add it to a container, inheriting style from

275 the container if not explicitly provided.

277 Args:

278 container: The container to add the quote to (must have add_block method and style property)

279 style: Optional style override. If None, inherits from container

281 Returns:

282 The newly created Quote object

284 Raises:

285 AttributeError: If the container doesn't have the required add_block method

286 """

287 # Validate container and inherit style using ContainerAware utilities

288 cls._validate_container(container)

289 style = cls._inherit_style(container, style)

290

291 # Create the new quote

292 quote = cls(style)

293

294 # Add the quote to the container

295 container.add_block(quote)

297 return quote

299 @property

300 def style(self):

301 """Get the default style for this quote"""

302 return self._style

304 @style.setter

305 def style(self, style):

306 """Set the default style for this quote"""

307 self._style = style

310class CodeBlock(Block):

311 """

312 A code block element containing pre-formatted text with syntax highlighting.

313 """

314

315 def __init__(self, language: str = ""):

316 """

317 Initialize a code block.

319 Args:

320 language: The programming language for syntax highlighting

321 """

322 super().__init__(BlockType.CODE_BLOCK)

323 self._language = language

324 self._lines: List[str] = []

325

326 @classmethod

327 def create_and_add_to(cls, container, language: str = "") -> 'CodeBlock':

328 """

329 Create a new CodeBlock and add it to a container.

331 Args:

332 container: The container to add the code block to (must have add_block method)

333 language: The programming language for syntax highlighting

335 Returns:

336 The newly created CodeBlock object

338 Raises:

339 AttributeError: If the container doesn't have the required add_block method

340 """

341 # Create the new code block

342 code_block = cls(language)

344 # Add the code block to the container

345 if hasattr(container, 'add_block'):

346 container.add_block(code_block)

347 else:

348 raise AttributeError(

349 f"Container {type(container).__name__} must have an 'add_block' method"

350 )

351

352 return code_block

353

354 @property

355 def language(self) -> str:

356 """Get the programming language"""

357 return self._language

359 @language.setter

360 def language(self, language: str):

361 """Set the programming language"""

362 self._language = language

364 def add_line(self, line: str):

365 """

366 Add a line of code to this code block.

368 Args:

369 line: The line of code to add

370 """

371 self._lines.append(line)

373 def lines(self) -> Iterator[Tuple[int, str]]:

374 """

375 Iterate over the lines in this code block.

376

377 Yields:

378 Tuples of (line_number, line_text) for each line

379 """

380 for i, line in enumerate(self._lines):

381 yield i, line

383 @property

384 def line_count(self) -> int:

385 """Get the number of lines in this code block"""

386 return len(self._lines)

388

389class ListStyle(Enum):

390 """Enumeration of list styles"""

391 UNORDERED = 1 # <ul>

392 ORDERED = 2 # <ol>

393 DEFINITION = 3 # <dl>

396class HList(ContainerAware, Block):

397 """

398 An HTML list element (ul, ol, dl).

399 """

400

401 def __init__(self, style: ListStyle = ListStyle.UNORDERED, default_style=None):

402 """

403 Initialize a list.

405 Args:

406 style: The style of list (unordered, ordered, definition)

407 default_style: Optional default style for child items

408 """

409 super().__init__(BlockType.LIST)

410 self._style = style

411 self._items: List[ListItem] = []

412 self._default_style = default_style

414 @classmethod

415 def create_and_add_to(

416 cls,

417 container,

418 style: ListStyle = ListStyle.UNORDERED,

419 default_style=None) -> 'HList':

420 """

421 Create a new HList and add it to a container, inheriting style from

422 the container if not explicitly provided.

423

424 Args:

425 container: The container to add the list to (must have add_block method)

426 style: The style of list (unordered, ordered, definition)

427 default_style: Optional default style for child items. If None, inherits from container

428

429 Returns:

430 The newly created HList object

432 Raises:

433 AttributeError: If the container doesn't have the required add_block method

434 """

435 # Validate container and inherit style using ContainerAware utilities

436 cls._validate_container(container)

437 default_style = cls._inherit_style(container, default_style)

438

439 # Create the new list

440 hlist = cls(style, default_style)

442 # Add the list to the container

443 container.add_block(hlist)

444

445 return hlist

447 @property

448 def style(self) -> ListStyle:

449 """Get the list style"""

450 return self._style

452 @style.setter

453 def style(self, style: ListStyle):

454 """Set the list style"""

455 self._style = style

457 @property

458 def default_style(self):

459 """Get the default style for list items"""

460 return self._default_style

461

462 @default_style.setter

463 def default_style(self, style):

464 """Set the default style for list items"""

465 self._default_style = style

466

467 def add_item(self, item: 'ListItem'):

468 """

469 Add an item to this list.

470

471 Args:

472 item: The ListItem to add

473 """

474 self._items.append(item)

475 item.parent = self

476

477 def create_item(self, term: Optional[str] = None, style=None) -> 'ListItem':

478 """

479 Create a new list item and add it to this list.

481 Args:

482 term: Optional term for definition lists

483 style: Optional style override. If None, inherits from list

484

485 Returns:

486 The newly created ListItem object

487 """

488 return ListItem.create_and_add_to(self, term, style)

489

490 def items(self) -> Iterator['ListItem']:

491 """

492 Iterate over the items in this list.

493

494 Yields:

495 Each ListItem in the list

496 """

497 for item in self._items:

498 yield item

499

500 @property

501 def item_count(self) -> int:

502 """Get the number of items in this list"""

503 return len(self._items)

504

506class ListItem(BlockContainer, ContainerAware, Block):

507 """

508 A list item element that can contain other block elements.

509 """

510

511 def __init__(self, term: Optional[str] = None, style=None):

512 """

513 Initialize a list item.

514

515 Args:

516 term: Optional term for definition lists (dt element)

517 style: Optional default style for child blocks

518 """

519 super().__init__(BlockType.LIST_ITEM)

520 self._term = term

521 self._style = style

522

523 @classmethod

524 def create_and_add_to(

525 cls,

526 container,

527 term: Optional[str] = None,

528 style=None) -> 'ListItem':

529 """

530 Create a new ListItem and add it to a container, inheriting style from

531 the container if not explicitly provided.

532

533 Args:

534 container: The container to add the list item to (must have add_item method)

535 term: Optional term for definition lists (dt element)

536 style: Optional style override. If None, inherits from container

538 Returns:

539 The newly created ListItem object

540

541 Raises:

542 AttributeError: If the container doesn't have the required add_item method

543 """

544 # Validate container and inherit style using ContainerAware utilities

545 cls._validate_container(container, required_method='add_item')

546 style = cls._inherit_style(container, style)

547

548 # Create the new list item

549 item = cls(term, style)

550

551 # Add the list item to the container

552 container.add_item(item)

553

554 return item

555

556 @property

557 def term(self) -> Optional[str]:

558 """Get the definition term (for definition lists)"""

559 return self._term

560

561 @term.setter

562 def term(self, term: str):

563 """Set the definition term"""

564 self._term = term

565

566 @property

567 def style(self):

568 """Get the default style for this list item"""

569 return self._style

570

571 @style.setter

572 def style(self, style):

573 """Set the default style for this list item"""

574 self._style = style

576

577class TableCell(BlockContainer, ContainerAware, Block):

578 """

579 A table cell element that can contain other block elements.

580 """

581

582 def __init__(

583 self,

584 is_header: bool = False,

585 colspan: int = 1,

586 rowspan: int = 1,

587 style=None):

588 """

589 Initialize a table cell.

590

591 Args:

592 is_header: Whether this cell is a header cell (th) or data cell (td)

593 colspan: Number of columns this cell spans

594 rowspan: Number of rows this cell spans

595 style: Optional default style for child blocks

596 """

597 super().__init__(BlockType.TABLE_CELL)

598 self._is_header = is_header

599 self._colspan = colspan

600 self._rowspan = rowspan

601 self._style = style

602

603 @classmethod

604 def create_and_add_to(cls, container, is_header: bool = False, colspan: int = 1,

605 rowspan: int = 1, style=None) -> 'TableCell':

606 """

607 Create a new TableCell and add it to a container, inheriting style from

608 the container if not explicitly provided.

609

610 Args:

611 container: The container to add the cell to (must have add_cell method)

612 is_header: Whether this cell is a header cell (th) or data cell (td)

613 colspan: Number of columns this cell spans

614 rowspan: Number of rows this cell spans

615 style: Optional style override. If None, inherits from container

616

617 Returns:

618 The newly created TableCell object

619

620 Raises:

621 AttributeError: If the container doesn't have the required add_cell method

622 """

623 # Validate container and inherit style using ContainerAware utilities

624 cls._validate_container(container, required_method='add_cell')

625 style = cls._inherit_style(container, style)

626

627 # Create the new table cell

628 cell = cls(is_header, colspan, rowspan, style)

629

630 # Add the cell to the container

631 container.add_cell(cell)

632

633 return cell

635 @property

636 def is_header(self) -> bool:

637 """Check if this is a header cell"""

638 return self._is_header

639

640 @is_header.setter

641 def is_header(self, is_header: bool):

642 """Set whether this is a header cell"""

643 self._is_header = is_header

644

645 @property

646 def colspan(self) -> int:

647 """Get the column span"""

648 return self._colspan

649

650 @colspan.setter

651 def colspan(self, colspan: int):

652 """Set the column span"""

653 self._colspan = max(1, colspan) # Ensure minimum of 1

654

655 @property

656 def rowspan(self) -> int:

657 """Get the row span"""

658 return self._rowspan

659

660 @rowspan.setter

661 def rowspan(self, rowspan: int):

662 """Set the row span"""

663 self._rowspan = max(1, rowspan) # Ensure minimum of 1

664

665 @property

666 def style(self):

667 """Get the default style for this table cell"""

668 return self._style

669

670 @style.setter

671 def style(self, style):

672 """Set the default style for this table cell"""

673 self._style = style

674

675

676class TableRow(ContainerAware, Block):

677 """

678 A table row element containing table cells.

679 """

680

681 def __init__(self, style=None):

682 """

683 Initialize an empty table row

684

685 Args:

686 style: Optional default style for child cells

687 """

688 super().__init__(BlockType.TABLE_ROW)

689 self._cells: List[TableCell] = []

690 self._style = style

692 @classmethod

693 def create_and_add_to(

694 cls,

695 container,

696 section: str = "body",

697 style=None) -> 'TableRow':

698 """

699 Create a new TableRow and add it to a container, inheriting style from

700 the container if not explicitly provided.

701

702 Args:

703 container: The container to add the row to (must have add_row method)

704 section: The section to add the row to ("header", "body", or "footer")

705 style: Optional style override. If None, inherits from container

706

707 Returns:

708 The newly created TableRow object

709

710 Raises:

711 AttributeError: If the container doesn't have the required add_row method

712 """

713 # Validate container and inherit style using ContainerAware utilities

714 cls._validate_container(container, required_method='add_row')

715 style = cls._inherit_style(container, style)

716

717 # Create the new table row

718 row = cls(style)

719

720 # Add the row to the container

721 container.add_row(row, section)

722

723 return row

724

725 @property

726 def style(self):

727 """Get the default style for this table row"""

728 return self._style

729

730 @style.setter

731 def style(self, style):

732 """Set the default style for this table row"""

733 self._style = style

734

735 def add_cell(self, cell: TableCell):

736 """

737 Add a cell to this row.

738

739 Args:

740 cell: The TableCell to add

741 """

742 self._cells.append(cell)

743 cell.parent = self

744

745 def create_cell(

746 self,

747 is_header: bool = False,

748 colspan: int = 1,

749 rowspan: int = 1,

750 style=None) -> TableCell:

751 """

752 Create a new table cell and add it to this row.

753

754 Args:

755 is_header: Whether this cell is a header cell

756 colspan: Number of columns this cell spans

757 rowspan: Number of rows this cell spans

758 style: Optional style override. If None, inherits from row

759

760 Returns:

761 The newly created TableCell object

762 """

763 return TableCell.create_and_add_to(self, is_header, colspan, rowspan, style)

764

765 def cells(self) -> Iterator[TableCell]:

766 """

767 Iterate over the cells in this row.

768

769 Yields:

770 Each TableCell in the row

771 """

772 for cell in self._cells:

773 yield cell

774

775 @property

776 def cell_count(self) -> int:

777 """Get the number of cells in this row"""

778 return len(self._cells)

779

780

781class Table(ContainerAware, Block):

782 """

783 A table element containing rows and cells.

784 """

785

786 def __init__(self, caption: Optional[str] = None, style=None):

787 """

788 Initialize a table.

789

790 Args:

791 caption: Optional caption for the table

792 style: Optional default style for child rows

793 """

794 super().__init__(BlockType.TABLE)

795 self._caption = caption

796 self._rows: List[TableRow] = []

797 self._header_rows: List[TableRow] = []

798 self._footer_rows: List[TableRow] = []

799 self._style = style

800

801 @classmethod

802 def create_and_add_to(

803 cls,

804 container,

805 caption: Optional[str] = None,

806 style=None) -> 'Table':

807 """

808 Create a new Table and add it to a container, inheriting style from

809 the container if not explicitly provided.

810

811 Args:

812 container: The container to add the table to (must have add_block method)

813 caption: Optional caption for the table

814 style: Optional style override. If None, inherits from container

815

816 Returns:

817 The newly created Table object

818

819 Raises:

820 AttributeError: If the container doesn't have the required add_block method

821 """

822 # Validate container and inherit style using ContainerAware utilities

823 cls._validate_container(container)

824 style = cls._inherit_style(container, style)

825

826 # Create the new table

827 table = cls(caption, style)

828

829 # Add the table to the container

830 container.add_block(table)

831

832 return table

833

834 @property

835 def caption(self) -> Optional[str]:

836 """Get the table caption"""

837 return self._caption

838

839 @caption.setter

840 def caption(self, caption: Optional[str]):

841 """Set the table caption"""

842 self._caption = caption

843

844 @property

845 def style(self):

846 """Get the default style for this table"""

847 return self._style

848

849 @style.setter

850 def style(self, style):

851 """Set the default style for this table"""

852 self._style = style

853

854 def add_row(self, row: TableRow, section: str = "body"):

855 """

856 Add a row to this table.

857

858 Args:

859 row: The TableRow to add

860 section: The section to add the row to ("header", "body", or "footer")

861 """

862 row.parent = self

863

864 if section.lower() == "header":

865 self._header_rows.append(row)

866 elif section.lower() == "footer":

867 self._footer_rows.append(row)

868 else: # Default to body

869 self._rows.append(row)

870

871 def create_row(self, section: str = "body", style=None) -> TableRow:

872 """

873 Create a new table row and add it to this table.

874

875 Args:

876 section: The section to add the row to ("header", "body", or "footer")

877 style: Optional style override. If None, inherits from table

878

879 Returns:

880 The newly created TableRow object

881 """

882 return TableRow.create_and_add_to(self, section, style)

883

884 def header_rows(self) -> Iterator[TableRow]:

885 """

886 Iterate over the header rows in this table.

887

888 Yields:

889 Each TableRow in the header section

890 """

891 for row in self._header_rows:

892 yield row

893

894 def body_rows(self) -> Iterator[TableRow]:

895 """

896 Iterate over the body rows in this table.

897

898 Yields:

899 Each TableRow in the body section

900 """

901 for row in self._rows:

902 yield row

903

904 def footer_rows(self) -> Iterator[TableRow]:

905 """

906 Iterate over the footer rows in this table.

907

908 Yields:

909 Each TableRow in the footer section

910 """

911 for row in self._footer_rows:

912 yield row

913

914 def all_rows(self) -> Iterator[Tuple[str, TableRow]]:

915 """

916 Iterate over all rows in this table with their section labels.

917

918 Yields:

919 Tuples of (section, row) for each row in the table

920 """

921 for row in self._header_rows:

922 yield ("header", row)

923 for row in self._rows:

924 yield ("body", row)

925 for row in self._footer_rows:

926 yield ("footer", row)

927

928 @property

929 def row_count(self) -> Dict[str, int]:

930 """Get the row counts by section"""

931 return {

932 "header": len(self._header_rows),

933 "body": len(self._rows),

934 "footer": len(self._footer_rows),

935 "total": len(self._header_rows) + len(self._rows) + len(self._footer_rows)

936 }

937

938

939class Image(Block):

940 """

941 An image element with source, dimensions, and alternative text.

942 """

943

944 def __init__(

945 self,

946 source: str = "",

947 alt_text: str = "",

948 width: Optional[int] = None,

949 height: Optional[int] = None):

950 """

951 Initialize an image element.

952

953 Args:

954 source: The image source URL or path

955 alt_text: Alternative text for accessibility

956 width: Optional image width in pixels

957 height: Optional image height in pixels

958 """

959 super().__init__(BlockType.IMAGE)

960 self._source = source

961 self._alt_text = alt_text

962 self._width = width

963 self._height = height

964

965 @classmethod

966 def create_and_add_to(

967 cls,

968 container,

969 source: str = "",

970 alt_text: str = "",

971 width: Optional[int] = None,

972 height: Optional[int] = None) -> 'Image':

973 """

974 Create a new Image and add it to a container.

975

976 Args:

977 container: The container to add the image to (must have add_block method)

978 source: The image source URL or path

979 alt_text: Alternative text for accessibility

980 width: Optional image width in pixels

981 height: Optional image height in pixels

982

983 Returns:

984 The newly created Image object

985

986 Raises:

987 AttributeError: If the container doesn't have the required add_block method

988 """

989 # Create the new image

990 image = cls(source, alt_text, width, height)

991

992 # Add the image to the container

993 if hasattr(container, 'add_block'):

994 container.add_block(image)

995 else:

996 raise AttributeError(

997 f"Container {type(container).__name__} must have an 'add_block' method"

998 )

999

1000 return image

1001

1002 @property

1003 def source(self) -> str:

1004 """Get the image source"""

1005 return self._source

1006

1007 @source.setter

1008 def source(self, source: str):

1009 """Set the image source"""

1010 self._source = source

1011

1012 @property

1013 def alt_text(self) -> str:

1014 """Get the alternative text"""

1015 return self._alt_text

1016

1017 @alt_text.setter

1018 def alt_text(self, alt_text: str):

1019 """Set the alternative text"""

1020 self._alt_text = alt_text

1021

1022 @property

1023 def width(self) -> Optional[int]:

1024 """Get the image width"""

1025 return self._width

1026

1027 @width.setter

1028 def width(self, width: Optional[int]):

1029 """Set the image width"""

1030 self._width = width

1031

1032 @property

1033 def height(self) -> Optional[int]:

1034 """Get the image height"""

1035 return self._height

1036

1037 @height.setter

1038 def height(self, height: Optional[int]):

1039 """Set the image height"""

1040 self._height = height

1041

1042 def get_dimensions(self) -> Tuple[Optional[int], Optional[int]]:

1043 """

1044 Get the image dimensions as a tuple.

1045

1046 Returns:

1047 Tuple of (width, height)

1048 """

1049 return (self._width, self._height)

1050

1051 def get_aspect_ratio(self) -> Optional[float]:

1052 """

1053 Calculate the aspect ratio of the image.

1054

1055 Returns:

1056 The aspect ratio (width/height) or None if either dimension is missing

1057 """

1058 if self._width is not None and self._height is not None and self._height > 0:

1059 return self._width / self._height

1060 return None

1061

1062 def calculate_scaled_dimensions(self,

1063 max_width: Optional[int] = None,

1064 max_height: Optional[int] = None) -> Tuple[Optional[int],

1065 Optional[int]]:

1066 """

1067 Calculate scaled dimensions that fit within the given constraints.

1068

1069 Args:

1070 max_width: Maximum allowed width

1071 max_height: Maximum allowed height

1072

1073 Returns:

1074 Tuple of (scaled_width, scaled_height)

1075 """

1076 if self._width is None or self._height is None:

1077 return (self._width, self._height)

1078

1079 width, height = self._width, self._height

1080

1081 # Scale down if needed

1082 if max_width is not None and width > max_width:

1083 height = int(height * max_width / width)

1084 width = max_width

1085

1086 if max_height is not None and height > max_height: 1086 ↛ 1087line 1086 didn't jump to line 1087 because the condition on line 1086 was never true

1087 width = int(width * max_height / height)

1088 height = max_height

1089

1090 return (width, height)

1091

1092 def _is_url(self, source: str) -> bool:

1093 """

1094 Check if the source is a URL.

1095

1096 Args:

1097 source: The source string to check

1098

1099 Returns:

1100 True if the source appears to be a URL, False otherwise

1101 """

1102 parsed = urllib.parse.urlparse(source)

1103 return bool(parsed.scheme and parsed.netloc)

1104

1105 def _download_to_temp(self, url: str) -> str:

1106 """

1107 Download an image from a URL to a temporary file.

1108

1109 Args:

1110 url: The URL to download from

1111

1112 Returns:

1113 Path to the temporary file

1114

1115 Raises:

1116 urllib.error.URLError: If the download fails

1117 """

1118 # Create a temporary file

1119 temp_fd, temp_path = tempfile.mkstemp(suffix='.tmp')

1120

1121 try:

1122 # Download the image

1123 with urllib.request.urlopen(url) as response:

1124 # Write the response data to the temporary file

1125 with os.fdopen(temp_fd, 'wb') as temp_file:

1126 temp_file.write(response.read())

1127

1128 return temp_path

1129 except BaseException:

1130 # Clean up the temporary file if download fails

1131 try:

1132 os.close(temp_fd)

1133 except BaseException:

1134 pass

1135 try:

1136 os.unlink(temp_path)

1137 except BaseException:

1138 pass

1139 raise

1140

1141 def load_image_data(self,

1142 auto_update_dimensions: bool = True) -> Tuple[Optional[str],

1143 Optional[PILImage.Image]]:

1144 """

1145 Load image data using PIL, handling both local files and URLs.

1146

1147 Args:

1148 auto_update_dimensions: If True, automatically update width and height from the loaded image

1149

1150 Returns:

1151 Tuple of (file_path, PIL_Image_object). For URLs, file_path is the temporary file path.

1152 Returns (None, None) if loading fails.

1153 """

1154 if not self._source:

1155 return None, None

1156

1157 file_path = None

1158 temp_file = None

1159

1160 try:

1161 if self._is_url(self._source):

1162 # Download to temporary file

1163 temp_file = self._download_to_temp(self._source)

1164 file_path = temp_file

1165 else:

1166 # Use local file path

1167 file_path = self._source

1168

1169 # Open with PIL

1170 with PILImage.open(file_path) as img:

1171 # Load the image data

1172 img.load()

1173

1174 # Update dimensions if requested

1175 if auto_update_dimensions:

1176 self._width, self._height = img.size

1177

1178 # Return a copy to avoid issues with the context manager

1179 return file_path, img.copy()

1180

1181 except Exception:

1182 # Clean up temporary file on error

1183 if temp_file and os.path.exists(temp_file): 1183 ↛ 1184line 1183 didn't jump to line 1184 because the condition on line 1183 was never true

1184 try:

1185 os.unlink(temp_file)

1186 except BaseException:

1187 pass

1188 return None, None

1189

1190 def get_image_info(self) -> Dict[str, Any]:

1191 """

1192 Get detailed information about the image using PIL.

1193

1194 Returns:

1195 Dictionary containing image information including format, mode, size, etc.

1196 Returns empty dict if image cannot be loaded.

1197 """

1198 file_path, img = self.load_image_data(auto_update_dimensions=False)

1199

1200 if img is None:

1201 return {}

1202

1203 # Try to determine format from the image, file extension, or source

1204 img_format = img.format

1205 if img_format is None: 1205 ↛ 1229line 1205 didn't jump to line 1229 because the condition on line 1205 was always true

1206 # Try to determine format from file extension

1207 format_map = {

1208 '.jpg': 'JPEG',

1209 '.jpeg': 'JPEG',

1210 '.png': 'PNG',

1211 '.gif': 'GIF',

1212 '.bmp': 'BMP',

1213 '.tiff': 'TIFF',

1214 '.tif': 'TIFF'

1215 }

1216

1217 # First try the actual file path if available

1218 if file_path: 1218 ↛ 1223line 1218 didn't jump to line 1223 because the condition on line 1218 was always true

1219 ext = os.path.splitext(file_path)[1].lower()

1220 img_format = format_map.get(ext)

1221

1222 # If still no format and we have a URL source, try the original URL

1223 if img_format is None and self._is_url(self._source):

1224 ext = os.path.splitext(

1225 urllib.parse.urlparse(

1226 self._source).path)[1].lower()

1227 img_format = format_map.get(ext)

1228

1229 info = {

1230 'format': img_format,

1231 'mode': img.mode,

1232 'size': img.size,

1233 'width': img.width,

1234 'height': img.height,

1235 }

1236

1237 # Add additional info if available

1238 if hasattr(img, 'info'): 1238 ↛ 1242line 1238 didn't jump to line 1242 because the condition on line 1238 was always true

1239 info['info'] = img.info

1240

1241 # Clean up temporary file if it was created

1242 if file_path and self._is_url(self._source):

1243 try:

1244 os.unlink(file_path)

1245 except BaseException:

1246 pass

1247

1248 return info

1249

1250

1251class LinkedImage(Image):

1252 """

1253 An Image that is also a Link - clickable images that navigate or trigger callbacks.

1254 """

1255

1256 def __init__(self, source: str, alt_text: str, location: str,

1257 width: Optional[int] = None, height: Optional[int] = None,

1258 link_type=None,

1259 callback: Optional[Any] = None,

1260 params: Optional[Dict[str, Any]] = None,

1261 title: Optional[str] = None):

1262 """

1263 Initialize a linked image.

1264

1265 Args:

1266 source: The image source URL or path

1267 alt_text: Alternative text for accessibility

1268 location: The link target (URL, bookmark, etc.)

1269 width: Optional image width in pixels

1270 height: Optional image height in pixels

1271 link_type: Type of link (INTERNAL, EXTERNAL, etc.)

1272 callback: Optional callback for link activation

1273 params: Parameters for the link

1274 title: Tooltip/title for the link

1275 """

1276 # Initialize Image

1277 super().__init__(source, alt_text, width, height)

1278

1279 # Store link properties

1280 # Import here to avoid circular imports at module level

1281 from pyWebLayout.abstract.functional import LinkType

1282 self._location = location

1283 self._link_type = link_type or LinkType.EXTERNAL

1284 self._callback = callback

1285 self._params = params or {}

1286 self._link_title = title

1287

1288 @property

1289 def location(self) -> str:

1290 """Get the link target location"""

1291 return self._location

1292

1293 @property

1294 def link_type(self):

1295 """Get the type of link"""

1296 return self._link_type

1297

1298 @property

1299 def link_callback(self) -> Optional[Any]:

1300 """Get the link callback"""

1301 return self._callback

1302

1303 @property

1304 def params(self) -> Dict[str, Any]:

1305 """Get the link parameters"""

1306 return self._params

1307

1308 @property

1309 def link_title(self) -> Optional[str]:

1310 """Get the link title/tooltip"""

1311 return self._link_title

1312

1313 def execute_link(self, context: Optional[Dict[str, Any]] = None) -> Any:

1314 """

1315 Execute the link action.

1316

1317 Args:

1318 context: Optional context dict (e.g., {'alt_text': image.alt_text})

1319

1320 Returns:

1321 The result of the link execution

1322 """

1323 from pyWebLayout.abstract.functional import LinkType

1324

1325 # Add image info to context

1326 full_context = {

1327 **self._params,

1328 'alt_text': self._alt_text,

1329 'source': self._source}

1330 if context: 1330 ↛ 1331line 1330 didn't jump to line 1331 because the condition on line 1330 was never true

1331 full_context.update(context)

1332

1333 if self._link_type in (LinkType.API, LinkType.FUNCTION) and self._callback:

1334 return self._callback(self._location, **full_context)

1335 else:

1336 # For INTERNAL and EXTERNAL links, return the location

1337 return self._location

1338

1339

1340class HorizontalRule(Block):

1341 """

1342 A horizontal rule element (hr tag).

1343 """

1344

1345 def __init__(self):

1346 """Initialize a horizontal rule element."""

1347 super().__init__(BlockType.HORIZONTAL_RULE)

1348

1349 @classmethod

1350 def create_and_add_to(cls, container) -> 'HorizontalRule':

1351 """

1352 Create a new HorizontalRule and add it to a container.

1353

1354 Args:

1355 container: The container to add the horizontal rule to (must have add_block method)

1356

1357 Returns:

1358 The newly created HorizontalRule object

1359

1360 Raises:

1361 AttributeError: If the container doesn't have the required add_block method

1362 """

1363 # Create the new horizontal rule

1364 hr = cls()

1365

1366 # Add the horizontal rule to the container

1367 if hasattr(container, 'add_block'):

1368 container.add_block(hr)

1369 else:

1370 raise AttributeError(

1371 f"Container {type(container).__name__} must have an 'add_block' method"

1372 )

1373

1374 return hr

1375

1376

1377class PageBreak(Block):

1378 """

1379 A page break element that forces content to start on a new page.

1380

1381 When encountered during layout, this block signals that all subsequent

1382 content should be placed on a new page, even if the current page has

1383 available space.

1384 """

1385

1386 def __init__(self):

1387 """Initialize a page break element."""

1388 super().__init__(BlockType.PAGE_BREAK)

1389

1390 @classmethod

1391 def create_and_add_to(cls, container) -> 'PageBreak':

1392 """

1393 Create a new PageBreak and add it to a container.

1394

1395 Args:

1396 container: The container to add the page break to (must have add_block method)

1397

1398 Returns:

1399 The newly created PageBreak object

1400

1401 Raises:

1402 AttributeError: If the container doesn't have the required add_block method

1403 """

1404 # Create the new page break

1405 page_break = cls()

1406

1407 # Add the page break to the container

1408 if hasattr(container, 'add_block'):

1409 container.add_block(page_break)

1410 else:

1411 raise AttributeError(

1412 f"Container {type(container).__name__} must have an 'add_block' method"

1413 )

1414

1415 return page_break

+ + + diff --git a/cov_info/htmlcov/z_af715639580e2d86_document_py.html b/cov_info/htmlcov/z_af715639580e2d86_document_py.html new file mode 100644 index 0000000..abbc1d6 --- /dev/null +++ b/cov_info/htmlcov/z_af715639580e2d86_document_py.html @@ -0,0 +1,694 @@ + + + + + Coverage for pyWebLayout/abstract/document.py: 78% + + + + + +

+ Coverage for pyWebLayout/abstract/document.py: + 78% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 194 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

2from typing import List, Dict, Optional, Tuple, Union, Any

3from enum import Enum

4from .block import Block, BlockType, Heading, HeadingLevel, Paragraph

5from ..style import Font, FontWeight, FontStyle, TextDecoration

6from ..style.abstract_style import AbstractStyle, AbstractStyleRegistry, FontFamily, FontSize

7from ..style.concrete_style import ConcreteStyleRegistry, RenderingContext, StyleResolver

8from ..core import FontRegistry, MetadataContainer

11class MetadataType(Enum):

12 """Types of metadata that can be associated with a document"""

13 TITLE = 1

14 AUTHOR = 2

15 DESCRIPTION = 3

16 KEYWORDS = 4

17 LANGUAGE = 5

18 PUBLICATION_DATE = 6

19 MODIFIED_DATE = 7

20 PUBLISHER = 8

21 IDENTIFIER = 9

22 COVER_IMAGE = 10

23 CUSTOM = 100

26class Document(FontRegistry, MetadataContainer):

27 """

28 Abstract representation of a complete document like an HTML page or an ebook.

29 This class manages the logical structure of the document without rendering concerns.

31 Uses FontRegistry mixin for font caching.

32 Uses MetadataContainer mixin for metadata management.

33 """

35 def __init__(

36 self,

37 title: Optional[str] = None,

38 language: str = "en-US",

39 default_style=None):

40 """

41 Initialize a new document.

43 Args:

44 title: The document title

45 language: The document language code

46 default_style: Optional default style for child blocks

47 """

48 super().__init__()

49 self._blocks: List[Block] = []

50 self._anchors: Dict[str, Block] = {} # Named anchors for navigation

51 self._resources: Dict[str, Any] = {} # External resources like images

52 self._stylesheets: List[Dict[str, Any]] = [] # CSS stylesheets

53 self._scripts: List[str] = [] # JavaScript code

55 # Style management with new abstract/concrete system

56 self._abstract_style_registry = AbstractStyleRegistry()

57 self._rendering_context = RenderingContext(default_language=language)

58 self._style_resolver = StyleResolver(self._rendering_context)

59 self._concrete_style_registry = ConcreteStyleRegistry(self._style_resolver)

61 # Set default style

62 if default_style is None: 62 ↛ 65line 62 didn't jump to line 65 because the condition on line 62 was always true

63 # Create a default abstract style

64 default_style = self._abstract_style_registry.default_style

65 elif isinstance(default_style, Font):

66 # Convert Font to AbstractStyle for backward compatibility

67 default_style = AbstractStyle(

68 font_family=FontFamily.SERIF, # Default assumption

69 font_size=default_style.font_size,

70 color=default_style.colour,

71 language=default_style.language

72 )

73 style_id, default_style = self._abstract_style_registry.get_or_create_style(

74 default_style)

75 self._default_style = default_style

77 # Set basic metadata

78 if title:

79 self.set_metadata(MetadataType.TITLE, title)

80 self.set_metadata(MetadataType.LANGUAGE, language)

82 @property

83 def blocks(self) -> List[Block]:

84 """Get the top-level blocks in this document"""

85 return self._blocks

87 @property

88 def default_style(self):

89 """Get the default style for this document"""

90 return self._default_style

92 @default_style.setter

93 def default_style(self, style):

94 """Set the default style for this document"""

95 self._default_style = style

97 def add_block(self, block: Block):

98 """

99 Add a block to this document.

101 Args:

102 block: The block to add

103 """

104 self._blocks.append(block)

106 def create_paragraph(self, style=None) -> Paragraph:

107 """

108 Create a new paragraph and add it to this document.

110 Args:

111 style: Optional style override. If None, inherits from document

113 Returns:

114 The newly created Paragraph object

115 """

116 if style is None:

117 style = self._default_style

118 paragraph = Paragraph(style)

119 self.add_block(paragraph)

120 return paragraph

122 def create_heading(

123 self,

124 level: HeadingLevel = HeadingLevel.H1,

125 style=None) -> Heading:

126 """

127 Create a new heading and add it to this document.

129 Args:

130 level: The heading level

131 style: Optional style override. If None, inherits from document

133 Returns:

134 The newly created Heading object

135 """

136 if style is None:

137 style = self._default_style

138 heading = Heading(level, style)

139 self.add_block(heading)

140 return heading

141

142 def create_chapter(

143 self,

144 title: Optional[str] = None,

145 level: int = 1,

146 style=None) -> 'Chapter':

147 """

148 Create a new chapter with inherited style.

150 Args:

151 title: The chapter title

152 level: The chapter level

153 style: Optional style override. If None, inherits from document

155 Returns:

156 The newly created Chapter object

157 """

158 if style is None:

159 style = self._default_style

160 return Chapter(title, level, style)

162 # set_metadata() and get_metadata() are provided by MetadataContainer mixin

163

164 def add_anchor(self, name: str, target: Block):

165 """

166 Add a named anchor to this document.

167

168 Args:

169 name: The anchor name

170 target: The target block

171 """

172 self._anchors[name] = target

174 def get_anchor(self, name: str) -> Optional[Block]:

175 """

176 Get a named anchor from this document.

178 Args:

179 name: The anchor name

181 Returns:

182 The target block, or None if not found

183 """

184 return self._anchors.get(name)

186 def add_resource(self, name: str, resource: Any):

187 """

188 Add a resource to this document.

189

190 Args:

191 name: The resource name

192 resource: The resource data

193 """

194 self._resources[name] = resource

196 def get_resource(self, name: str) -> Optional[Any]:

197 """

198 Get a resource from this document.

200 Args:

201 name: The resource name

203 Returns:

204 The resource data, or None if not found

205 """

206 return self._resources.get(name)

208 def add_stylesheet(self, stylesheet: Dict[str, Any]):

209 """

210 Add a stylesheet to this document.

212 Args:

213 stylesheet: The stylesheet data

214 """

215 self._stylesheets.append(stylesheet)

216

217 def add_script(self, script: str):

218 """

219 Add a script to this document.

221 Args:

222 script: The script code

223 """

224 self._scripts.append(script)

226 def get_title(self) -> Optional[str]:

227 """

228 Get the document title.

230 Returns:

231 The document title, or None if not set

232 """

233 return self.get_metadata(MetadataType.TITLE)

234

235 def set_title(self, title: str):

236 """

237 Set the document title.

239 Args:

240 title: The document title

241 """

242 self.set_metadata(MetadataType.TITLE, title)

244 @property

245 def title(self) -> Optional[str]:

246 """

247 Get the document title as a property.

249 Returns:

250 The document title, or None if not set

251 """

252 return self.get_title()

253

254 @title.setter

255 def title(self, title: str):

256 """

257 Set the document title as a property.

259 Args:

260 title: The document title

261 """

262 self.set_title(title)

263

264 def find_blocks_by_type(self, block_type: BlockType) -> List[Block]:

265 """

266 Find all blocks of a specific type.

268 Args:

269 block_type: The type of blocks to find

271 Returns:

272 A list of matching blocks

273 """

274 result = []

276 def _find_recursive(blocks: List[Block]):

277 for block in blocks:

278 if block.block_type == block_type:

279 result.append(block)

281 # Check for child blocks based on block type

282 if hasattr(block, '_blocks'): 282 ↛ 283line 282 didn't jump to line 283 because the condition on line 282 was never true

283 _find_recursive(block._blocks)

284 elif hasattr(block, '_items') and isinstance(block._items, list): 284 ↛ 285line 284 didn't jump to line 285 because the condition on line 284 was never true

285 _find_recursive(block._items)

287 _find_recursive(self._blocks)

288 return result

290 def find_headings(self) -> List[Heading]:

291 """

292 Find all headings in the document.

293

294 Returns:

295 A list of heading blocks

296 """

297 blocks = self.find_blocks_by_type(BlockType.HEADING)

298 return [block for block in blocks if isinstance(block, Heading)]

300 def generate_table_of_contents(self) -> List[Tuple[int, str, Block]]:

301 """

302 Generate a table of contents from headings.

304 Returns:

305 A list of tuples containing (level, title, heading_block)

306 """

307 headings = self.find_headings()

309 toc = []

310 for heading in headings:

311 # Extract text from the heading

312 title = ""

313 for _, word in heading.words_iter():

314 title += word.text + " "

315 title = title.strip()

317 # Add to TOC

318 level = heading.level.value # Get numeric value from HeadingLevel enum

319 toc.append((level, title, heading))

321 return toc

322

323 def get_or_create_style(self,

324 font_family: FontFamily = FontFamily.SERIF,

325 font_size: Union[FontSize, int] = FontSize.MEDIUM,

326 font_weight: FontWeight = FontWeight.NORMAL,

327 font_style: FontStyle = FontStyle.NORMAL,

328 text_decoration: TextDecoration = TextDecoration.NONE,

329 color: Union[str, Tuple[int, int, int]] = "black",

330 background_color: Optional[Union[str, Tuple[int, int, int, int]]] = None,

331 language: str = "en-US",

332 **kwargs) -> Tuple[str, AbstractStyle]:

333 """

334 Get or create an abstract style with the specified properties.

336 Args:

337 font_family: Semantic font family

338 font_size: Font size (semantic or numeric)

339 font_weight: Font weight

340 font_style: Font style

341 text_decoration: Text decoration

342 color: Text color (name or RGB tuple)

343 background_color: Background color

344 language: Language code

345 **kwargs: Additional style properties

347 Returns:

348 Tuple of (style_id, AbstractStyle)

349 """

350 abstract_style = AbstractStyle(

351 font_family=font_family,

352 font_size=font_size,

353 font_weight=font_weight,

354 font_style=font_style,

355 text_decoration=text_decoration,

356 color=color,

357 background_color=background_color,

358 language=language,

359 **kwargs

360 )

362 return self._abstract_style_registry.get_or_create_style(abstract_style)

364 def get_font_for_style(self, abstract_style: AbstractStyle) -> Font:

365 """

366 Get a Font object for an AbstractStyle (for rendering).

368 Args:

369 abstract_style: The abstract style to get a font for

371 Returns:

372 Font object ready for rendering

373 """

374 return self._concrete_style_registry.get_font(abstract_style)

376 def update_rendering_context(self, **kwargs):

377 """

378 Update the rendering context (user preferences, device settings, etc.).

379

380 Args:

381 **kwargs: Context properties to update (base_font_size, font_scale_factor, etc.)

382 """

383 self._style_resolver.update_context(**kwargs)

384

385 def get_style_registry(self) -> AbstractStyleRegistry:

386 """Get the abstract style registry for this document."""

387 return self._abstract_style_registry

388

389 def get_concrete_style_registry(self) -> ConcreteStyleRegistry:

390 """Get the concrete style registry for this document."""

391 return self._concrete_style_registry

393 # get_or_create_font() is provided by FontRegistry mixin

396class Chapter(FontRegistry, MetadataContainer):

397 """

398 Represents a chapter or section in a document.

399 A chapter contains a sequence of blocks and has metadata.

400

401 Uses FontRegistry mixin for font caching with parent delegation.

402 Uses MetadataContainer mixin for metadata management.

403 """

405 def __init__(

406 self,

407 title: Optional[str] = None,

408 level: int = 1,

409 style=None,

410 parent=None):

411 """

412 Initialize a new chapter.

414 Args:

415 title: The chapter title

416 level: The chapter level (1 = top level, 2 = subsection, etc.)

417 style: Optional default style for child blocks

418 parent: Parent container (e.g., Document or Book)

419 """

420 super().__init__()

421 self._title = title

422 self._level = level

423 self._blocks: List[Block] = []

424 self._style = style

425 self._parent = parent

427 @property

428 def title(self) -> Optional[str]:

429 """Get the chapter title"""

430 return self._title

432 @title.setter

433 def title(self, title: str):

434 """Set the chapter title"""

435 self._title = title

436

437 @property

438 def level(self) -> int:

439 """Get the chapter level"""

440 return self._level

442 @property

443 def blocks(self) -> List[Block]:

444 """Get the blocks in this chapter"""

445 return self._blocks

447 @property

448 def style(self):

449 """Get the default style for this chapter"""

450 return self._style

452 @style.setter

453 def style(self, style):

454 """Set the default style for this chapter"""

455 self._style = style

457 def add_block(self, block: Block):

458 """

459 Add a block to this chapter.

461 Args:

462 block: The block to add

463 """

464 self._blocks.append(block)

465

466 def create_paragraph(self, style=None) -> Paragraph:

467 """

468 Create a new paragraph and add it to this chapter.

469

470 Args:

471 style: Optional style override. If None, inherits from chapter

472

473 Returns:

474 The newly created Paragraph object

475 """

476 if style is None:

477 style = self._style

478 paragraph = Paragraph(style)

479 self.add_block(paragraph)

480 return paragraph

481

482 def create_heading(

483 self,

484 level: HeadingLevel = HeadingLevel.H1,

485 style=None) -> Heading:

486 """

487 Create a new heading and add it to this chapter.

488

489 Args:

490 level: The heading level

491 style: Optional style override. If None, inherits from chapter

493 Returns:

494 The newly created Heading object

495 """

496 if style is None:

497 style = self._style

498 heading = Heading(level, style)

499 self.add_block(heading)

500 return heading

501

502 # set_metadata() and get_metadata() are provided by MetadataContainer mixin

503 # get_or_create_font() is provided by FontRegistry mixin

504

506class Book(Document):

507 """

508 Abstract representation of an ebook.

509 A book is a document that contains chapters.

510 """

512 def __init__(self, title: Optional[str] = None, author: Optional[str] = None,

513 language: str = "en-US", default_style=None):

514 """

515 Initialize a new book.

517 Args:

518 title: The book title

519 author: The book author

520 language: The book language code

521 default_style: Optional default style for child chapters and blocks

522 """

523 super().__init__(title, language, default_style)

524 self._chapters: List[Chapter] = []

526 if author:

527 self.set_metadata(MetadataType.AUTHOR, author)

529 @property

530 def chapters(self) -> List[Chapter]:

531 """Get the chapters in this book"""

532 return self._chapters

533

534 def add_chapter(self, chapter: Chapter):

535 """

536 Add a chapter to this book.

538 Args:

539 chapter: The chapter to add

540 """

541 self._chapters.append(chapter)

542

543 def create_chapter(

544 self,

545 title: Optional[str] = None,

546 level: int = 1,

547 style=None) -> Chapter:

548 """

549 Create and add a new chapter with inherited style.

550

551 Args:

552 title: The chapter title

553 level: The chapter level

554 style: Optional style override. If None, inherits from book

555

556 Returns:

557 The new chapter

558 """

559 if style is None: 559 ↛ 561line 559 didn't jump to line 561 because the condition on line 559 was always true

560 style = self._default_style

561 chapter = Chapter(title, level, style)

562 self.add_chapter(chapter)

563 return chapter

565 def get_author(self) -> Optional[str]:

566 """

567 Get the book author.

568

569 Returns:

570 The book author, or None if not set

571 """

572 return self.get_metadata(MetadataType.AUTHOR)

574 def set_author(self, author: str):

575 """

576 Set the book author.

577

578 Args:

579 author: The book author

580 """

581 self.set_metadata(MetadataType.AUTHOR, author)

582

583 def generate_table_of_contents(self) -> List[Tuple[int, str, Chapter]]:

584 """

585 Generate a table of contents from chapters.

586

587 Returns:

588 A list of tuples containing (level, title, chapter)

589 """

590 toc = []

591 for chapter in self._chapters:

592 if chapter.title:

593 toc.append((chapter.level, chapter.title, chapter))

594

595 return toc

+ + + diff --git a/cov_info/htmlcov/z_af715639580e2d86_functional_py.html b/cov_info/htmlcov/z_af715639580e2d86_functional_py.html new file mode 100644 index 0000000..7c78573 --- /dev/null +++ b/cov_info/htmlcov/z_af715639580e2d86_functional_py.html @@ -0,0 +1,444 @@ + + + + + Coverage for pyWebLayout/abstract/functional.py: 98% + + + + + +

+ Coverage for pyWebLayout/abstract/functional.py: + 98% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 144 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

2from enum import Enum

3from typing import Callable, Dict, Any, Optional, List, Tuple

4from pyWebLayout.core.base import Interactable

7class LinkType(Enum):

8 """Enumeration of different types of links for classification purposes"""

9 INTERNAL = 1 # Links within the same document (e.g., chapter references, bookmarks)

10 EXTERNAL = 2 # Links to external resources (e.g., websites, other documents)

11 API = 3 # Links that trigger API calls (e.g., for settings management)

12 FUNCTION = 4 # Links that execute a specific function

15class Link(Interactable):

16 """

17 A link that can navigate to a location or execute a function.

18 Links can be used for navigation within a document, to external resources,

19 or to trigger API calls for functionality like settings management.

20 """

22 def __init__(self,

23 location: str,

24 link_type: LinkType = LinkType.INTERNAL,

25 callback: Optional[Callable] = None,

26 params: Optional[Dict[str, Any]] = None,

27 title: Optional[str] = None,

28 html_id: Optional[str] = None):

29 """

30 Initialize a link.

32 Args:

33 location: The target location or identifier for this link

34 link_type: The type of link (internal, external, API, function)

35 callback: Optional callback function to execute when the link is activated

36 params: Optional parameters to pass to the callback or API

37 title: Optional title/tooltip for the link

38 html_id: Optional HTML id attribute (from <a id="...">) for callback binding

39 """

40 super().__init__(callback)

41 self._location = location

42 self._link_type = link_type

43 self._params = params or {}

44 self._title = title

45 self._html_id = html_id

47 @property

48 def location(self) -> str:

49 """Get the target location of this link"""

50 return self._location

52 @property

53 def link_type(self) -> LinkType:

54 """Get the type of this link"""

55 return self._link_type

57 @property

58 def params(self) -> Dict[str, Any]:

59 """Get the parameters for this link"""

60 return self._params

62 @property

63 def title(self) -> Optional[str]:

64 """Get the title/tooltip for this link"""

65 return self._title

67 @property

68 def html_id(self) -> Optional[str]:

69 """Get the HTML id attribute for callback binding"""

70 return self._html_id

72 def execute(self, point=None) -> Any:

73 """

74 Execute the link action based on its type.

76 For internal and external links, returns the location.

77 For API and function links, executes the callback with the provided parameters.

79 Args:

80 point: Optional interaction point passed from the interact() method

82 Returns:

83 The result of the link execution, which depends on the link type.

84 """

85 if self._link_type in (LinkType.API, LinkType.FUNCTION) and self._callback:

86 return self._callback(self._location, point, **self._params)

87 else:

88 # For INTERNAL and EXTERNAL links, return the location

89 # The renderer/browser will handle the navigation

90 return self._location

93class Button(Interactable):

94 """

95 A button that can be clicked to execute an action.

96 Buttons are similar to function links but are rendered differently.

97 """

99 def __init__(self,

100 label: str,

101 callback: Callable,

102 params: Optional[Dict[str, Any]] = None,

103 enabled: bool = True,

104 html_id: Optional[str] = None):

105 """

106 Initialize a button.

108 Args:

109 label: The text label for the button

110 callback: The function to execute when the button is clicked

111 params: Optional parameters to pass to the callback

112 enabled: Whether the button is initially enabled

113 html_id: Optional HTML id attribute (from <button id="...">) for callback binding

114 """

115 super().__init__(callback)

116 self._label = label

117 self._params = params or {}

118 self._enabled = enabled

119 self._html_id = html_id

121 @property

122 def label(self) -> str:

123 """Get the button label"""

124 return self._label

126 @label.setter

127 def label(self, label: str):

128 """Set the button label"""

129 self._label = label

131 @property

132 def enabled(self) -> bool:

133 """Check if the button is enabled"""

134 return self._enabled

136 @enabled.setter

137 def enabled(self, enabled: bool):

138 """Enable or disable the button"""

139 self._enabled = enabled

141 @property

142 def params(self) -> Dict[str, Any]:

143 """Get the button parameters"""

144 return self._params

146 @property

147 def html_id(self) -> Optional[str]:

148 """Get the HTML id attribute for callback binding"""

149 return self._html_id

151 def execute(self, point=None) -> Any:

152 """

153 Execute the button's callback function if the button is enabled.

155 Args:

156 point: Optional interaction point passed from the interact() method

157

158 Returns:

159 The result of the callback function, or None if the button is disabled.

160 """

161 if self._enabled and self._callback:

162 return self._callback(point, **self._params)

163 return None

166class Form(Interactable):

167 """

168 A form that can contain input fields and be submitted.

169 Forms can be used for user input and settings configuration.

170 """

172 def __init__(self,

173 form_id: str,

174 action: Optional[str] = None,

175 callback: Optional[Callable] = None,

176 html_id: Optional[str] = None):

177 """

178 Initialize a form.

179

180 Args:

181 form_id: The unique identifier for this form

182 action: The action URL or endpoint for form submission

183 callback: Optional callback function to execute on form submission

184 html_id: Optional HTML id attribute (from <form id="...">) for callback binding

185 """

186 super().__init__(callback)

187 self._form_id = form_id

188 self._action = action

189 self._fields: Dict[str, FormField] = {}

190 self._html_id = html_id

192 @property

193 def form_id(self) -> str:

194 """Get the form ID"""

195 return self._form_id

197 @property

198 def action(self) -> Optional[str]:

199 """Get the form action"""

200 return self._action

202 @property

203 def html_id(self) -> Optional[str]:

204 """Get the HTML id attribute for callback binding"""

205 return self._html_id

207 def add_field(self, field: FormField):

208 """

209 Add a field to this form.

210

211 Args:

212 field: The FormField to add

213 """

214 self._fields[field.name] = field

215 field.form = self

216

217 def get_field(self, name: str) -> Optional[FormField]:

218 """

219 Get a field by name.

221 Args:

222 name: The name of the field to get

223

224 Returns:

225 The FormField with the specified name, or None if not found

226 """

227 return self._fields.get(name)

228

229 def get_values(self) -> Dict[str, Any]:

230 """

231 Get the current values of all fields in this form.

232

233 Returns:

234 A dictionary mapping field names to their current values

235 """

236 return {name: field.value for name, field in self._fields.items()}

238 def execute(self) -> Any:

239 """

240 Submit the form, executing the callback with the form values.

241

242 Returns:

243 The result of the callback function, or the form values if no callback is provided.

244 """

245 values = self.get_values()

246

247 if self._callback:

248 return self._callback(self._form_id, values)

250 return values

253class FormFieldType(Enum):

254 """Enumeration of different types of form fields"""

255 TEXT = 1

256 PASSWORD = 2

257 CHECKBOX = 3

258 RADIO = 4

259 SELECT = 5

260 TEXTAREA = 6

261 NUMBER = 7

262 DATE = 8

263 TIME = 9

264 EMAIL = 10

265 URL = 11

266 COLOR = 12

267 RANGE = 13

268 HIDDEN = 14

271class FormField:

272 """

273 A field in a form that can accept user input.

274 """

276 def __init__(self,

277 name: str,

278 field_type: FormFieldType,

279 label: Optional[str] = None,

280 value: Any = None,

281 required: bool = False,

282 options: Optional[List[Tuple[str, str]]] = None):

283 """

284 Initialize a form field.

286 Args:

287 name: The name of this field

288 field_type: The type of this field

289 label: Optional label for this field

290 value: Initial value for this field

291 required: Whether this field is required

292 options: Options for select, radio, or checkbox fields (list of (value, label) tuples)

293 """

294 self._name = name

295 self._field_type = field_type

296 self._label = label or name

297 self._value = value

298 self._required = required

299 self._options = options or []

300 self._form: Optional[Form] = None

302 @property

303 def name(self) -> str:

304 """Get the field name"""

305 return self._name

307 @property

308 def field_type(self) -> FormFieldType:

309 """Get the field type"""

310 return self._field_type

312 @property

313 def label(self) -> str:

314 """Get the field label"""

315 return self._label

317 @property

318 def value(self) -> Any:

319 """Get the current field value"""

320 return self._value

322 @value.setter

323 def value(self, value: Any):

324 """Set the field value"""

325 self._value = value

327 @property

328 def required(self) -> bool:

329 """Check if the field is required"""

330 return self._required

332 @property

333 def options(self) -> List[Tuple[str, str]]:

334 """Get the field options"""

335 return self._options

336

337 @property

338 def form(self) -> Optional[Form]:

339 """Get the form containing this field"""

340 return self._form

342 @form.setter

343 def form(self, form: Form):

344 """Set the form containing this field"""

345 self._form = form

+ + + diff --git a/cov_info/htmlcov/z_af715639580e2d86_inline_py.html b/cov_info/htmlcov/z_af715639580e2d86_inline_py.html new file mode 100644 index 0000000..be61f69 --- /dev/null +++ b/cov_info/htmlcov/z_af715639580e2d86_inline_py.html @@ -0,0 +1,556 @@ + + + + + Coverage for pyWebLayout/abstract/inline.py: 99% + + + + + +

+ Coverage for pyWebLayout/abstract/inline.py: + 99% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 164 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1from __future__ import annotations

2from pyWebLayout.core import Hierarchical

3from pyWebLayout.style import Font

4from pyWebLayout.style.abstract_style import AbstractStyle

5from typing import Tuple, Union, List, Optional, Dict, Any, Callable

6from functools import lru_cache

7import pyphen

9# Import LinkType for type hints (imported at module level to avoid F821 linting error)

10from pyWebLayout.abstract.functional import LinkType

13@lru_cache(maxsize=16)

14def _hyphen_dict(language: Optional[str]) -> pyphen.Pyphen:

15 """

16 The pyphen dictionary for a language, reused across words.

18 Pyphen caches the parsed dictionary file itself, but rebuilding the wrapper

19 per word still costs about 40% of a hyphenation call, and hyphenation is

20 attempted for every word that overflows its line.

21 """

22 return pyphen.Pyphen(lang=language)

25class Word:

26 """

27 An abstract representation of a word in a document. Words can be split across

28 lines or pages during rendering. This class manages the logical representation

29 of a word without any rendering specifics.

31 Now uses AbstractStyle objects for memory efficiency and proper style management.

32 """

34 def __init__(self,

35 text: str,

36 style: Union[Font,

37 AbstractStyle],

38 background=None,

39 previous: Union['Word',

40 None] = None):

41 """

42 Initialize a new Word.

44 Args:

45 text: The text content of the word

46 style: AbstractStyle object or Font object (for backward compatibility)

47 background: Optional background color override

48 previous: Reference to the previous word in sequence

49 """

50 self._text = text

51 self._style = style

52 self._background = background

53 self._previous = previous

54 self._next = None

55 self.concrete = None

56 if previous:

57 previous.add_next(self)

59 @classmethod

60 def create_and_add_to(cls, text: str, container, style: Optional[Font] = None,

61 background=None) -> 'Word':

62 """

63 Create a new Word and add it to a container, inheriting style and language

64 from the container if not explicitly provided.

66 This method provides a convenient way to create words that automatically

67 inherit styling from their container (Paragraph, FormattedSpan, etc.)

68 without copying string values - using object references instead.

70 Args:

71 text: The text content of the word

72 container: The container to add the word to (must have add_word method and style property)

73 style: Optional Font style override. If None, inherits from container

74 background: Optional background color override. If None, inherits from container

76 Returns:

77 The newly created Word object

79 Raises:

80 AttributeError: If the container doesn't have the required add_word method or style property

81 """

82 # Inherit style from container if not provided

83 if style is None:

84 if hasattr(container, 'style'):

85 style = container.style

86 else:

87 raise AttributeError(

88 f"Container {type(container).__name__} must have a 'style' property")

90 # Inherit background from container if not provided

91 if background is None and hasattr(container, 'background'):

92 background = container.background

94 # Determine the previous word for proper linking

95 previous = None

96 if hasattr(container, '_words') and container._words:

97 # Container has a _words list (like FormattedSpan)

98 previous = container._words[-1]

99 elif hasattr(container, 'words'):

100 # Container has a words() method (like Paragraph)

101 try:

102 # Get the last word from the iterator

103 for _, word in container.words():

104 previous = word

105 except (StopIteration, TypeError):

106 previous = None

108 # Create the new word

109 word = cls(text, style, background, previous)

111 # Link the previous word to this new one

112 if previous:

113 previous.add_next(word)

115 # Add the word to the container

116 if hasattr(container, 'add_word'):

117 # Check if add_word expects a Word object or text string

118 import inspect

119 sig = inspect.signature(container.add_word)

120 params = list(sig.parameters.keys())

122 if len(params) > 0:

123 # Peek at the parameter name to guess the expected type

124 param_name = params[0]

125 if param_name in ['word', 'word_obj', 'word_object']:

126 # Expects a Word object

127 container.add_word(word)

128 else:

129 # Might expect text string (like FormattedSpan.add_word)

130 # In this case, we can't use the container's add_word as it would create

131 # a duplicate Word. We need to add directly to the container's word

132 # list.

133 if hasattr(container, '_words'):

134 container._words.append(word)

135 else:

136 # Fallback: try calling with the Word object anyway

137 container.add_word(word)

138 else:

139 # No parameters, shouldn't happen with add_word methods

140 container.add_word(word)

141 else:

142 raise AttributeError(

143 f"Container {type(container).__name__} must have an 'add_word' method")

145 return word

147 def add_concete(self, text: Union[Any, Tuple[Any, Any]]):

148 self.concrete = text

150 @property

151 def text(self) -> str:

152 """Get the text content of the word"""

153 return self._text

155 @property

156 def style(self) -> Font:

157 """Get the font style of the word"""

158 return self._style

159

160 @property

161 def background(self):

162 """Get the background color of the word"""

163 return self._background

165 @property

166 def previous(self) -> Union['Word', None]:

167 """Get the previous word in sequence"""

168 return self._previous

170 @property

171 def next(self) -> Union['Word', None]:

172 """Get the next word in sequence"""

173 return self._next

175 def add_next(self, next_word: 'Word'):

176 """Set the next word in sequence"""

177 self._next = next_word

179 def with_style(self, style: Font) -> 'Word':

180 """

181 Return a copy of this word carrying a different font.

183 Subclasses that hold extra state must override this, or that state is

184 silently dropped when a caller restyles the word. Sequence links

185 (previous/next) are deliberately not copied: the copy belongs to a

186 different word chain, which the new container rebuilds as words are

187 added to it.

188 """

189 return Word(self._text, style, self._background)

191 def possible_hyphenation(self, language: str = None) -> bool:

192 """

193 Hyphenate the word and store the parts.

195 Args:

196 language: Language code for hyphenation. If None, uses the style's language.

198 Returns:

199 bool: True if the word was hyphenated, False otherwise.

200 """

202 return list(_hyphen_dict(self._style.language).iterate(self._text))

205...

208class FormattedSpan:

209 """

210 A run of words with consistent formatting.

211 This represents a sequence of words that share the same style attributes.

212 """

213

214 def __init__(self, style: Font, background=None):

215 """

216 Initialize a new formatted span.

218 Args:

219 style: Font style information for all words in this span

220 background: Optional background color override

221 """

222 self._style = style

223 self._background = background if background else style.background

224 self._words: List[Word] = []

226 @classmethod

227 def create_and_add_to(

228 cls,

229 container,

230 style: Optional[Font] = None,

231 background=None) -> 'FormattedSpan':

232 """

233 Create a new FormattedSpan and add it to a container, inheriting style from

234 the container if not explicitly provided.

236 Args:

237 container: The container to add the span to (must have add_span method and style property)

238 style: Optional Font style override. If None, inherits from container

239 background: Optional background color override

241 Returns:

242 The newly created FormattedSpan object

244 Raises:

245 AttributeError: If the container doesn't have the required add_span method or style property

246 """

247 # Inherit style from container if not provided

248 if style is None:

249 if hasattr(container, 'style'):

250 style = container.style

251 else:

252 raise AttributeError(

253 f"Container {type(container).__name__} must have a 'style' property")

254

255 # Inherit background from container if not provided

256 if background is None and hasattr(container, 'background'):

257 background = container.background

259 # Create the new span

260 span = cls(style, background)

262 # Add the span to the container

263 if hasattr(container, 'add_span'):

264 container.add_span(span)

265 else:

266 raise AttributeError(

267 f"Container {type(container).__name__} must have an 'add_span' method")

269 return span

271 @property

272 def style(self) -> Font:

273 """Get the font style of this span"""

274 return self._style

276 @property

277 def background(self):

278 """Get the background color of this span"""

279 return self._background

281 @property

282 def words(self) -> List[Word]:

283 """Get the list of words in this span"""

284 return self._words

286 def add_word(self, text: str) -> Word:

287 """

288 Create and add a new word to this span.

290 Args:

291 text: The text content of the word

293 Returns:

294 The newly created Word object

295 """

296 # Get the previous word if any

297 previous = self._words[-1] if self._words else None

299 # Create the new word

300 word = Word(text, self._style, self._background, previous)

302 # Link the previous word to this new one

303 if previous:

304 previous.add_next(word)

306 # Add the word to our list

307 self._words.append(word)

309 return word

312class LinkedWord(Word):

313 """

314 A Word that is also a Link - combines text content with hyperlink functionality.

316 When a word is part of a hyperlink, it becomes clickable and can trigger

317 navigation or callbacks. Multiple words can share the same link destination.

318 """

319

320 def __init__(self, text: str, style: Union[Font, 'AbstractStyle'],

321 location: str, link_type: Optional['LinkType'] = None,

322 callback: Optional[Callable] = None,

323 background=None, previous: Optional[Word] = None,

324 params: Optional[Dict[str, Any]] = None,

325 title: Optional[str] = None):

326 """

327 Initialize a linked word.

329 Args:

330 text: The text content of the word

331 style: The font style

332 location: The link target (URL, bookmark, etc.)

333 link_type: Type of link (INTERNAL, EXTERNAL, etc.)

334 callback: Optional callback for link activation

335 background: Optional background color

336 previous: Previous word in sequence

337 params: Parameters for the link

338 title: Tooltip/title for the link

339 """

340 # Initialize Word first

341 super().__init__(text, style, background, previous)

342

343 # Store link properties

344 self._location = location

345 self._link_type = link_type or LinkType.EXTERNAL

346 self._callback = callback

347 self._params = params or {}

348 self._title = title

349

350 @property

351 def location(self) -> str:

352 """Get the link target location"""

353 return self._location

355 @property

356 def link_type(self):

357 """Get the type of link"""

358 return self._link_type

359

360 @property

361 def link_callback(self) -> Optional[Callable]:

362 """Get the link callback (distinct from word callback)"""

363 return self._callback

364

365 @property

366 def params(self) -> Dict[str, Any]:

367 """Get the link parameters"""

368 return self._params

369

370 @property

371 def link_title(self) -> Optional[str]:

372 """Get the link title/tooltip"""

373 return self._title

375 def with_style(self, style: Font) -> 'LinkedWord':

376 """Return a copy carrying a different font, keeping the link intact."""

377 return LinkedWord(

378 self._text,

379 style,

380 self._location,

381 link_type=self._link_type,

382 callback=self._callback,

383 background=self._background,

384 params=dict(self._params),

385 title=self._title,

386 )

388 def execute_link(self, context: Optional[Dict[str, Any]] = None) -> Any:

389 """

390 Execute the link action.

392 Args:

393 context: Optional context dict (e.g., {'text': word.text})

395 Returns:

396 The result of the link execution

397 """

398 # Add word text to context

399 full_context = {**self._params, 'text': self._text}

400 if context: 400 ↛ 401line 400 didn't jump to line 401 because the condition on line 400 was never true

401 full_context.update(context)

402

403 if self._link_type in (LinkType.API, LinkType.FUNCTION) and self._callback:

404 return self._callback(self._location, **full_context)

405 else:

406 # For INTERNAL and EXTERNAL links, return the location

407 return self._location

410class LineBreak(Hierarchical):

411 """

412 A line break element that forces a new line within text content.

413 While this is an inline element that can occur within paragraphs,

414 it has block-like properties for consistency with the abstract model.

416 Uses Hierarchical mixin for parent-child relationship management.

417 """

418

419 def __init__(self):

420 """Initialize a line break element."""

421 super().__init__()

422 # Import here to avoid circular imports

423 from .block import BlockType

424 self._block_type = BlockType.LINE_BREAK

425

426 @property

427 def block_type(self):

428 """Get the block type for this line break"""

429 return self._block_type

431 @classmethod

432 def create_and_add_to(cls, container) -> 'LineBreak':

433 """

434 Create a new LineBreak and add it to a container.

436 Args:

437 container: The container to add the line break to

438

439 Returns:

440 The newly created LineBreak object

441 """

442 # Create the new line break

443 line_break = cls()

444

445 # Add the line break to the container if it has an appropriate method

446 if hasattr(container, 'add_line_break'):

447 container.add_line_break(line_break)

448 elif hasattr(container, 'add_element'):

449 container.add_element(line_break)

450 elif hasattr(container, 'add_word'):

451 # Some containers might treat line breaks like words

452 container.add_word(line_break)

453 else:

454 # Set parent relationship manually

455 line_break.parent = container

457 return line_break

+ + + diff --git a/cov_info/htmlcov/z_af715639580e2d86_interactive_image_py.html b/cov_info/htmlcov/z_af715639580e2d86_interactive_image_py.html new file mode 100644 index 0000000..6be5b25 --- /dev/null +++ b/cov_info/htmlcov/z_af715639580e2d86_interactive_image_py.html @@ -0,0 +1,262 @@ + + + + + Coverage for pyWebLayout/abstract/interactive_image.py: 80% + + + + + +

+ Coverage for pyWebLayout/abstract/interactive_image.py: + 80% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 34 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Interactive and queryable image for pyWebLayout.

4Provides an InteractiveImage class that combines Image with Interactable

5and Queriable capabilities, allowing images to respond to tap events with

6proper bounding box detection.

7"""

9from typing import Optional, Callable, Tuple

10import numpy as np

12from .block import Image

13from ..core.base import Interactable, Queriable

16class InteractiveImage(Image, Interactable, Queriable):

17 """

18 An image that can be interacted with and queried for hit detection.

20 This combines pyWebLayout's Image block with Interactable and Queriable

21 capabilities, allowing the image to:

22 - Have a callback that fires when tapped

23 - Know its rendered position (origin)

24 - Detect if a point is within its bounds

26 Example:

27 >>> img = InteractiveImage(

28 ... source="cover.png",

29 ... alt_text="Book Title",

30 ... callback=lambda point: "/path/to/book.epub"

31 ... )

32 >>> # After rendering, origin is set automatically

33 >>> # Check if tap is inside

34 >>> result = img.interact((120, 250))

35 >>> # Returns "/path/to/book.epub" if inside, None if outside

36 """

38 def __init__(

39 self,

40 source: str = "",

41 alt_text: str = "",

42 width: Optional[int] = None,

43 height: Optional[int] = None,

44 callback: Optional[Callable] = None

45 ):

46 """

47 Initialize an interactive image.

49 Args:

50 source: The image source URL or path

51 alt_text: Alternative text for accessibility

52 width: Optional image width in pixels

53 height: Optional image height in pixels

54 callback: Function to call when image is tapped (receives point coordinates)

55 """

56 # Initialize Image

57 Image.__init__(

58 self,

59 source=source,

60 alt_text=alt_text,

61 width=width,

62 height=height)

64 # Initialize Interactable

65 Interactable.__init__(self, callback=callback)

67 # Initialize position tracking

68 self._origin = np.array([0, 0]) # Will be set during rendering

69 self.size = (width or 0, height or 0) # Will be updated during rendering

71 def interact(self, point: np.generic) -> Optional[any]:

72 """

73 Handle interaction at the given point.

75 Only triggers the callback if the point is within the image bounds.

77 Args:

78 point: The coordinates of the interaction (x, y)

80 Returns:

81 The result of the callback if point is inside, None otherwise

82 """

83 # Check if point is inside this image

84 if self.in_object(point):

85 # Point is inside, trigger callback

86 if self._callback is not None:

87 return self._callback(point)

89 return None

91 def in_object(self, point: np.generic) -> bool:

92 """

93 Check if a point is within the image bounds.

95 Args:

96 point: The coordinates to check (x, y)

98 Returns:

99 True if point is inside the image, False otherwise

100 """

101 point_array = np.array(point)

102 relative_point = point_array - self._origin

103 return np.all((0 <= relative_point) & (relative_point < self.size))

105 @classmethod

106 def create_and_add_to(

107 cls,

108 parent,

109 source: str,

110 alt_text: str = "",

111 width: Optional[int] = None,

112 height: Optional[int] = None,

113 callback: Optional[Callable] = None

114 ) -> 'InteractiveImage':

115 """

116 Create an interactive image and add it to a parent block.

118 This is a convenience method that mimics the Image.create_and_add_to API

119 but creates an InteractiveImage instead.

121 Args:

122 parent: Parent block to add this image to

123 source: The image source URL or path

124 alt_text: Alternative text for accessibility

125 width: Optional image width in pixels

126 height: Optional image height in pixels

127 callback: Function to call when image is tapped

129 Returns:

130 The created InteractiveImage instance

131 """

132 img = cls(

133 source=source,

134 alt_text=alt_text,

135 width=width,

136 height=height,

137 callback=callback

138 )

140 # Add to parent using its add_block method

141 if hasattr(parent, 'add_block'): 141 ↛ 142line 141 didn't jump to line 142 because the condition on line 141 was never true

142 parent.add_block(img)

143 elif hasattr(parent, 'add_child'): 143 ↛ 144line 143 didn't jump to line 144 because the condition on line 143 was never true

144 parent.add_child(img)

145 elif hasattr(parent, '_children'): 145 ↛ 147line 145 didn't jump to line 147 because the condition on line 145 was always true

146 parent._children.append(img)

147 elif hasattr(parent, '_blocks'):

148 parent._blocks.append(img)

150 return img

152 def set_rendered_bounds(self, origin: Tuple[int, int], size: Tuple[int, int]):

153 """

154 Set the rendered position and size of this image.

156 This should be called by the renderer after it places the image.

157

158 Args:

159 origin: (x, y) coordinates of top-left corner

160 size: (width, height) of the rendered image

161 """

162 self._origin = np.array(origin)

163 self.size = size

+ + + diff --git a/cov_info/htmlcov/z_ba7f6bdeb0188088___init___py.html b/cov_info/htmlcov/z_ba7f6bdeb0188088___init___py.html new file mode 100644 index 0000000..a56cf4a --- /dev/null +++ b/cov_info/htmlcov/z_ba7f6bdeb0188088___init___py.html @@ -0,0 +1,122 @@ + + + + + Coverage for pyWebLayout/style/__init__.py: 100% + + + + + +

+ Coverage for pyWebLayout/style/init.py: + 100% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 6 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Style system for the pyWebLayout library.

4This module provides the core styling components used throughout the library.

5"""

7from .fonts import (

8 Font, FontWeight, FontStyle, TextDecoration,

9 BundledFont, get_bundled_font_path, get_bundled_fonts_dir

10)

11from .abstract_style import (

12 AbstractStyle, AbstractStyleRegistry, FontFamily, FontSize

13)

14from .concrete_style import ConcreteStyle

15from .page_style import PageStyle

16from .alignment import Alignment

18__all__ = [

19 "Font", "FontWeight", "FontStyle", "TextDecoration",

20 "BundledFont", "get_bundled_font_path", "get_bundled_fonts_dir",

21 "AbstractStyle", "AbstractStyleRegistry", "FontFamily", "FontSize",

22 "ConcreteStyle", "PageStyle", "Alignment"

23]

+ + + diff --git a/cov_info/htmlcov/z_ba7f6bdeb0188088_abstract_style_py.html b/cov_info/htmlcov/z_ba7f6bdeb0188088_abstract_style_py.html new file mode 100644 index 0000000..168c2ec --- /dev/null +++ b/cov_info/htmlcov/z_ba7f6bdeb0188088_abstract_style_py.html @@ -0,0 +1,454 @@ + + + + + Coverage for pyWebLayout/style/abstract_style.py: 76% + + + + + +

+ Coverage for pyWebLayout/style/abstract_style.py: + 76% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 135 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Abstract style system for storing document styling intent.

4This module defines styles in terms of semantic meaning rather than concrete

5rendering parameters, allowing for flexible interpretation by different

6rendering systems and user preferences.

7"""

9from .alignment import Alignment

10from typing import Dict, Optional, Tuple, Union

11from dataclasses import dataclass

12from enum import Enum

13from .fonts import FontWeight, FontStyle, TextDecoration

16class FontFamily(Enum):

17 """Semantic font family categories"""

18 SERIF = "serif"

19 SANS_SERIF = "sans-serif"

20 MONOSPACE = "monospace"

21 CURSIVE = "cursive"

22 FANTASY = "fantasy"

25class FontSize(Enum):

26 """Semantic font sizes"""

27 XX_SMALL = "xx-small"

28 X_SMALL = "x-small"

29 SMALL = "small"

30 MEDIUM = "medium"

31 LARGE = "large"

32 X_LARGE = "x-large"

33 XX_LARGE = "xx-large"

35 # Allow numeric values as well

36 @classmethod

37 def from_value(cls, value: Union[str, int, float]) -> Union['FontSize', int]:

38 """Convert a value to FontSize enum or return numeric value"""

39 if isinstance(value, (int, float)):

40 return int(value)

41 if isinstance(value, str):

42 try:

43 return cls(value)

44 except ValueError:

45 # Try to parse as number

46 try:

47 return int(float(value))

48 except ValueError:

49 return cls.MEDIUM

50 return cls.MEDIUM

53# Import Alignment from the centralized location

55# Use Alignment for text alignment

56TextAlign = Alignment

59@dataclass(frozen=True)

60class AbstractStyle:

61 """

62 Abstract representation of text styling that captures semantic intent

63 rather than concrete rendering parameters.

65 This allows the same document to be rendered differently based on

66 user preferences, device capabilities, or accessibility requirements.

68 Being frozen=True makes this class hashable and immutable, which is

69 perfect for use as dictionary keys and preventing accidental modification.

70 """

72 # Font properties (semantic)

73 font_family: FontFamily = FontFamily.SERIF

74 font_size: Union[FontSize, int] = FontSize.MEDIUM

75 font_weight: FontWeight = FontWeight.NORMAL

76 font_style: FontStyle = FontStyle.NORMAL

77 text_decoration: TextDecoration = TextDecoration.NONE

79 # Color (as semantic names or RGB)

80 color: Union[str, Tuple[int, int, int]] = "black"

81 background_color: Optional[Union[str, Tuple[int, int, int, int]]] = None

83 # Text properties

84 # None means "not specified": the page's default_alignment applies.

85 text_align: Optional[TextAlign] = None

86 line_height: Optional[Union[str, float]] = None # "normal", "1.2", 1.5, etc.

87 letter_spacing: Optional[Union[str, float]] = None # "normal", "0.1em", etc.

88 word_spacing: Optional[Union[str, float]] = None

89 word_spacing_min: Optional[Union[str, float]] = None # Minimum allowed word spacing

90 word_spacing_max: Optional[Union[str, float]] = None # Maximum allowed word spacing

92 # Language and locale

93 language: str = "en-US"

95 # Hierarchy properties

96 parent_style_id: Optional[str] = None

98 def __post_init__(self):

99 """Validate and normalize values after creation"""

100 # Normalize font_size if it's a string that could be a number

101 if isinstance(self.font_size, str): 101 ↛ 102line 101 didn't jump to line 102 because the condition on line 101 was never true

102 try:

103 object.__setattr__(self, 'font_size', int(float(self.font_size)))

104 except ValueError:

105 # Keep as is if it's a semantic size name

106 pass

108 def __hash__(self) -> int:

109 """

110 Custom hash implementation to ensure consistent hashing.

112 Since this is a frozen dataclass, it should be hashable by default,

113 but we provide a custom implementation to ensure all fields are

114 properly considered and to handle the Union types correctly.

116 The result is memoised on first use. Styles are used as dictionary keys

117 throughout parsing and style resolution, and five of the fields are enum

118 members whose own __hash__ is a Python-level call, so rebuilding the

119 15-tuple on every lookup was a measurable share of document parsing. The

120 class is frozen, so the value cannot go stale.

121 """

122 cached = self.__dict__.get('_hash_cache')

123 if cached is not None:

124 return cached

126 # Convert all values to hashable forms

127 hashable_values = (

128 self.font_family,

129 self.font_size if isinstance(self.font_size, int) else self.font_size,

130 self.font_weight,

131 self.font_style,

132 self.text_decoration,

133 self.color if isinstance(self.color, (str, tuple)) else str(self.color),

134 self.background_color,

135 self.text_align,

136 self.line_height,

137 self.letter_spacing,

138 self.word_spacing,

139 self.word_spacing_min,

140 self.word_spacing_max,

141 self.language,

142 self.parent_style_id

143 )

145 result = hash(hashable_values)

146 object.__setattr__(self, '_hash_cache', result)

147 return result

148

149 def merge_with(self, other: 'AbstractStyle') -> 'AbstractStyle':

150 """

151 Create a new AbstractStyle by merging this one with another.

152 The other style's properties take precedence.

153

154 Args:

155 other: AbstractStyle to merge with this one

157 Returns:

158 New AbstractStyle with merged values

159 """

160 # Get all fields from both styles

161 current_dict = {

162 field.name: getattr(self, field.name)

163 for field in self.__dataclass_fields__.values()

164 }

166 other_dict = {

167 field.name: getattr(other, field.name)

168 for field in other.__dataclass_fields__.values()

169 if getattr(other, field.name) != field.default

170 }

172 # Merge dictionaries (other takes precedence)

173 merged_dict = current_dict.copy()

174 merged_dict.update(other_dict)

175

176 return AbstractStyle(**merged_dict)

178 def with_modifications(self, **kwargs) -> 'AbstractStyle':

179 """

180 Create a new AbstractStyle with specified modifications.

182 Args:

183 **kwargs: Properties to modify

185 Returns:

186 New AbstractStyle with modifications applied

187 """

188 current_dict = {

189 field.name: getattr(self, field.name)

190 for field in self.__dataclass_fields__.values()

191 }

193 current_dict.update(kwargs)

194 return AbstractStyle(**current_dict)

197class AbstractStyleRegistry:

198 """

199 Registry for managing abstract document styles.

200

201 This registry stores the semantic styling intent and provides

202 deduplication and inheritance capabilities using hashable AbstractStyle objects.

203 """

205 def __init__(self):

206 """Initialize an empty abstract style registry."""

207 self._styles: Dict[str, AbstractStyle] = {}

208 # Reverse mapping using hashable styles

209 self._style_to_id: Dict[AbstractStyle, str] = {}

210 self._next_id = 1

212 # Create and register the default style

213 self._default_style = self._create_default_style()

215 def _create_default_style(self) -> AbstractStyle:

216 """Create the default document style."""

217 default_style = AbstractStyle()

218 style_id = "default"

219 self._styles[style_id] = default_style

220 self._style_to_id[default_style] = style_id

221 return default_style

222

223 @property

224 def default_style(self) -> AbstractStyle:

225 """Get the default style for the document."""

226 return self._default_style

228 def _generate_style_id(self) -> str:

229 """Generate a unique style ID."""

230 style_id = f"abstract_style_{self._next_id}"

231 self._next_id += 1

232 return style_id

234 def get_style_id(self, style: AbstractStyle) -> Optional[str]:

235 """

236 Get the ID for a given style if it exists in the registry.

238 Args:

239 style: AbstractStyle to find

241 Returns:

242 Style ID if found, None otherwise

243 """

244 return self._style_to_id.get(style)

246 def register_style(

247 self,

248 style: AbstractStyle,

249 style_id: Optional[str] = None) -> str:

250 """

251 Register a style in the registry.

253 Args:

254 style: AbstractStyle to register

255 style_id: Optional style ID. If None, one will be generated

257 Returns:

258 The style ID

259 """

260 # Check if style already exists

261 existing_id = self.get_style_id(style)

262 if existing_id is not None: 262 ↛ 263line 262 didn't jump to line 263 because the condition on line 262 was never true

263 return existing_id

265 if style_id is None: 265 ↛ 268line 265 didn't jump to line 268 because the condition on line 265 was always true

266 style_id = self._generate_style_id()

268 self._styles[style_id] = style

269 self._style_to_id[style] = style_id

270 return style_id

271

272 def get_or_create_style(self,

273 style: Optional[AbstractStyle] = None,

274 parent_id: Optional[str] = None,

275 **kwargs) -> Tuple[str, AbstractStyle]:

276 """

277 Get an existing style or create a new one.

278

279 Args:

280 style: AbstractStyle object. If None, created from kwargs

281 parent_id: Optional parent style ID

282 **kwargs: Individual style properties (used if style is None)

284 Returns:

285 Tuple of (style_id, AbstractStyle)

286 """

287 # Create style object if not provided

288 if style is None:

289 # Filter out None values from kwargs

290 filtered_kwargs = {k: v for k, v in kwargs.items() if v is not None}

291 if parent_id: 291 ↛ 292line 291 didn't jump to line 292 because the condition on line 291 was never true

292 filtered_kwargs['parent_style_id'] = parent_id

293 style = AbstractStyle(**filtered_kwargs)

295 # Check if we already have this style (using hashable property)

296 existing_id = self.get_style_id(style)

297 if existing_id is not None:

298 return existing_id, style

300 # Create new style

301 style_id = self.register_style(style)

302 return style_id, style

304 def get_style_by_id(self, style_id: str) -> Optional[AbstractStyle]:

305 """Get a style by its ID."""

306 return self._styles.get(style_id)

307

308 def create_derived_style(self, base_style_id: str, **

309 modifications) -> Tuple[str, AbstractStyle]:

310 """

311 Create a new style derived from a base style.

313 Args:

314 base_style_id: ID of the base style

315 **modifications: Properties to modify

317 Returns:

318 Tuple of (new_style_id, new_AbstractStyle)

319 """

320 base_style = self.get_style_by_id(base_style_id)

321 if base_style is None: 321 ↛ 322line 321 didn't jump to line 322 because the condition on line 321 was never true

322 raise ValueError(f"Base style '{base_style_id}' not found")

323

324 # Create derived style

325 derived_style = base_style.with_modifications(**modifications)

326 return self.get_or_create_style(derived_style)

327

328 def resolve_effective_style(self, style_id: str) -> AbstractStyle:

329 """

330 Resolve the effective style including inheritance.

332 Args:

333 style_id: Style ID to resolve

335 Returns:

336 Effective AbstractStyle with inheritance applied

337 """

338 style = self.get_style_by_id(style_id)

339 if style is None: 339 ↛ 340line 339 didn't jump to line 340 because the condition on line 339 was never true

340 return self._default_style

342 if style.parent_style_id is None: 342 ↛ 346line 342 didn't jump to line 346 because the condition on line 342 was always true

343 return style

345 # Recursively resolve parent styles

346 parent_style = self.resolve_effective_style(style.parent_style_id)

347 return parent_style.merge_with(style)

349 def get_all_styles(self) -> Dict[str, AbstractStyle]:

350 """Get all registered styles."""

351 return self._styles.copy()

353 def get_style_count(self) -> int:

354 """Get the number of registered styles."""

355 return len(self._styles)

+ + + diff --git a/cov_info/htmlcov/z_ba7f6bdeb0188088_alignment_py.html b/cov_info/htmlcov/z_ba7f6bdeb0188088_alignment_py.html new file mode 100644 index 0000000..130d634 --- /dev/null +++ b/cov_info/htmlcov/z_ba7f6bdeb0188088_alignment_py.html @@ -0,0 +1,124 @@ + + + + + Coverage for pyWebLayout/style/alignment.py: 91% + + + + + +

+ Coverage for pyWebLayout/style/alignment.py: + 91% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 11 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Alignment options for the pyWebLayout library.

4This module provides alignment-related functionality.

5"""

7from enum import Enum

10class Alignment(Enum):

11 """Text and box alignment options"""

12 # Horizontal alignment

13 LEFT = "left"

14 RIGHT = "right"

15 CENTER = "center"

16 JUSTIFY = "justify"

18 # Vertical alignment

19 TOP = "top"

20 MIDDLE = "middle"

21 BOTTOM = "bottom"

23 def __str__(self):

24 """Return the string value of the alignment."""

25 return self.value

+ + + diff --git a/cov_info/htmlcov/z_ba7f6bdeb0188088_concrete_style_py.html b/cov_info/htmlcov/z_ba7f6bdeb0188088_concrete_style_py.html new file mode 100644 index 0000000..d5236a4 --- /dev/null +++ b/cov_info/htmlcov/z_ba7f6bdeb0188088_concrete_style_py.html @@ -0,0 +1,584 @@ + + + + + Coverage for pyWebLayout/style/concrete_style.py: 63% + + + + + +

+ Coverage for pyWebLayout/style/concrete_style.py: + 63% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 207 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1"""

2Concrete style system for actual rendering parameters.

4This module converts abstract styles to concrete rendering parameters based on

5user preferences, device capabilities, and rendering context.

6"""

8from typing import Dict, Optional, Tuple, Union

9from dataclasses import dataclass

10from .abstract_style import AbstractStyle, FontFamily, FontSize

11from pyWebLayout.style.alignment import Alignment as TextAlign

12from .fonts import Font, FontWeight, FontStyle, TextDecoration

15@dataclass(frozen=True)

16class RenderingContext:

17 """

18 Context information for style resolution.

19 Contains user preferences and device capabilities.

20 """

22 # User preferences

23 base_font_size: int = 16 # Base font size in points

24 font_scale_factor: float = 1.0 # Global font scaling

25 preferred_serif_font: Optional[str] = None

26 preferred_sans_serif_font: Optional[str] = None

27 preferred_monospace_font: Optional[str] = None

29 # Device/environment info

30 dpi: int = 96 # Dots per inch

31 available_width: Optional[int] = None # Available width in pixels

32 available_height: Optional[int] = None # Available height in pixels

34 # Accessibility preferences

35 high_contrast: bool = False

36 large_text: bool = False

37 reduce_motion: bool = False

39 # Language and locale

40 default_language: str = "en-US"

43@dataclass(frozen=True)

44class ConcreteStyle:

45 """

46 Concrete representation of text styling with actual rendering parameters.

48 This contains the resolved font files, pixel sizes, actual colors, etc.

49 that will be used for rendering. This is also hashable for efficient caching.

50 """

52 # Concrete font properties

53 font_path: Optional[str] = None

54 font_size: int = 16 # Always in points/pixels

55 color: Tuple[int, int, int] = (0, 0, 0) # Always RGB

56 background_color: Optional[Tuple[int, int, int, int]] = None # Always RGBA or None

58 # Font attributes

59 weight: FontWeight = FontWeight.NORMAL

60 style: FontStyle = FontStyle.NORMAL

61 decoration: TextDecoration = TextDecoration.NONE

63 # Layout properties

64 # None means "not specified": the page's default_alignment applies.

65 text_align: Optional[TextAlign] = None

66 line_height: float = 1.0 # Multiplier

67 letter_spacing: float = 0.0 # In pixels

68 word_spacing: float = 0.0 # In pixels

69 word_spacing_min: float = 0.0 # Minimum word spacing in pixels

70 word_spacing_max: float = 0.0 # Maximum word spacing in pixels

72 # Language and locale

73 language: str = "en-US"

74 min_hyphenation_width: int = 64 # In pixels

76 # Reference to source abstract style

77 abstract_style: Optional[AbstractStyle] = None

79 def create_font(self) -> Font:

80 """Create a Font object from this concrete style."""

81 return Font(

82 font_path=self.font_path,

83 font_size=self.font_size,

84 colour=self.color,

85 weight=self.weight,

86 style=self.style,

87 decoration=self.decoration,

88 background=self.background_color,

89 language=self.language,

90 min_hyphenation_width=self.min_hyphenation_width

91 )

94class StyleResolver:

95 """

96 Resolves abstract styles to concrete styles based on rendering context.

98 This class handles the conversion from semantic styling intent to actual

99 rendering parameters, applying user preferences and device capabilities.

100 """

101

102 def __init__(self, context: RenderingContext):

103 """

104 Initialize the style resolver with a rendering context.

106 Args:

107 context: RenderingContext with user preferences and device info

108 """

109 self.context = context

110 self._concrete_cache: Dict[AbstractStyle, ConcreteStyle] = {}

112 # Font size mapping for semantic sizes

113 self._semantic_font_sizes = {

114 FontSize.XX_SMALL: 0.6,

115 FontSize.X_SMALL: 0.75,

116 FontSize.SMALL: 0.89,

117 FontSize.MEDIUM: 1.0,

118 FontSize.LARGE: 1.2,

119 FontSize.X_LARGE: 1.5,

120 FontSize.XX_LARGE: 2.0,

121 }

123 # Color name mapping

124 self._color_names = {

125 "black": (0, 0, 0),

126 "white": (255, 255, 255),

127 "red": (255, 0, 0),

128 "green": (0, 128, 0),

129 "blue": (0, 0, 255),

130 "yellow": (255, 255, 0),

131 "cyan": (0, 255, 255),

132 "magenta": (255, 0, 255),

133 "silver": (192, 192, 192),

134 "gray": (128, 128, 128),

135 "maroon": (128, 0, 0),

136 "olive": (128, 128, 0),

137 "lime": (0, 255, 0),

138 "aqua": (0, 255, 255),

139 "teal": (0, 128, 128),

140 "navy": (0, 0, 128),

141 "fuchsia": (255, 0, 255),

142 "purple": (128, 0, 128),

143 }

145 def resolve_style(self, abstract_style: AbstractStyle) -> ConcreteStyle:

146 """

147 Resolve an abstract style to a concrete style.

148

149 Args:

150 abstract_style: AbstractStyle to resolve

152 Returns:

153 ConcreteStyle with concrete rendering parameters

154 """

155 # Check cache first

156 if abstract_style in self._concrete_cache:

157 return self._concrete_cache[abstract_style]

159 # Resolve each property

160 font_path = self._resolve_font_path(abstract_style.font_family)

161 font_size = self._resolve_font_size(abstract_style.font_size)

162 # Ensure font_size is always an int before using in arithmetic

163 font_size = int(font_size)

164 color = self._resolve_color(abstract_style.color)

165 background_color = self._resolve_background_color(

166 abstract_style.background_color)

167 line_height = self._resolve_line_height(abstract_style.line_height)

168 letter_spacing = self._resolve_letter_spacing(

169 abstract_style.letter_spacing, font_size)

170 word_spacing = self._resolve_word_spacing(

171 abstract_style.word_spacing, font_size)

172 word_spacing_min = self._resolve_word_spacing(

173 abstract_style.word_spacing_min, font_size)

174 word_spacing_max = self._resolve_word_spacing(

175 abstract_style.word_spacing_max, font_size)

176 min_hyphenation_width = max(int(font_size) * 4, 32) # At least 32 pixels

178 # Apply default logic for word spacing constraints

179 if word_spacing_min == 0.0 and word_spacing_max == 0.0:

180 # If no constraints specified, use base word_spacing as reference

181 if word_spacing > 0.0:

182 word_spacing_min = word_spacing

183 word_spacing_max = word_spacing * 2

184 else:

185 # Default constraints when no word spacing is specified

186 word_spacing_min = 2.0 # Minimum 2 pixels

187 word_spacing_max = font_size * 0.5 # Maximum 50% of font size

188 elif word_spacing_min == 0.0:

189 # Only max specified, use base word_spacing or min default

190 word_spacing_min = max(word_spacing, 2.0)

191 elif word_spacing_max == 0.0:

192 # Only min specified, use base word_spacing or reasonable multiple

193 word_spacing_max = max(word_spacing, word_spacing_min * 2)

195 # Create concrete style

196 concrete_style = ConcreteStyle(

197 font_path=font_path,

198 font_size=font_size,

199 color=color,

200 background_color=background_color,

201 weight=abstract_style.font_weight,

202 style=abstract_style.font_style,

203 decoration=abstract_style.text_decoration,

204 text_align=abstract_style.text_align,

205 line_height=line_height,

206 letter_spacing=letter_spacing,

207 word_spacing=word_spacing,

208 word_spacing_min=word_spacing_min,

209 word_spacing_max=word_spacing_max,

210 language=abstract_style.language,

211 min_hyphenation_width=min_hyphenation_width,

212 abstract_style=abstract_style

213 )

215 # Cache and return

216 self._concrete_cache[abstract_style] = concrete_style

217 return concrete_style

219 def _resolve_font_path(self, font_family: FontFamily) -> Optional[str]:

220 """Resolve font family to actual font file path."""

221 if font_family == FontFamily.SERIF: 221 ↛ 223line 221 didn't jump to line 223 because the condition on line 221 was always true

222 return self.context.preferred_serif_font

223 elif font_family == FontFamily.SANS_SERIF:

224 return self.context.preferred_sans_serif_font

225 elif font_family == FontFamily.MONOSPACE:

226 return self.context.preferred_monospace_font

227 else:

228 # For cursive and fantasy, fall back to sans-serif

229 return self.context.preferred_sans_serif_font

230

231 def _resolve_font_size(self, font_size: Union[FontSize, int]) -> int:

232 """Resolve font size to actual pixel/point size."""

233 # Ensure we handle FontSize enums properly

234 if isinstance(font_size, FontSize):

235 # Semantic size, convert to multiplier

236 multiplier = self._semantic_font_sizes.get(font_size, 1.0)

237 base_size = int(self.context.base_font_size * multiplier)

238 elif isinstance(font_size, int): 238 ↛ 243line 238 didn't jump to line 243 because the condition on line 238 was always true

239 # Already a concrete size, apply scaling

240 base_size = font_size

241 else:

242 # Fallback for any other type - try to convert to int

243 try:

244 base_size = int(font_size)

245 except (ValueError, TypeError):

246 # If conversion fails, use default

247 base_size = self.context.base_font_size

249 # Apply global font scaling

250 final_size = int(base_size * self.context.font_scale_factor)

252 # Apply accessibility adjustments

253 if self.context.large_text:

254 final_size = int(final_size * 1.2)

256 # Ensure we always return an int, minimum 8pt font

257 return max(int(final_size), 8)

259 def _resolve_color(

260 self, color: Union[str, Tuple[int, int, int]]) -> Tuple[int, int, int]:

261 """Resolve color to RGB tuple."""

262 if isinstance(color, tuple):

263 return color

265 if isinstance(color, str): 265 ↛ 300line 265 didn't jump to line 300 because the condition on line 265 was always true

266 # Check if it's a named color

267 if color.lower() in self._color_names:

268 base_color = self._color_names[color.lower()]

269 elif color.startswith('#'): 269 ↛ 286line 269 didn't jump to line 286 because the condition on line 269 was always true

270 # Parse hex color

271 try:

272 hex_color = color[1:]

273 if len(hex_color) == 3: 273 ↛ 275line 273 didn't jump to line 275 because the condition on line 273 was never true

274 # Short hex format #RGB -> #RRGGBB

275 hex_color = ''.join(c * 2 for c in hex_color)

276 if len(hex_color) == 6: 276 ↛ 282line 276 didn't jump to line 282 because the condition on line 276 was always true

277 r = int(hex_color[0:2], 16)

278 g = int(hex_color[2:4], 16)

279 b = int(hex_color[4:6], 16)

280 base_color = (r, g, b)

281 else:

282 base_color = (0, 0, 0) # Fallback to black

283 except ValueError:

284 base_color = (0, 0, 0) # Fallback to black

285 else:

286 base_color = (0, 0, 0) # Fallback to black

288 # Apply high contrast if needed

289 if self.context.high_contrast: 289 ↛ 291line 289 didn't jump to line 291 because the condition on line 289 was never true

290 # Simple high contrast: make dark colors black, light colors white

291 r, g, b = base_color

292 brightness = (r + g + b) / 3

293 if brightness < 128:

294 base_color = (0, 0, 0) # Black

295 else:

296 base_color = (255, 255, 255) # White

298 return base_color

300 return (0, 0, 0) # Fallback to black

302 def _resolve_background_color(self,

303 bg_color: Optional[Union[str,

304 Tuple[int,

305 int,

306 int,

307 int]]]) -> Optional[Tuple[int,

308 int,

309 int,

310 int]]:

311 """Resolve background color to RGBA tuple or None."""

312 if bg_color is None: 312 ↛ 315line 312 didn't jump to line 315 because the condition on line 312 was always true

313 return None

314

315 if isinstance(bg_color, tuple):

316 if len(bg_color) == 3:

317 # RGB -> RGBA

318 return bg_color + (255,)

319 return bg_color

321 if isinstance(bg_color, str):

322 if bg_color.lower() == "transparent":

323 return None

325 # Resolve as RGB then add alpha

326 rgb = self._resolve_color(bg_color)

327 return rgb + (255,)

329 return None

331 def _resolve_line_height(self, line_height: Optional[Union[str, float]]) -> float:

332 """Resolve line height to multiplier."""

333 if line_height is None or line_height == "normal": 333 ↛ 336line 333 didn't jump to line 336 because the condition on line 333 was always true

334 return 1.2 # Default line height

336 if isinstance(line_height, (int, float)):

337 return float(line_height)

338

339 if isinstance(line_height, str):

340 try:

341 return float(line_height)

342 except ValueError:

343 return 1.2 # Fallback

345 return 1.2

347 def _resolve_letter_spacing(

348 self, letter_spacing: Optional[Union[str, float]], font_size: int) -> float:

349 """Resolve letter spacing to pixels."""

350 if letter_spacing is None or letter_spacing == "normal": 350 ↛ 353line 350 didn't jump to line 353 because the condition on line 350 was always true

351 return 0.0

353 if isinstance(letter_spacing, (int, float)):

354 return float(letter_spacing)

355

356 if isinstance(letter_spacing, str):

357 if letter_spacing.endswith("em"):

358 try:

359 em_value = float(letter_spacing[:-2])

360 return em_value * font_size

361 except ValueError:

362 return 0.0

363 else:

364 try:

365 return float(letter_spacing)

366 except ValueError:

367 return 0.0

368

369 return 0.0

371 def _resolve_word_spacing(

372 self, word_spacing: Optional[Union[str, float]], font_size: int) -> float:

373 """Resolve word spacing to pixels."""

374 if word_spacing is None or word_spacing == "normal":

375 return 0.0

376

377 if isinstance(word_spacing, (int, float)):

378 return float(word_spacing)

379

380 if isinstance(word_spacing, str): 380 ↛ 393line 380 didn't jump to line 393 because the condition on line 380 was always true

381 if word_spacing.endswith("em"): 381 ↛ 388line 381 didn't jump to line 388 because the condition on line 381 was always true

382 try:

383 em_value = float(word_spacing[:-2])

384 return em_value * font_size

385 except ValueError:

386 return 0.0

387 else:

388 try:

389 return float(word_spacing)

390 except ValueError:

391 return 0.0

393 return 0.0

395 def update_context(self, **kwargs):

396 """

397 Update the rendering context and clear cache.

399 Args:

400 **kwargs: Context properties to update

401 """

402 # Create new context with updates

403 context_dict = {

404 field.name: getattr(self.context, field.name)

405 for field in self.context.__dataclass_fields__.values()

406 }

407 context_dict.update(kwargs)

409 self.context = RenderingContext(**context_dict)

410

411 # Clear cache since context changed

412 self._concrete_cache.clear()

414 def clear_cache(self):

415 """Clear the concrete style cache."""

416 self._concrete_cache.clear()

418 def get_cache_size(self) -> int:

419 """Get the number of cached concrete styles."""

420 return len(self._concrete_cache)

421

422

423class ConcreteStyleRegistry:

424 """

425 Registry for managing concrete styles with efficient caching.

427 This registry manages the mapping between abstract and concrete styles,

428 and provides efficient access to Font objects for rendering.

429 """

431 def __init__(self, resolver: StyleResolver):

432 """

433 Initialize the concrete style registry.

434

435 Args:

436 resolver: StyleResolver for converting abstract to concrete styles

437 """

438 self.resolver = resolver

439 self._font_cache: Dict[ConcreteStyle, Font] = {}

440

441 def get_concrete_style(self, abstract_style: AbstractStyle) -> ConcreteStyle:

442 """

443 Get a concrete style for an abstract style.

444

445 Args:

446 abstract_style: AbstractStyle to resolve

448 Returns:

449 ConcreteStyle with rendering parameters

450 """

451 return self.resolver.resolve_style(abstract_style)

452

453 def get_font(self, abstract_style: AbstractStyle) -> Font:

454 """

455 Get a Font object for an abstract style.

457 Args:

458 abstract_style: AbstractStyle to get font for

459

460 Returns:

461 Font object ready for rendering

462 """

463 concrete_style = self.get_concrete_style(abstract_style)

464

465 # Check font cache

466 if concrete_style in self._font_cache:

467 return self._font_cache[concrete_style]

468

469 # Create and cache font

470 font = concrete_style.create_font()

471 self._font_cache[concrete_style] = font

472

473 return font

475 def clear_caches(self):

476 """Clear all caches."""

477 self.resolver.clear_cache()

478 self._font_cache.clear()

479

480 def get_cache_stats(self) -> Dict[str, int]:

481 """Get cache statistics."""

482 return {

483 "concrete_styles": self.resolver.get_cache_size(),

484 "fonts": len(self._font_cache)

485 }

+ + + diff --git a/cov_info/htmlcov/z_ba7f6bdeb0188088_fonts_py.html b/cov_info/htmlcov/z_ba7f6bdeb0188088_fonts_py.html new file mode 100644 index 0000000..b4e94c0 --- /dev/null +++ b/cov_info/htmlcov/z_ba7f6bdeb0188088_fonts_py.html @@ -0,0 +1,505 @@ + + + + + Coverage for pyWebLayout/style/fonts.py: 66% + + + + + +

+ Coverage for pyWebLayout/style/fonts.py: + 66% +

+ + + Show/hide keyboard shortcuts

+ +

Shortcuts on this page

+ r + m + x + p + toggle line displays +

+ j + k + next/prev highlighted chunk +

+ 0 (zero) top of page +

+ 1 (one) first highlighted chunk +

+ [ + ] + prev/next file +

+ u up to the index +

+ ? show/hide this help +

+ 161 statements + + + + +

+ « prev + ^ index + » next + + coverage.py v7.15.4, + created at 2026-08-08 20:34 +0000 +

+ +

1# this should contain classes for how different object can be rendered,

2# e.g. bold, italic, regular

3from PIL import ImageFont

4from enum import Enum

5from typing import Tuple, Optional, Dict

6import os

7import logging

9# Set up logging for font loading

10logger = logging.getLogger(__name__)

12# Global cache for PIL ImageFont objects to avoid reloading fonts from disk

13# Key: (font_path, font_size), Value: PIL ImageFont object

14_FONT_CACHE: Dict[Tuple[Optional[str], int], ImageFont.FreeTypeFont] = {}

16# Cache for bundled font path to avoid repeated filesystem lookups

17_BUNDLED_FONT_PATH: Optional[str] = None

19# Cache for bundled fonts directory

20_BUNDLED_FONTS_DIR: Optional[str] = None

23class FontWeight(Enum):

24 NORMAL = "normal"

25 BOLD = "bold"

28class FontStyle(Enum):

29 NORMAL = "normal"

30 ITALIC = "italic"

33class TextDecoration(Enum):

34 NONE = "none"

35 UNDERLINE = "underline"

36 STRIKETHROUGH = "strikethrough"

39class BundledFont(Enum):

40 """Bundled font families available in pyWebLayout"""

41 SANS = "sans" # DejaVu Sans - modern sans-serif

42 SERIF = "serif" # DejaVu Serif - classic serif

43 MONOSPACE = "monospace" # DejaVu Sans Mono - fixed-width

46def get_bundled_fonts_dir():

47 """

48 Get the directory containing bundled fonts (cached).

50 Returns:

51 str: Path to the fonts directory, or None if not found

52 """

53 global _BUNDLED_FONTS_DIR

55 # Return cached path if available

56 if _BUNDLED_FONTS_DIR is not None:

57 return _BUNDLED_FONTS_DIR

59 # First time - determine the path and cache it

60 current_dir = os.path.dirname(os.path.abspath(__file__))

61 fonts_dir = os.path.join(os.path.dirname(current_dir), 'assets', 'fonts')

63 if os.path.exists(fonts_dir) and os.path.isdir(fonts_dir):

64 _BUNDLED_FONTS_DIR = fonts_dir

65 logger.debug(f"Found bundled fonts directory at: {fonts_dir}")

66 return fonts_dir

67 else:

68 logger.warning(f"Bundled fonts directory not found at: {fonts_dir}")

69 _BUNDLED_FONTS_DIR = "" # Empty string to indicate "checked but not found"

70 return None

73def get_bundled_font_path(

74 family: BundledFont = BundledFont.SANS,

75 weight: FontWeight = FontWeight.NORMAL,

76 style: FontStyle = FontStyle.NORMAL

77) -> Optional[str]:

78 """

79 Get the path to a specific bundled font file.

81 Args:

82 family: The font family (SANS, SERIF, or MONOSPACE)

83 weight: The font weight (NORMAL or BOLD)

84 style: The font style (NORMAL or ITALIC)

86 Returns:

87 str: Full path to the font file, or None if not found

89 Example:

90 >>> # Get bold italic sans font

91 >>> path = get_bundled_font_path(BundledFont.SANS, FontWeight.BOLD, FontStyle.ITALIC)

92 >>> font = Font(font_path=path, font_size=16)

93 """

94 fonts_dir = get_bundled_fonts_dir()

95 if not fonts_dir:

96 return None

98 # Map font parameters to filename

99 family_map = {

100 BundledFont.SANS: "DejaVuSans",

101 BundledFont.SERIF: "DejaVuSerif",

102 BundledFont.MONOSPACE: "DejaVuSansMono"

103 }

105 base_name = family_map.get(family, "DejaVuSans")

107 # Build the font file name

108 parts = [base_name]

110 if weight == FontWeight.BOLD and style == FontStyle.ITALIC:

111 # Special case: both bold and italic

112 if family == BundledFont.MONOSPACE:

113 parts.append("BoldOblique")

114 elif family == BundledFont.SERIF:

115 parts.append("BoldItalic")

116 else: # SANS

117 parts.append("BoldOblique")

118 elif weight == FontWeight.BOLD:

119 parts.append("Bold")

120 elif style == FontStyle.ITALIC:

121 # Italic naming differs by family

122 if family == BundledFont.MONOSPACE or family == BundledFont.SANS:

123 parts.append("Oblique")

124 else: # SERIF

125 parts.append("Italic")

127 filename = "-".join(parts) + ".ttf"

128 font_path = os.path.join(fonts_dir, filename)

129

130 if os.path.exists(font_path):

131 logger.debug(f"Found bundled font: {filename}")

132 return font_path

133 else:

134 logger.warning(f"Bundled font not found: {filename}")

135 return None

136

138class Font:

139 """

140 Font class to manage text rendering properties including font face, size, color, and styling.

141 This class is used by the text renderer to determine how to render text.

142 """

143

144 def __init__(self,

145 font_path: Optional[str] = None,

146 font_size: int = 16,

147 colour: Tuple[int, int, int] = (0, 0, 0),

148 weight: FontWeight = FontWeight.NORMAL,

149 style: FontStyle = FontStyle.NORMAL,

150 decoration: TextDecoration = TextDecoration.NONE,

151 background: Optional[Tuple[int, int, int, int]] = None,

152 language="en_EN",

153 min_hyphenation_width: Optional[int] = None):

154 """

155 Initialize a Font object with the specified properties.

157 Args:

158 font_path: Path to the font file (.ttf, .otf). If None, uses default bundled font.

159 font_size: Size of the font in points.

160 colour: RGB color tuple for the text.

161 weight: Font weight (normal or bold).

162 style: Font style (normal or italic).

163 decoration: Text decoration (none, underline, or strikethrough).

164 background: RGBA background color for the text. If None, transparent background.

165 language: Language code for hyphenation and text processing.

166 min_hyphenation_width: Minimum width in pixels required for hyphenation to be considered.

167 If None, defaults to 4 times the font size.

168 """

169 self._font_path = font_path

170 self._font_size = font_size

171 self._colour = colour

172 self._weight = weight

173 self._style = style

174 self._decoration = decoration

175 self._background = background if background else (255, 255, 255, 0)

176 self.language = language

177 self._min_hyphenation_width = min_hyphenation_width if min_hyphenation_width is not None else font_size * 4

178 # Load the font file or use default

179 self._load_font()

181 @classmethod

182 def from_family(cls,

183 family: BundledFont = BundledFont.SANS,

184 font_size: int = 16,

185 colour: Tuple[int, int, int] = (0, 0, 0),

186 weight: FontWeight = FontWeight.NORMAL,

187 style: FontStyle = FontStyle.NORMAL,

188 decoration: TextDecoration = TextDecoration.NONE,

189 background: Optional[Tuple[int, int, int, int]] = None,

190 language: str = "en_EN",

191 min_hyphenation_width: Optional[int] = None) -> 'Font':

192 """

193 Create a Font using a bundled font family.

195 This is a convenient way to use the bundled DejaVu fonts without needing to

196 specify paths manually.

198 Args:

199 family: The font family to use (SANS, SERIF, or MONOSPACE)

200 font_size: Size of the font in points.

201 colour: RGB color tuple for the text.

202 weight: Font weight (normal or bold).

203 style: Font style (normal or italic).

204 decoration: Text decoration (none, underline, or strikethrough).

205 background: RGBA background color for the text. If None, transparent background.

206 language: Language code for hyphenation and text processing.

207 min_hyphenation_width: Minimum width in pixels required for hyphenation.

208

209 Returns:

210 Font object configured with the bundled font

212 Example:

213 >>> # Create a bold serif font

214 >>> font = Font.from_family(BundledFont.SERIF, font_size=18, weight=FontWeight.BOLD)

215 >>>

216 >>> # Create an italic monospace font

217 >>> code_font = Font.from_family(BundledFont.MONOSPACE, style=FontStyle.ITALIC)

218 """

219 font_path = get_bundled_font_path(family, weight, style)

220 return cls(

221 font_path=font_path,

222 font_size=font_size,

223 colour=colour,

224 weight=weight,

225 style=style,

226 decoration=decoration,

227 background=background,

228 language=language,

229 min_hyphenation_width=min_hyphenation_width

230 )

232 def _get_bundled_font_path(self):

233 """Get the path to the bundled font (cached)"""

234 global _BUNDLED_FONT_PATH

236 # Return cached path if available

237 if _BUNDLED_FONT_PATH is not None:

238 return _BUNDLED_FONT_PATH

240 # First time - determine the path and cache it

241 # Get the directory containing this module

242 current_dir = os.path.dirname(os.path.abspath(__file__))

243 # Navigate to the assets/fonts directory

244 assets_dir = os.path.join(os.path.dirname(current_dir), 'assets', 'fonts')

245 bundled_font_path = os.path.join(assets_dir, 'DejaVuSans.ttf')

246

247 logger.debug(f"Font loading: current_dir = {current_dir}")

248 logger.debug(f"Font loading: assets_dir = {assets_dir}")

249 logger.debug(f"Font loading: bundled_font_path = {bundled_font_path}")

250 logger.debug(

251 f"Font loading: bundled font exists = {os.path.exists(bundled_font_path)}"

252 )

253

254 if os.path.exists(bundled_font_path): 254 ↛ 259line 254 didn't jump to line 259 because the condition on line 254 was always true

255 logger.info(f"Found bundled font at: {bundled_font_path}")

256 _BUNDLED_FONT_PATH = bundled_font_path

257 return bundled_font_path

258 else:

259 logger.warning(f"Bundled font not found at: {bundled_font_path}")

260 # Cache None to indicate bundled font is not available

261 _BUNDLED_FONT_PATH = "" # Use empty string instead of None to differentiate from "not checked yet"

262 return None

263

264 def _load_font(self):

265 """Load the font using PIL's ImageFont with consistent bundled font and caching"""

266 # Determine the actual font path to use

267 font_path_to_use = self._font_path

268 if not font_path_to_use:

269 font_path_to_use = self._get_bundled_font_path()

271 # Create cache key

272 cache_key = (font_path_to_use, self._font_size)

273

274 # Check if font is already cached

275 if cache_key in _FONT_CACHE:

276 self._font = _FONT_CACHE[cache_key]

277 logger.debug(f"Reusing cached font: {font_path_to_use} at size {self._font_size}")

278 return

280 # Font not cached, need to load it

281 try:

282 if self._font_path:

283 # Use specified font path

284 logger.info(f"Loading font from specified path: {self._font_path}")

285 self._font = ImageFont.truetype(

286 self._font_path,

287 self._font_size

288 )

289 logger.info(f"Successfully loaded font from: {self._font_path}")

290 else:

291 # Use bundled font for consistency across environments

292 bundled_font_path = self._get_bundled_font_path()

293

294 if bundled_font_path: 294 ↛ 303line 294 didn't jump to line 303 because the condition on line 294 was always true

295 logger.info(f"Loading bundled font from: {bundled_font_path}")

296 self._font = ImageFont.truetype(bundled_font_path, self._font_size)

297 logger.info(

298 f"Successfully loaded bundled font at size {self._font_size}"

299 )

300 else:

301 # Only fall back to PIL's default font if bundled font is not

302 # available

303 logger.warning(

304 "Bundled font not available, falling back to PIL default font")

305 self._font = ImageFont.load_default()

307 # Cache the loaded font

308 _FONT_CACHE[cache_key] = self._font

309 logger.debug(f"Cached font: {font_path_to_use} at size {self._font_size}")

311 except Exception as e:

312 # Ultimate fallback to default font

313 logger.error(f"Failed to load font: {e}, falling back to PIL default font")

314 self._font = ImageFont.load_default()

315 # Don't cache the default font as it doesn't have a path

317 @property

318 def font(self):

319 """Get the PIL ImageFont object"""

320 return self._font

322 @property

323 def font_size(self):

324 """Get the font size"""

325 return self._font_size

327 @property

328 def colour(self):

329 """Get the text color"""

330 return self._colour

332 @property

333 def color(self):

334 """Alias for colour (American spelling)"""

335 return self._colour

336

337 @property

338 def background(self):

339 """Get the background color"""

340 return self._background

342 @property

343 def weight(self):

344 """Get the font weight"""

345 return self._weight

347 @property

348 def style(self):

349 """Get the font style"""

350 return self._style

351

352 @property

353 def decoration(self):

354 """Get the text decoration"""

355 return self._decoration

356

357 @property

358 def min_hyphenation_width(self):

359 """Get the minimum width required for hyphenation to be considered"""

360 return self._min_hyphenation_width

362 def _with_modified(self, **kwargs):

363 """

364 Internal helper to create a new Font with modified parameters.

365

366 This consolidates the duplication across all with_* methods.

368 Args:

369 **kwargs: Parameters to override (e.g., font_size=20, colour=(255,0,0))

371 Returns:

372 New Font object with modified parameters

373 """

374 params = {

375 'font_path': self._font_path,

376 'font_size': self._font_size,

377 'colour': self._colour,

378 'weight': self._weight,

379 'style': self._style,

380 'decoration': self._decoration,

381 'background': self._background,

382 'language': self.language,

383 'min_hyphenation_width': self._min_hyphenation_width

384 }

385 params.update(kwargs)

386 return Font(**params)

388 def with_size(self, size: int):

389 """Create a new Font object with modified size"""

390 return self._with_modified(font_size=size)

392 def with_colour(self, colour: Tuple[int, int, int]):

393 """Create a new Font object with modified colour"""

394 return self._with_modified(colour=colour)