DOC: Watermark and stamp (#1095)

See #307

docs/user/add-watermark.md

@@ -10,57 +10,76 @@ content stays the same.
 ## Stamp (Overlay)
 
 ```python
-from PyPDF2 import PdfWriter, PdfReader
-
-
-def stamp(content_page, image_page):
-    """Put the image over the content"""
-    # Note that this modifies the content_page in-place!
-    content_page.merge_page(image_page)
-    return content_page
-
+from pathlib import Path
+from typing import Union, Literal, List
 
-# Read the pages
-reader_content = PdfReader("content.pdf")
-reader_image = PdfReader("image.pdf")
+from PyPDF2 import PdfWriter, PdfReader
 
-# Modify it
-modified = stamp(reader_content.pages[0], reader_image.pages[0])
 
-# Create the new document
-writer = PdfWriter()
-writer.add_page(modified)
-with open("out-stamp.pdf", "wb") as fp:
-    writer.write(fp)
+def stamp(
+    content_pdf: Path,
+    stamp_pdf: Path,
+    pdf_result: Path,
+    page_indices: Union[Literal["ALL"], List[int]] = "ALL",
+):
+    reader = PdfReader(stamp_pdf)
+    image_page = reader.pages[0]
+
+    writer = PdfWriter()
+
+    reader = PdfReader(content_pdf)
+    if page_indices == "ALL":
+        page_indices = list(range(0, len(reader.pages)))
+    for index in page_indices:
+        content_page = reader.pages[index]
+        mediabox = content_page.mediabox
+        content_page.merge_page(image_page)
+        content_page.mediabox = mediabox
+        writer.add_page(content_page)
+
+    with open(pdf_result, "wb") as fp:
+        writer.write(fp)
 ```
 
 ![stamp.png](stamp.png)
 
 ## Watermark (Underlay)
 
 ```python
+from pathlib import Path
+from typing import Union, Literal, List
+
 from PyPDF2 import PdfWriter, PdfReader
 
 
-def watermark(content_page, image_page):
-    """Put the image under the content"""
-    # Note that this modifies the image_page in-place!
-    image_page.merge_page(content_page)
-    return image_page
+def watermark(
+    content_pdf: Path,
+    stamp_pdf: Path,
+    pdf_result: Path,
+    page_indices: Union[Literal["ALL"], List[int]] = "ALL",
+):
+    reader = PdfReader(content_pdf)
+    if page_indices == "ALL":
+        page_indices = list(range(0, len(reader.pages)))
+
+    reader_stamp = PdfReader(stamp_pdf)
+    image_page = reader_stamp.pages[0]
 
+    writer = PdfWriter()
+    for index in page_indices:
+        content_page = reader.pages[index]
+        mediabox = content_page.mediabox
 
-# Read the pages
-reader_content = PdfReader("content.pdf")
-reader_image = PdfReader("image.pdf")
+        # You need to load it again, as the last time it was overwritten
+        reader_stamp = PdfReader(stamp_pdf)
+        image_page = reader_stamp.pages[0]
 
-# Modify it
-modified = stamp(reader_content.pages[0], reader_image.pages[0])
+        image_page.merge_page(content_page)
+        image_page.mediabox = mediabox
+        writer.add_page(image_page)
 
-# Create the new document
-writer = PdfWriter()
-writer.add_page(modified)
-with open("out-watermark.pdf", "wb") as fp:
-    writer.write(fp)
+    with open(pdf_result, "wb") as fp:
+        writer.write(fp)
 ```
 
 ![watermark.png](watermark.png)