The Complete Production SOP: How to Deploy and Run pypdf Document Manipulator in Autonomous AI Agents

---
name: "pypdf-document-manipulator"
description: "Merge, split, rotate, watermark, and encrypt PDF files using pure Python pypdf."
metadata:
  author: "py-pdf"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "merge multiple pdf files"
  - "add watermark to pdf python"
  - "encrypt pdf with password pypdf"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# pypdf Document Manipulator SOP
1. Always import from `pypdf` (never `PyPDF2`).
2. Use `PdfReader(file_handle)` and `PdfWriter()` with context managers.
3. Watermark by calling `target_page.merge_page(watermark_page)`.
4. Apply encryption via `writer.encrypt(user_password, owner_pwd, algorithm='AES-256')`.
5. Write changes deterministically to a new output file before replacing inputs.

import os
from pathlib import Path
from pypdf import PdfReader, PdfWriter

def secure_merge_and_watermark(input_paths: list[Path], watermark_path: Path, output_path: Path) -> None:
    writer = PdfWriter()
    watermark_reader = PdfReader(watermark_path)
    watermark_page = watermark_reader.pages[0]
    
    for doc_path in input_paths:
        reader = PdfReader(doc_path)
        for page in reader.pages:
            page.merge_page(watermark_page)
            writer.add_page(page)
            
    encryption_pwd = os.environ.get("PDF_ENCRYPTION_KEY")
    if encryption_pwd:
        writer.encrypt(encryption_pwd, algorithm="AES-256")
        
    with open(output_path, "wb") as f_out:
        writer.write(f_out)

# Example invocation command for Claude Code CLI or Codex CLI
claude --print \
  "Execute deterministic document compilation: merge multiple pdf files from ./docs, apply watermark, output to ./dist/final.pdf"

import os
from pathlib import Path
from pypdf import PdfReader

def test_output_integrity():
    output_file = Path("dist/final.pdf")
    assert output_file.exists(), "Output PDF was not generated"
    
    reader = PdfReader(output_file)
    if reader.is_encrypted:
        pwd = os.environ.get("PDF_ENCRYPTION_KEY", "")
        result = reader.decrypt(pwd)
        assert result > 0, "Decryption failed for generated artifact"
        
    assert len(reader.pages) > 0, "Generated PDF has zero pages"