Support for merging a page in the background (watermark)

[hvbtup]

I propose adding an optional argument background=False to the various merge...Page methods.
All these methods finally go into _mergePage. There, the following little change should to the trick:

    newContentArray = ArrayObject()

    originalContent = self.getContents()
    if originalContent is not None:
        newContentArray.append(PageObject._pushPopGS(
              originalContent, self.pdf))

    page2Content = page2.getContents()
    if page2Content is not None:
        if page2transformation is not None:
            page2Content = page2transformation(page2Content)
        page2Content = PageObject._contentStreamRename(
            page2Content, rename, self.pdf)
        page2Content = PageObject._pushPopGS(page2Content, self.pdf)
        if background:
            newContentArray.insert(0, page2Content)
        else:
            newContentArray.append(page2Content)

[hvbtup]

This is the patch for PyPDF2/pdf.py.
pdf.patch.txt

[hvbtup]

I have not tested your code, but I think your example is probably too simple. The typical use case is:
You have a multi-page source PDF (say, 5 pages) and a stamp/watermark PDF (for example, containing a big text "for internal use" or "copy").
Now you want to create a destination PDF which consists of the source PDF plus the stamp above or the watermark below the content of each page.

Since your example code for creating a watermark modifies the image page in-place, I don't think it will work for this use case.

[MartinThoma]

What do you think would go wrong?

(As an important side-note: You need to copy the watermark or re-load it every time, of course)

[hvbtup]

You need to copy the watermark or re-load it every time, of course

Would that be cumbersome and counter-intuitive?

I think the approach to specify wether the "image page" should go above or below the existing content with an optional argument is much more user-friendly.

BTW The well-known Java iText PDF library uses the words "OverContent" and "UnderContent" for this, but people don't understand that (https://stackoverflow.com/questions/66029258/difference-between-getundercontent-and-getovercontent-of-itext). IMHO the wording "background" for a boolean argument is more clear, but I'm biased of course.

[MartinThoma]

An image says more than 1000 words: https://pypdf2.readthedocs.io/en/latest/user/add-watermark.html 😄

I want to keep the public interface of PyPDF2 small and hence I hesitate to add such features which are easy to do on the users side. But I get your point that users might not understand that they need to copy the page.

I think I'll wait and see how many people open stackoverflow questions / issues here. If this is really an issue, adding this feature is pretty easy.

[MartinThoma]

Oh, and I should adjust the docs to make a copy so that people who simply copy-and-paste don't fall into this trap

[MartinThoma]

#1095

[hvbtup]

It's good that you show a complete example in add-watermark.md.

Of course parsing the stamp file inside the loop with

reader_stamp = PdfReader(stamp_pdf)

will cost some performance. I hope this isnt' really an issue.

If it turns out to be an issue, one could still modify PyPDF2 to use my approach instead.

[MartinThoma]

I completely agree that this is not ideal. I actually thought it would be simpler - using copy.deepcopy or maybe a method of PageObject that allows to create a copy of itself (e.g. page.clone() or similar).

Turns out, that page.clone() does not exist and deepcopy does not work :-/