feat: Add recipe system

Author: MPCodeWriter21

.pre-commit-config.yaml

@@ -7,7 +7,6 @@ repos:
     -   id: trailing-whitespace
     -   id: check-yaml
     -   id: check-added-large-files
-    -   id: double-quote-string-fixer
 
   # Python-specific hooks
   - repo: https://github.com/google/yapf

README.md

@@ -11,19 +11,20 @@ Features
   + [x] Image inputs (e.g. PNG, JPG, etc.)
   + [ ] Markdown inputs
 + [x] **Merge PDFs**: Merge multiple PDFs into one PDF
-+ [x] **Split PDFs**: Split a PDF into multiple PDFs, each containing a range of pages from
-      the original PDF
++ [x] **Split PDFs**: Split a PDF into multiple PDFs, each containing a range of pages
 + [x] **Export as image**: Export designated pages from a PDF as image files
 + [x] **Remove pages**: Remove designated pages from a PDF
++ [x] **Extract text**: Export text from a PDF file and optionally save it to a text file
++ [x] **Recipe system**: Chain multiple operations together using YAML recipe files
++ [ ] Add watermark to a PDF
 + [ ] Encrypt a PDF
 + [ ] Decrypt a PDF
-+ [ ] Add watermark to a PDF
 + [ ] Extract images from a PDF
-+ [x] **Extract text**: Export text from a PDF file and optionally save it to a text file
 + [ ] Extract links from a PDF
++ [ ] Set PDF metadata (title, author, etc.)
 
