pyWebLayout/pyWebLayout/layout/README_EREADER_API.md

EbookReader API Quick Reference

This is a quick reference for the EbookReader class API.

Import

from pyWebLayout.layout.ereader_application import EbookReader

Constructor

EbookReader(
    page_size=(800, 1000),             # Page dimensions (width, height)
    margin=40,                          # Page margin in pixels
    background_color=(255, 255, 255),   # Background RGB color
    line_spacing=5,                     # Line spacing in pixels
    inter_block_spacing=15,             # Block spacing in pixels
    bookmarks_dir="ereader_bookmarks",  # Bookmark directory
    buffer_size=5                       # Number of pages to cache
)

Loading & Book Info

Method	Returns	Description
load_epub(path)	bool	Load an EPUB file
is_loaded()	bool	Check if book is loaded
get_book_info()	dict	Get book metadata and stats

Navigation

Method	Returns	Description
get_current_page()	PIL.Image	Get current page as image
next_page()	PIL.Image or None	Navigate forward
previous_page()	PIL.Image or None	Navigate backward
render_to_file(path)	bool	Save current page to file

Position Management

Method	Returns	Description
save_position(name)	bool	Save current position
load_position(name)	PIL.Image or None	Load saved position
list_saved_positions()	List[str]	List all saved positions
delete_position(name)	bool	Delete a saved position
get_position_info()	dict	Get detailed position info
get_reading_progress()	float	Get progress (0.0-1.0)

Chapter Navigation

Method	Returns	Description
get_chapters()	List[Tuple[str, int]]	Get list of chapters
get_chapter_positions()	List[Tuple[str, RenderingPosition]]	Get chapters with positions
jump_to_chapter(chapter)	PIL.Image or None	Jump to chapter by title or index
get_current_chapter_info()	dict or None	Get current chapter info

Font & Styling

Method	Returns	Description
get_font_size()	float	Get current font scale
set_font_size(scale)	PIL.Image	Set font scale (0.5-3.0)
increase_font_size()	PIL.Image	Increase font by 10%
decrease_font_size()	PIL.Image	Decrease font by 10%
set_line_spacing(pixels)	PIL.Image	Set line spacing
set_inter_block_spacing(pixels)	PIL.Image	Set block spacing

Cleanup

Method	Returns	Description
close()	None	Close reader and save position

Context Manager

with EbookReader() as reader:
    reader.load_epub("book.epub")
    # ... use reader
# Automatically closes and saves position

Minimal Example

from pyWebLayout.layout.ereader_application import EbookReader

# Create and load
reader = EbookReader(page_size=(800, 1000))
reader.load_epub("book.epub")

# Navigate
page = reader.get_current_page()
page.save("page1.png")
reader.next_page()

# Save position
reader.save_position("bookmark1")

# Close
reader.close()

Common Patterns

Reading through a book

with EbookReader() as reader:
    reader.load_epub("book.epub")
    
    page_num = 1
    while True:
        page = reader.get_current_page()
        if not page:
            break
        
        page.save(f"page_{page_num:03d}.png")
        
        if not reader.next_page():
            break  # End of book
        
        page_num += 1

Chapter-based navigation

reader = EbookReader()
reader.load_epub("book.epub")

# List chapters
chapters = reader.get_chapters()
for title, idx in chapters:
    print(f"Chapter {idx}: {title}")

# Jump to chapter
reader.jump_to_chapter(2)  # By index
reader.jump_to_chapter("Chapter 3")  # By title

Font size adjustment

reader = EbookReader()
reader.load_epub("book.epub")

# Simple increase/decrease
reader.increase_font_size()
reader.decrease_font_size()

# Or set specific scale
reader.set_font_size(1.5)  # 150% size

Position persistence

# Save multiple bookmarks
reader.save_position("chapter_1_start")
reader.next_page()
reader.next_page()
reader.save_position("interesting_quote")

# List all bookmarks
bookmarks = reader.list_saved_positions()

# Load a bookmark
reader.load_position("chapter_1_start")

# Delete a bookmark
reader.delete_position("old_bookmark")

Position Format

Positions are stored as JSON in {bookmarks_dir}/{document_id}_bookmarks.json:

{
  "chapter_index": 0,
  "block_index": 42,
  "word_index": 15,
  "table_row": 0,
  "table_col": 0,
  "list_item_index": 0,
  "remaining_pretext": null,
  "page_y_offset": 0
}

Positions remain valid across:

• Font size changes
• Line spacing changes
• Page size changes
• Block spacing changes

See Also

• examples/README_EREADER.md - Full documentation with examples
• examples/simple_ereader_example.py - Simple usage example
• examples/ereader_demo.py - Comprehensive feature demo