page.insert_htmlbox raises ValueError: 'text' must be a string or a Story

[0nobody0]

Description of the bug

hello. a test page from a pdf with a text layer was translated successfully using https://medium.com/@pymupdf/translating-pdfs-a-practical-pymupdf-guide-c1c54b024042 as a template.

When processing the full 200 page document with python3 -v translator.py test.pdf the following ValueError shows up:

Traceback (most recent call last):
  File "/home/user/pymupdf/translator.py", line 37, in <module>
    page.insert_htmlbox(
  File "/home/user/pymupdf/lib/python3.12/site-packages/pymupdf/__init__.py", line 12376, in insert_htmlbox
    raise ValueError("'text' must be a string or a Story")
ValueError: 'text' must be a string or a Story

How to reproduce the bug

using Python 3.12.3 and PyMuPDF 1.26.6 in a venv with:

python3 -m venv pymupdf
source pymupdf/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install deep-translator
python3 -m pip install pymupdf

python3 -v translator.py test.pdf is run with this translator.py:

import pymupdf
from deep_translator import GoogleTranslator

# Define color "white"
WHITE = pymupdf.pdfcolor["white"]

# This flag ensures that text will be dehyphenated after extraction.
textflags = pymupdf.TEXT_DEHYPHENATE

# Configure the desired translator
to_english = GoogleTranslator(source="da", target="en")

# Open the document
doc = pymupdf.open("test.pdf")

# Define an Optional Content layer in the document named "English".
# Activate it by default.
ocg_xref = doc.add_ocg("English", on=True)

# Iterate over all pages
for page in doc:
    # Extract text grouped like lines in a paragraph.
    blocks = page.get_text("blocks", flags=textflags)

    # Every block of text is contained in a rectangle ("bbox")
    for block in blocks:
        bbox = block[:4]  # area containing the text
        text = block[4]  # the text of this block

        # Invoke the actual translation to deliver us an English string
        english = to_english.translate(text)

        # Cover the Danish text with a white rectangle.
        page.draw_rect(bbox, color=None, fill=WHITE, oc=ocg_xref)

        # Write the English text into the original rectangle
        page.insert_htmlbox(
            bbox, english, css="* {font-family: sans-serif;}", oc=ocg_xref
        )

doc.subset_fonts()
doc.ez_save("test_english.pdf")

After a minute or two the process crashes with:

Traceback (most recent call last):
  File "/home/user/pymupdf/translator.py", line 37, in <module>
    page.insert_htmlbox(
  File "/home/user/pymupdf/lib/python3.12/site-packages/pymupdf/__init__.py", line 12376, in insert_htmlbox
    raise ValueError("'text' must be a string or a Story")
ValueError: 'text' must be a string or a Story

PyMuPDF version

1.26.6

Operating system

Linux

Python version

3.12

[JorjMcKie]

... and how do you know that this is a bug?
What was the type of object text when the crash occurred?

[JorjMcKie]

Please provide the test file and insert a check for the type of the returned "english" object.
This is actually not a bug but a Discussions item ... transferring.

[0nobody0]

apologies, pardon my ignorance. i added

        print(english)
        print(type(english))

before page.inserthtmlbox and found the script was crashing when the english object was None / <class 'NoneType'>

i added this check: if type(english) is str: before page.inserthtmlbox - not sure if this is adequate, testing now and it looks like it's going to take a little while to run.

[JorjMcKie]

Ok, well done.
Yes, this method is not the fastest in the world. But consider everything it does each time:

• Parse the text with an HTML lexer,
• determine character by character which font is required (after all you can have an arbitrary mix of languages, colors, font weights and font styles in there),
• then invoke Harfbuzz to transform it in complex scripts (like Devanagari) where necessary,
• then perform a mathematical iteration for optimum exploitation (scaling) of the available space, each time distributing the words across the available lines in a different way ...