-If you want any other feature to be added, feel free to open an [issue](https://github.com/MPCodeWriter21/PDF-To-Image/issues)
-or fork the repo and make a [pull request](https://github.com/MPCodeWriter21/PDF-To-Image/pulls)
+If you want any other feature to be added, feel free to open an [issue](https://github.com/MPCodeWriter21/PDF-Helper/issues)
+or fork the repo and make a [pull request](https://github.com/MPCodeWriter21/PDF-Helper/pulls)
 after adding your contribution.
 
 Usage
@@ -67,8 +68,8 @@ Bundle multiple files into one PDF:
 ```bash
 pdf-helper bundle <input_file_1> <input_file_2>... <input_file_n> <output_file>
 
-# E.g. Merge PDFs 1, 2 and 3 into a new PDF
-pdf-helper merge 1.pdf 2.pdf 3.pdf new.pdf
+# E.g. Bundle PDFs 1, 2 and 3 into a new PDF
+pdf-helper bundle 1.pdf 2.pdf 3.pdf new.pdf
 
 # E.g. Take 1.png, 2.jpg, and 3.png and create a PDF named 123.pdf and override
 # if already exists
@@ -130,6 +131,117 @@ pdf-helper extract-text <input_file> -o <output_file_name>
 pdf-helper extract-text my-pdf.pdf -o my-text.txt
 ```
 
+### Run Recipes
+
+The recipe system lets you chain multiple PDF operations together in a single run
+using a YAML file. This unlocks features not available through individual CLI
+commands (e.g. selecting specific pages per file when bundling).
+
+```bash
+pdf-helper run-recipe <recipe_file.yaml>
+
+# E.g. Run a simple recipe
+pdf-helper run-recipe remove-pages.yaml
+
+# E.g. Run with force overwrite and verbose logging
+pdf-helper run-recipe bundle-workflow.yaml --force --verbose
+```
+
+#### Recipe File Format
+
+A recipe is a YAML file with a `steps` list. Each step has an `id`, an
+`operation`, input/output paths, and operation-specific options. Steps can
+reference each other's outputs using `{ step: step_id }`.
+
+```yaml
+name: "Remove specific pages"
+description: "Removes pages 2, 4, 6 from a PDF."
+version: "1.0"
+
+steps:
+  - id: clean
+    operation: remove_pages
+    input: document.pdf
+    pages_to_remove: [2, 4, 6]
+    output: cleaned.pdf
+```
+
+#### Supported Operations
+
+| Operation | Status | Description |
+|---|---|---|
+| `bundle` | Available | Bundle files with optional per-file page selection |
+| `remove_pages` | Available | Remove pages by 1-based index |
+| `split_pdf` | Available | Split at given page boundaries |
+| `pdf_to_image` | Available | Render pages as PNG images |
+| `extract_text` | Available | Extract text content |
+| `watermark` | Planned | Add text watermark (graceful fallback) |
+| `encrypt` | Planned | Password-protect PDF (graceful fallback) |
+| `metadata` | Planned | Set title/author/keywords (graceful fallback) |
+
+Operations marked *Planned* are not yet implemented — the recipe runner
+logs a warning and copies the input file through, so pipelines don't break.
+
+#### Advanced Example: Multi-step Pipeline
+
+```yaml
+name: "Split, Convert, and Extract Pipeline"
+version: "1.0"
+
+settings:
+  temp_dir: "./.recipe-tmp"
+
+steps:
+  # Step 1: Split the PDF at pages 5 and 10
+  - id: split
+    operation: split_pdf
+    input: report.pdf
+    split_points: [5, 10]
+    output_dir: .
+    output_prefix: "report_part_"
+
+  # Step 2: Convert the second chunk to images
+  - id: to_images
+    operation: pdf_to_image
+    input:
+      step: split
+      file: report_part_2.pdf
+    pages: "1-3"
+    scale: 3
+    output: ./output/images
+
+  # Step 3: Extract text from the first chunk
+  - id: extract
+    operation: extract_text
+    input:
+      step: split
+      file: report_part_1.pdf
+    pages: "1-4"
+    max_characters: 5000
+    reverse_lines: true
+    output: ./output/chapter-1-text.txt
+```
+
+#### Recipe Settings
+
+| Setting | Default | Description |
+|---|---|---|
+| `temp_dir` | `./.recipe-tmp` | Directory for intermediate files |
+| `overwrite` | `false` | Overwrite existing output files |
+| `cleanup_temp` | `false` | Remove temp directory after completion |
+
+Input values (e.g. passwords) can be sourced from environment variables or
+prompted at runtime:
+
+```yaml
+inputs:
+  password:
+    env: PDF_PASSWORD
+    prompt: "Enter output PDF password"
+```
+
+See [`examples/recipes/`](examples/recipes) for more example recipe files.
+
 About
 -----
 

examples/recipes/bundle-with-pages.yaml

@@ -0,0 +1,18 @@
+# yaml-language-server: $schema=../../schemas/recipe-schema.json
+name: "Bundle with Page Selection"
+description: "Bundles specific pages from multiple PDFs together with images into a single PDF. Page selection per file is not available through the CLI."
+version: "1.0"
+
+steps:
+  - id: assemble
+    operation: bundle
+    inputs:
+      - cover.pdf
+      - path: chapter-1.pdf
+        pages: [1, 2, 3]
+      - logo.png
+      - path: chapter-2.pdf
+        pages: "1-5,8,10-12"
+      - path: appendix.pdf
+        pages: [1, 3, 5]
+    output: compiled.pdf

examples/recipes/remove-pages.yaml

@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=../../schemas/recipe-schema.json
+name: "Remove Specific Pages"
+description: "Removes a set of pages (1-based) from a PDF and writes the result."
+version: "1.0"
+
+steps:
+  - id: clean
+    operation: remove_pages
+    input: document.pdf
+    pages_to_remove: [2, 4, 6]
+    output: cleaned.pdf

examples/recipes/secure-report-workflow.yaml

@@ -0,0 +1,64 @@
+# yaml-language-server: $schema=../../schemas/recipe-schema.json
+name: "Secure Report Publishing Workflow"
+description: >
+  A complete publishing pipeline:
+  1. Bundles selected pages from multiple reports
+  2. Adds a CONFIDENTIAL watermark across every page
+  3. Encrypts the output with a password
+  4. Sets author/title metadata
+  Combines existing, planned, and future features into a single orchestrated run.
+version: "1.0"
+
+inputs:
+  password:
+    env: PDF_PASSWORD
+    prompt: "Enter output PDF password"
+
+settings:
+  temp_dir: "./.recipe-tmp"
+
+steps:
+  - id: assemble
+    operation: bundle
+    inputs:
+      - cover-page.pdf
+      - path: executive-summary.pdf
+        pages: "1-3"
+      - path: financial-report.pdf
+        pages: [1, 2, 3, 5, 7, 10, 11, 12]
+    output: "{temp_dir}/assembled.pdf"
+
+  - id: watermark
+    operation: watermark
+    input:
+      step: assemble
+    text: "CONFIDENTIAL"
+    position: center
+    opacity: 0.15
+    rotation: 30.0
+    font_size: 48
+    output: "{temp_dir}/watermarked.pdf"
+
+  - id: encrypt
+    operation: encrypt
+    input:
+      step: watermark
+    password:
+      input: password
+    algorithm: AES-256
+    permissions:
+      printing: false
+      copying: false
+      modifying: false
+    output: "{temp_dir}/encrypted.pdf"
+
+  - id: set_metadata
+    operation: metadata
+    input:
+      step: encrypt
+    title: "Annual Financial Report 2026"
+    author: "Finance Department"
+    subject: "Q4 Financial Summary"
+    keywords: ["finance", "annual", "2026", "confidential"]
+    producer: "PDF-Helper Recipe System v1.0"
+    output: final-report.pdf

examples/recipes/split-convert-extract.yaml

@@ -0,0 +1,34 @@
+# yaml-language-server: $schema=../../schemas/recipe-schema.json
+name: "Split, Convert, and Extract Pipeline"
+description: "Splits a PDF at given points, converts the second chunk to PNG images, and extracts text from the first chunk — all in one recipe run."
+version: "1.0"
+
+settings:
+  temp_dir: "./.recipe-tmp"
+
+steps:
+  - id: split
+    operation: split_pdf
+    input: report.pdf
+    split_points: [5, 10]
+    output_dir: .
+    output_prefix: "report_part_"
+
+  - id: to_images
+    operation: pdf_to_image
+    input:
+      step: split
+      file: report_part_2.pdf
+    pages: "1-3"
+    scale: 3
+    output: ./output/images
+
+  - id: extract
+    operation: extract_text
+    input:
+      step: split
+      file: report_part_1.pdf
+    pages: "1-4"
+    max_characters: 5000
+    reverse_lines: true
+    output: ./output/chapter-1-text.txt

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "PDF-Helper"
-version = "0.2.2"
+version = "0.3.0"
 authors = [
   {name = "CodeWriter21(Mehrad Pooryoussof)", email = "CodeWriter21@gmail.com"}
 ]
@@ -11,7 +11,16 @@ requires-python = ">=3.10"
 dependencies = [
     "log21>=3.3.2",
     "pypdfium2>=4.30.0",
-    "Pillow>=11.0.0"
+    "Pillow>=11.0.0",
+    "pyyaml>=6.0.3",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=9.1.1"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
 ]
 
 [project.scripts]
@@ -46,3 +55,10 @@ line-length = 88
 
 [tool.ruff.lint]
 extend-select = ["C4", "SIM", "TCH", "ANN", "N", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/pdf_helper/*" = ["ANN101"]
+"tests/*" = ["ANN"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]