`show_pdf_page` does not like empty pages created by `new_page`

[sliedes]

Description of the bug

Not sure if this is a bug; I worked around it by drawing a white rectangle. It feels a bit surprising.

new_page is documented as producing an empty page (I use it to add empty pages in front of an existing PDF). Nevertheless, using them in show_pdf_page fails.

How to reproduce the bug

import fitz

src_doc = fitz.open()
blank = src_doc.new_page(width=595, height=842)

target_doc = fitz.open()
page = target_doc.new_page(width=595, height=842)

page.show_pdf_page(fitz.Rect(0, 0, 595, 842), blank.parent, blank.number)

Result:

Traceback (most recent call last):
  File "/home/sliedes/proj/imposition/bug.py", line 12, in <module>
    page.show_pdf_page(fitz.Rect(0, 0, 595, 842), blank.parent, blank.number)
  File "/home/sliedes/proj/imposition/.venv/lib/python3.12/site-packages/pymupdf/utils.py", line 178, in show_pdf_page
    raise ValueError("nothing to show - source page empty")
ValueError: nothing to show - source page empty

PyMuPDF version

1.26.0

Operating system

Linux

Python version

3.12

[JorjMcKie]

This is no bug but works as intended.
The reason should be obvious.
Let me rephrase this:
A page created via doc.new_page() has no /Contents object at all, as long as there never has been inserted anything.
In this state, there is nothing that can be converted to the object type ("Form XObject") needed for show_pdf_page.
Insert something / anything and it will work.

[sliedes]

Let me rephrase this: A page created via doc.new_page() has no /Contents object at all, as long as there never has been inserted anything. In this state, there is nothing that can be converted to the object type ("Form XObject") needed for show_pdf_page. Insert something / anything and it will work.

Yes, I understand why this happens. Nevertheless, the documentation said doc.new_page "inserts an empty page" and it is used in examples to add empty pages to documents, so purely from the documentation, I would have assumed using it to simply pad a document with empty pages to work. Apparently it works in some cases but doesn't in others. A documentation issue then? :)

[JorjMcKie]

I have discussed your post with a colleague.
I certainly do understand the confusion. Method doc.new_page() strives to create a new PDF page of the minimum possible size and thus does not give it a /Contents object - not even an empty one.

Method page.show_pdf_page() does not display the source page itself. Instead it converts it into a different PDF object type (a so-called "Form XObject") which is then shown in the target page.
Form XObjects are stream objects. The concatenated source page's /Contents objects are used as the Form XObject's stream during this conversion.
There is no problem if the source page has a contents stream - even if empty - but currently an exception is raised if no source contents stream exists at all.

As you can see, it takes a while to explain all this. So we discussed what best can be done to avoid too much effort. It is after all a corner case with no practical importance.
But on the other hand it certainly is a rough edge that should be addressed.
I tend to favor simply creating a Form XObject with an empty (b"") stream in this case. Easy to do and low documentation effort.

[sliedes]

Makes sense!

Would there be a downside for show_pdf_page just treating a missing stream as an empty stream? Or would that be more of a hack?

I agree, it doesn't seem particularly important.

[JorjMcKie]

Well, nothing would be shown in the target, that's all - apart from that the target PDF will become 500 bytes or so larger for nothing.

[JorjMcKie]

I am going to reopen this to make the change as discussed int this post: When using a page without /Contents in Page.show_pdf_page() still create the respective Form XObject in the target page giving it an empty stream b"".

[julian-smith-artifex-com]

Fixed in PyMuPDF-1.26.1.