pdfworkbench 1.0.0__py3-none-any.whl

pdftoolbox/__init__.py

@@ -0,0 +1,3 @@
+"""PDFworkbench - a toolbox for common PDF operations."""
+
+__version__ = "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())

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)

pdftoolbox/web/__init__.py

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

pdftoolbox/web/app.py

@@ -0,0 +1,203 @@
+"""FastAPI web UI for PDFworkbench (dark mode)."""
+
+from __future__ import annotations
+
+import io
+import argparse
+from pathlib import Path
+
+from fastapi import FastAPI, File, Form, HTTPException, Request, UploadFile
+from fastapi.responses import HTMLResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from pypdf import PdfReader, PdfWriter
+
+from .. import __version__, operations
+
+BASE_DIR = Path(__file__).resolve().parent
+
+app = FastAPI(title="PDFworkbench", version=__version__)
+app.mount("/static", StaticFiles(directory=BASE_DIR / "static"), name="static")
+templates = Jinja2Templates(directory=str(BASE_DIR / "templates"))
+
+
+def serve(argv: list[str] | None = None) -> int:
+    """Start the web UI from the installed ``pdfworkbench-web`` command."""
+    import uvicorn
+
+    parser = argparse.ArgumentParser(description="Start the PDFworkbench web UI.")
+    parser.add_argument("--host", default="127.0.0.1", help="Bind host.")
+    parser.add_argument("--port", type=int, default=8098, help="Bind port.")
+    parser.add_argument(
+        "--reload", action="store_true", help="Enable auto-reload (development)."
+    )
+    args = parser.parse_args(argv)
+    url = f"http://{args.host}:{args.port}"
+    print(f"PDFworkbench web UI running at {url}  (press Ctrl+C to stop)")
+    uvicorn.run(
+        "pdftoolbox.web:app",
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+    )
+    return 0
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index(request: Request) -> HTMLResponse:
+    return templates.TemplateResponse(request, "index.html", {"version": __version__})
+
+
+def _read_upload(upload: UploadFile) -> PdfReader:
+    if not (upload.filename or "").lower().endswith(".pdf"):
+        raise HTTPException(400, f"Not a PDF file: {upload.filename}")
+    data = upload.file.read()
+    if not data:
+        raise HTTPException(400, f"Empty file: {upload.filename}")
+    try:
+        return PdfReader(io.BytesIO(data))
+    except Exception as exc:  # noqa: BLE001 - surface a clean error to the client
+        raise HTTPException(400, f"Could not read {upload.filename}: {exc}") from exc
+
+
+@app.post("/api/merge")
+async def api_merge(files: list[UploadFile] = File(...)):
+    if len(files) < 2:
+        raise HTTPException(400, "Please upload at least two PDF files to merge.")
+
+    writer = PdfWriter()
+    for upload in files:
+        reader = _read_upload(upload)
+        for page in reader.pages:
+            writer.add_page(page)
+
+    buffer = io.BytesIO()
+    writer.write(buffer)
+    buffer.seek(0)
+    return StreamingResponse(
+        buffer,
+        media_type="application/pdf",
+        headers={"Content-Disposition": "attachment; filename=merged.pdf"},
+    )
+
+
+@app.post("/api/split")
+async def api_split(file: UploadFile = File(...)):
+    import zipfile
+
+    reader = _read_upload(file)
+    stem = Path(file.filename or "document").stem
+
+    zip_buffer = io.BytesIO()
+    with zipfile.ZipFile(zip_buffer, "w", zipfile.ZIP_DEFLATED) as zf:
+        width = len(str(len(reader.pages)))
+        for index, page in enumerate(reader.pages, start=1):
+            writer = PdfWriter()
+            writer.add_page(page)
+            page_buffer = io.BytesIO()
+            writer.write(page_buffer)
+            zf.writestr(f"{stem}_{index:0{width}d}.pdf", page_buffer.getvalue())
+
+    zip_buffer.seek(0)
+    return StreamingResponse(
+        zip_buffer,
+        media_type="application/zip",
+        headers={"Content-Disposition": f"attachment; filename={stem}_pages.zip"},
+    )
+
+
+@app.post("/api/rotate")
+async def api_rotate(file: UploadFile = File(...), degrees: int = Form(90)):
+    if degrees % 90 != 0:
+        raise HTTPException(400, "Rotation must be a multiple of 90 degrees.")
+
+    reader = _read_upload(file)
+    writer = PdfWriter()
+    for page in reader.pages:
+        page.rotate(degrees)
+        writer.add_page(page)
+
+    buffer = io.BytesIO()
+    writer.write(buffer)
+    buffer.seek(0)
+    stem = Path(file.filename or "document").stem
+    return StreamingResponse(
+        buffer,
+        media_type="application/pdf",
+        headers={"Content-Disposition": f"attachment; filename={stem}_rotated.pdf"},
+    )
+
+
+@app.post("/api/compress")
+async def api_compress(
+    file: UploadFile = File(...),
+    image_quality: int = Form(60),
+    image_scale: float = Form(1.0),
+    compress_streams: bool = Form(True),
+):
+    if not 1 <= image_quality <= 100:
+        raise HTTPException(400, "Image quality must be between 1 and 100.")
+    if not 0 < image_scale <= 1:
+        raise HTTPException(400, "Image scale must be between 0 and 1.")
+
+    reader = _read_upload(file)
+    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
+
+    buffer = io.BytesIO()
+    writer.write(buffer)
+    buffer.seek(0)
+    stem = Path(file.filename or "document").stem
+    return StreamingResponse(
+        buffer,
+        media_type="application/pdf",
+        headers={"Content-Disposition": f"attachment; filename={stem}_compressed.pdf"},
+    )
+
+
+@app.post("/api/extract")
+async def api_extract(
+    file: UploadFile = File(...),
+    ocr: bool = Form(False),
+):
+    if not (file.filename or "").lower().endswith(".pdf"):
+        raise HTTPException(400, f"Not a PDF file: {file.filename}")
+    data = await file.read()
+    if not data:
+        raise HTTPException(400, f"Empty file: {file.filename}")
+    try:
+        text = operations.extract_text_content(data, ocr=ocr)
+    except Exception as exc:  # noqa: BLE001 - surface a clean error to the client
+        raise HTTPException(
+            400, f"Could not extract text from {file.filename}: {exc}"
+        ) from exc
+    buffer = io.BytesIO((text + ("\n" if text else "")).encode("utf-8"))
+    stem = Path(file.filename or "document").stem
+    return StreamingResponse(
+        buffer,
+        media_type="text/plain; charset=utf-8",
+        headers={"Content-Disposition": f"attachment; filename={stem}.txt"},
+    )