pdfworkbench 1.0.0__tar.gz

pdfworkbench-1.0.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: pdfworkbench
+Version: 1.0.0
+Summary: A toolbox for common PDF operations with a FastAPI web UI and a CLI.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: pypdf>=4.2
+Requires-Dist: pillow>=10.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pytesseract>=0.3.13
+Requires-Dist: pymupdf>=1.24
+
+# PDFworkbench
+
+A small toolbox for common PDF tasks with **two** interfaces:
+
+1. **Web UI** — a dark-mode FastAPI app (merge, split, rotate, compress, extract text).
+2. **CLI** — e.g. `pdfworkbench -merge --dir <directory_name>` merges every PDF in a folder.
+
+## Requirements
+
+- Python 3.10+
+
+## Install
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install pdfworkbench
+```
+
+For local development from a checkout, use an editable install instead:
+
+```powershell
+pip install -e .
+```
+
+## Run the web UI
+
+```powershell
+pdfworkbench-web
+```
+
+Then open http://127.0.0.1:8098 in your browser. Optional flags:
+
+```powershell
+pdfworkbench-web --host 0.0.0.0 --port 8098 --reload
+```
+
+The UI is also available during development with `python main.py`.
+
+## Command line
+
+The CLI is available through the installed `pdfworkbench` command:
+
+```powershell
+# Merge every PDF in a directory into one file (writes <dir>/merged.pdf)
+pdfworkbench -merge --dir .\invoices
+
+# Same, but recurse into sub-folders and choose the output name
+pdfworkbench -merge --dir .\invoices --recursive --output all.pdf
+
+# Merge specific files in order
+pdfworkbench -merge --input a.pdf b.pdf c.pdf --output combined.pdf
+
+# Split a PDF into one file per page
+pdfworkbench -split --input big.pdf
+
+# Rotate all pages
+pdfworkbench -rotate --input scan.pdf --degrees 90
+
+# Compress a PDF
+pdfworkbench -compress --input scan.pdf
+
+# Extract text from every page into scan.txt
+pdfworkbench -extract --input scan.pdf
+
+# Extract text from scanned pages with OCR
+pdfworkbench -extract --input scan.pdf --ocr
+```
+
+For local development from a checkout, use `python main.py` with the same
+operation flags.
+
+OCR requires the Tesseract executable to be installed and available on your
+PATH. The Python package installs the OCR integration and PDF renderer, but not
+the Tesseract executable itself.
+
+## Project layout
+
+```
+pdftoolbox/
+├── main.py                  # entry point: web UI or CLI dispatch
+├── pyproject.toml           # packaging + `pdfworkbench` console scripts
+└── pdftoolbox/
+    ├── operations.py        # core PDF logic (shared by CLI + web)
+    ├── cli.py               # command line interface
+    └── web/
+        ├── app.py           # FastAPI application
+        ├── templates/index.html
+        └── static/          # style.css, script.js
+```
+
+All processing happens locally — files are never uploaded to a third-party server.

pdfworkbench-1.0.0/README.md

@@ -0,0 +1,92 @@
+# PDFworkbench
+
+A small toolbox for common PDF tasks with **two** interfaces:
+
+1. **Web UI** — a dark-mode FastAPI app (merge, split, rotate, compress, extract text).
+2. **CLI** — e.g. `pdfworkbench -merge --dir <directory_name>` merges every PDF in a folder.
+
+## Requirements
+
+- Python 3.10+
+
+## Install
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install pdfworkbench
+```
+
+For local development from a checkout, use an editable install instead:
+
+```powershell
+pip install -e .
+```
+
+## Run the web UI
+
+```powershell
+pdfworkbench-web
+```
+
+Then open http://127.0.0.1:8098 in your browser. Optional flags:
+
+```powershell
+pdfworkbench-web --host 0.0.0.0 --port 8098 --reload
+```
+
+The UI is also available during development with `python main.py`.
+
+## Command line
+
+The CLI is available through the installed `pdfworkbench` command:
+
+```powershell
+# Merge every PDF in a directory into one file (writes <dir>/merged.pdf)
+pdfworkbench -merge --dir .\invoices
+
+# Same, but recurse into sub-folders and choose the output name
+pdfworkbench -merge --dir .\invoices --recursive --output all.pdf
+
+# Merge specific files in order
+pdfworkbench -merge --input a.pdf b.pdf c.pdf --output combined.pdf
+
+# Split a PDF into one file per page
+pdfworkbench -split --input big.pdf
+
+# Rotate all pages
+pdfworkbench -rotate --input scan.pdf --degrees 90
+
+# Compress a PDF
+pdfworkbench -compress --input scan.pdf
+
+# Extract text from every page into scan.txt
+pdfworkbench -extract --input scan.pdf
+
+# Extract text from scanned pages with OCR
+pdfworkbench -extract --input scan.pdf --ocr
+```
+
+For local development from a checkout, use `python main.py` with the same
+operation flags.
+
+OCR requires the Tesseract executable to be installed and available on your
+PATH. The Python package installs the OCR integration and PDF renderer, but not
+the Tesseract executable itself.
+
+## Project layout
+
+```
+pdftoolbox/
+├── main.py                  # entry point: web UI or CLI dispatch
+├── pyproject.toml           # packaging + `pdfworkbench` console scripts
+└── pdftoolbox/
+    ├── operations.py        # core PDF logic (shared by CLI + web)
+    ├── cli.py               # command line interface
+    └── web/
+        ├── app.py           # FastAPI application
+        ├── templates/index.html
+        └── static/          # style.css, script.js
+```
+
+All processing happens locally — files are never uploaded to a third-party server.

pdfworkbench-1.0.0/pdftoolbox/__init__.py

@@ -0,0 +1,3 @@
+"""PDFworkbench - a toolbox for common PDF operations."""
+
+__version__ = "1.0.0"

pdfworkbench-1.0.0/pdftoolbox/cli.py

@@ -0,0 +1,137 @@
+"""Command line interface for PDFworkbench.
+
+Examples
+--------
+    pdfworkbench -merge --dir ./invoices
+    pdfworkbench -merge --dir ./invoices --output all.pdf --recursive
+    pdfworkbench -split --input big.pdf
+    pdfworkbench -rotate --input scan.pdf --degrees 90
+    pdfworkbench -compress --input scan.pdf
+    pdfworkbench -extract --input report.pdf
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from . import __version__, operations
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pdfworkbench",
+        description="A toolbox for common PDF operations.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"PDFworkbench {__version__}"
+    )
+
+    action = parser.add_mutually_exclusive_group(required=True)
+    action.add_argument("-merge", action="store_true", help="Merge PDFs into one file.")
+    action.add_argument("-split", action="store_true", help="Split a PDF into pages.")
+    action.add_argument("-rotate", action="store_true", help="Rotate all pages.")
+    action.add_argument("-compress", action="store_true", help="Compress a PDF.")
+    action.add_argument(
+        "-extract", action="store_true", help="Extract text from a PDF."
+    )
+
+    parser.add_argument("--dir", "-d", help="Directory containing PDF files (merge).")
+    parser.add_argument("--input", "-i", nargs="+", help="One or more input PDF files.")
+    parser.add_argument("--output", "-o", help="Output file (or directory for split).")
+    parser.add_argument(
+        "--recursive",
+        "-r",
+        action="store_true",
+        help="Recurse into sub-directories when merging a directory.",
+    )
+    parser.add_argument(
+        "--degrees", type=int, default=90, help="Rotation in degrees (default: 90)."
+    )
+    parser.add_argument(
+        "--quality",
+        type=int,
+        default=60,
+        help="Image quality 1-100 for -compress (default: 60).",
+    )
+    parser.add_argument(
+        "--scale",
+        type=float,
+        default=1.0,
+        help="Image scale 0-1 for -compress, e.g. 0.5 halves resolution (default: 1.0).",
+    )
+    parser.add_argument(
+        "--no-stream-compression",
+        dest="compress_streams",
+        action="store_false",
+        help="Skip content-stream deflation during -compress.",
+    )
+    parser.add_argument(
+        "--ocr",
+        action="store_true",
+        help="Use OCR with Tesseract during -extract (requires Tesseract).",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.merge:
+            if args.dir:
+                out = operations.merge_directory(
+                    args.dir, args.output, recursive=args.recursive
+                )
+            elif args.input:
+                if not args.output:
+                    parser.error("--output is required when merging with --input.")
+                out = operations.merge_pdfs(args.input, args.output)
+            else:
+                parser.error("-merge requires --dir or --input.")
+            print(f"Merged PDF written to: {out}")
+
+        elif args.split:
+            _require_single_input(parser, args)
+            created = operations.split_pdf(args.input[0], args.output)
+            print(f"Split into {len(created)} pages in: {created[0].parent}")
+
+        elif args.rotate:
+            _require_single_input(parser, args)
+            out = operations.rotate_pdf(args.input[0], args.degrees, args.output)
+            print(f"Rotated PDF written to: {out}")
+
+        elif args.compress:
+            _require_single_input(parser, args)
+            out = operations.compress_pdf(
+                args.input[0],
+                args.output,
+                image_quality=args.quality,
+                image_scale=args.scale,
+                compress_streams=args.compress_streams,
+            )
+            print(f"Compressed PDF written to: {out}")
+
+        elif args.extract:
+            _require_single_input(parser, args)
+            out = operations.extract_text(args.input[0], args.output, ocr=args.ocr)
+            print(f"Extracted text written to: {out}")
+
+    except (FileNotFoundError, NotADirectoryError, RuntimeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+def _require_single_input(
+    parser: argparse.ArgumentParser, args: argparse.Namespace
+) -> None:
+    if not args.input:
+        parser.error("This action requires --input <file.pdf>.")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdfworkbench-1.0.0/pdftoolbox/operations.py

@@ -0,0 +1,213 @@
+"""Core PDF operations used by both the CLI and the web UI."""
+
+from __future__ import annotations
+
+import io
+import os
+from pathlib import Path
+from typing import Iterable
+
+from pypdf import PdfReader, PdfWriter
+
+
+def _natural_sorted(paths: Iterable[Path]) -> list[Path]:
+    """Sort paths in a human-friendly order (file2 before file10)."""
+    import re
+
+    def key(p: Path):
+        return [
+            int(chunk) if chunk.isdigit() else chunk.lower()
+            for chunk in re.split(r"(\d+)", p.name)
+        ]
+
+    return sorted(paths, key=key)
+
+
+def find_pdfs(directory: str | os.PathLike[str], recursive: bool = False) -> list[Path]:
+    """Return a naturally sorted list of PDF files in *directory*."""
+    root = Path(directory)
+    if not root.is_dir():
+        raise NotADirectoryError(f"Not a directory: {root}")
+
+    pattern = "**/*.pdf" if recursive else "*.pdf"
+    pdfs = [p for p in root.glob(pattern) if p.is_file()]
+    return _natural_sorted(pdfs)
+
+
+def merge_pdfs(
+    inputs: Iterable[str | os.PathLike[str]],
+    output: str | os.PathLike[str],
+) -> Path:
+    """Merge *inputs* (in the given order) into a single PDF at *output*."""
+    inputs = [Path(p) for p in inputs]
+    if not inputs:
+        raise ValueError("No PDF files supplied to merge.")
+
+    writer = PdfWriter()
+    for pdf in inputs:
+        reader = PdfReader(str(pdf))
+        for page in reader.pages:
+            writer.add_page(page)
+
+    output = Path(output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    with output.open("wb") as fh:
+        writer.write(fh)
+    return output
+
+
+def merge_directory(
+    directory: str | os.PathLike[str],
+    output: str | os.PathLike[str] | None = None,
+    recursive: bool = False,
+) -> Path:
+    """Merge every PDF found in *directory* into one file."""
+    pdfs = find_pdfs(directory, recursive=recursive)
+    if not pdfs:
+        raise FileNotFoundError(f"No PDF files found in: {directory}")
+
+    if output is None:
+        output = Path(directory) / "merged.pdf"
+    return merge_pdfs(pdfs, output)
+
+
+def split_pdf(
+    input_pdf: str | os.PathLike[str],
+    output_dir: str | os.PathLike[str] | None = None,
+) -> list[Path]:
+    """Split *input_pdf* into one file per page. Returns the created files."""
+    src = Path(input_pdf)
+    reader = PdfReader(str(src))
+
+    out_dir = Path(output_dir) if output_dir else src.parent / f"{src.stem}_pages"
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    created: list[Path] = []
+    width = len(str(len(reader.pages)))
+    for index, page in enumerate(reader.pages, start=1):
+        writer = PdfWriter()
+        writer.add_page(page)
+        target = out_dir / f"{src.stem}_{index:0{width}d}.pdf"
+        with target.open("wb") as fh:
+            writer.write(fh)
+        created.append(target)
+    return created
+
+
+def rotate_pdf(
+    input_pdf: str | os.PathLike[str],
+    degrees: int,
+    output: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Rotate every page of *input_pdf* by *degrees* (multiple of 90)."""
+    if degrees % 90 != 0:
+        raise ValueError("Rotation must be a multiple of 90 degrees.")
+
+    src = Path(input_pdf)
+    reader = PdfReader(str(src))
+    writer = PdfWriter()
+    for page in reader.pages:
+        page.rotate(degrees)
+        writer.add_page(page)
+
+    out = Path(output) if output else src.with_name(f"{src.stem}_rotated.pdf")
+    with out.open("wb") as fh:
+        writer.write(fh)
+    return out
+
+
+def compress_pdf(
+    input_pdf: str | os.PathLike[str],
+    output: str | os.PathLike[str] | None = None,
+    *,
+    image_quality: int = 60,
+    image_scale: float = 1.0,
+    compress_streams: bool = True,
+) -> Path:
+    """Compress *input_pdf* by re-encoding images and deflating streams.
+
+    ``image_quality`` is the JPEG quality (1-100) used when re-encoding images;
+    lower means smaller files. ``image_scale`` (0-1) optionally downsamples image
+    dimensions. Set ``compress_streams`` to also deflate page content streams.
+    """
+    if not 1 <= image_quality <= 100:
+        raise ValueError("image_quality must be between 1 and 100.")
+    if not 0 < image_scale <= 1:
+        raise ValueError("image_scale must be between 0 (exclusive) and 1.")
+
+    src = Path(input_pdf)
+    reader = PdfReader(str(src))
+    writer = PdfWriter()
+    writer.append(reader)
+
+    for page in writer.pages:
+        for img in page.images:
+            pil_image = img.image
+            if pil_image is None:
+                continue
+            if image_scale < 1.0:
+                new_size = (
+                    max(1, int(pil_image.width * image_scale)),
+                    max(1, int(pil_image.height * image_scale)),
+                )
+                pil_image = pil_image.resize(new_size)
+            img.replace(pil_image, quality=image_quality)
+        if compress_streams:
+            try:
+                page.compress_content_streams()
+            except Exception:  # noqa: BLE001 - some streams can't be re-deflated
+                pass
+
+    try:
+        writer.compress_identical_objects(remove_identicals=True, remove_orphans=True)
+    except Exception:  # noqa: BLE001 - best-effort de-duplication
+        pass
+
+    out = Path(output) if output else src.with_name(f"{src.stem}_compressed.pdf")
+    with out.open("wb") as fh:
+        writer.write(fh)
+    return out
+
+
+def extract_text(
+    input_pdf: str | os.PathLike[str],
+    output: str | os.PathLike[str] | None = None,
+    *,
+    ocr: bool = False,
+) -> Path:
+    """Extract text from every page into a UTF-8 text file.
+
+    When ``ocr`` is true, render each page and use Tesseract instead of relying
+    on selectable PDF text. Tesseract must be installed separately.
+    """
+    src = Path(input_pdf)
+    text = extract_text_content(src.read_bytes(), ocr=ocr)
+
+    out = Path(output) if output else src.with_suffix(".txt")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(text + ("\n" if text else ""), encoding="utf-8")
+    return out
+
+
+def extract_text_content(pdf_data: bytes, *, ocr: bool = False) -> str:
+    """Return extracted text for PDF bytes, optionally using OCR."""
+    reader = PdfReader(io.BytesIO(pdf_data))
+    if not ocr:
+        pages = [(page.extract_text() or "").rstrip() for page in reader.pages]
+    else:
+        import pymupdf
+        import pytesseract
+        from PIL import Image
+
+        document = pymupdf.open(stream=pdf_data, filetype="pdf")
+        try:
+            pages = []
+            for page in document:
+                pixmap = page.get_pixmap(matrix=pymupdf.Matrix(2, 2), alpha=False)
+                image = Image.frombytes(
+                    "RGB", (pixmap.width, pixmap.height), pixmap.samples
+                )
+                pages.append(pytesseract.image_to_string(image).rstrip())
+        finally:
+            document.close()
+    return "\n\n".join(pages)

pdfworkbench-1.0.0/pdftoolbox/web/__init__.py

@@ -0,0 +1,5 @@
+"""Web UI package for PDFworkbench."""
+
+from .app import app
+
+__all__ = ["app"]