pdfslice-py 1.0.0__py3-none-any.whl

pdfslice_py/__init__.py

@@ -0,0 +1,6 @@
+"""pdfslice-py: split PDFs into page images, then gather or check them back.
+
+Python port of https://github.com/DuckyMomo20012/pdfslice (TypeScript).
+"""
+
+__version__ = "1.0.0"

pdfslice_py/cli.py

@@ -0,0 +1,130 @@
+"""CLI. Port of src/app.ts + src/commands/{split,gather,check}/{command,impl}.ts."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .filename_template import DEFAULT_TEMPLATE
+from .gather import gather_all
+from .logger import create_logger
+from .split import split_all
+
+
+def _log_flags(f: click.decorators.FC) -> click.decorators.FC:
+    f = click.option("--verbose", is_flag=True, default=False, help="Enable debug logging")(f)
+    f = click.option("--quiet", is_flag=True, default=False, help="Only log errors")(f)
+    f = click.option("--log-file", default=None, help="Path to also write logs as JSON")(f)
+    return f
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="pdfslice")
+def cli() -> None:
+    """Split PDFs into page images, then gather or check them back."""
+
+
+@cli.command("split")
+@click.argument("input", type=str)
+@click.option(
+    "-l",
+    "--level",
+    type=int,
+    default=1,
+    help="How many directory levels deep to search for PDFs",
+)
+@click.option(
+    "-f",
+    "--flatten",
+    is_flag=True,
+    default=False,
+    help="Pull every discovered PDF's output folder to the input root, "
+    "instead of alongside each PDF",
+)
+@click.option(
+    "--template",
+    type=str,
+    default=DEFAULT_TEMPLATE,
+    help="Page image filename template. Placeholders: {{filename}}, "
+    "{{page_number}}. Must contain exactly one {{page_number}}.",
+)
+@click.option(
+    "--dry-run", is_flag=True, default=False, help="Preview actions without writing any files"
+)
+@_log_flags
+def split_cmd(
+    input: str,  # noqa: A002 - mirrors Click argument name and TS API
+    level: int,
+    flatten: bool,
+    template: str,
+    dry_run: bool,
+    verbose: bool,
+    quiet: bool,
+    log_file: str | None,
+) -> None:
+    """Split PDF(s) into per-page JPG images alongside the source file."""
+    logger = create_logger(verbose=verbose, quiet=quiet, log_file=log_file)
+    results = split_all(
+        input,
+        logger,
+        level=level,
+        flatten=flatten,
+        template=template,
+        dry_run=dry_run,
+    )
+    logger.info(f"Done. Processed {len(results)} PDF(s).")
+
+
+@cli.command("gather")
+@click.argument("input", type=str)
+@click.option(
+    "--dry-run", is_flag=True, default=False, help="Preview actions without writing any files"
+)
+@click.option(
+    "--backup/--no-backup",
+    default=True,
+    help="Back up the existing PDF before overwriting it",
+)
+@_log_flags
+def gather_cmd(
+    input: str,  # noqa: A002 - mirrors Click argument name and TS API
+    dry_run: bool,
+    backup: bool,
+    verbose: bool,
+    quiet: bool,
+    log_file: str | None,
+) -> None:
+    """Gather page images back into a PDF, reporting any missing pages."""
+    logger = create_logger(verbose=verbose, quiet=quiet, log_file=log_file)
+    reports = gather_all(input, logger, dry_run=dry_run, check_only=False, backup=backup)
+
+    with_missing = [r for r in reports if r.missing_pages]
+    if with_missing:
+        logger.warn(f"{len(with_missing)} unit(s) have missing pages")
+    logger.info(f"Done. Processed {len(reports)} unit folder(s).")
+
+
+@cli.command("check")
+@click.argument("input", type=str)
+@_log_flags
+def check_cmd(
+    input: str,  # noqa: A002 - mirrors Click argument name and TS API
+    verbose: bool,
+    quiet: bool,
+    log_file: str | None,
+) -> None:
+    """Report missing page images without writing any PDF (read-only)."""
+    logger = create_logger(verbose=verbose, quiet=quiet, log_file=log_file)
+    reports = gather_all(input, logger, check_only=True)
+
+    with_missing = [r for r in reports if r.missing_pages]
+    if with_missing:
+        logger.warn(f"{len(with_missing)} unit(s) have missing pages")
+        sys.exit(1)
+    else:
+        logger.info(f"All {len(reports)} unit(s) complete.")
+
+
+if __name__ == "__main__":
+    cli()

pdfslice_py/discover.py

@@ -0,0 +1,67 @@
+"""PDF/image discovery on the filesystem. Direct port of lib/discover.ts."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .filename_template import DEFAULT_TEMPLATE, compile_template
+
+_IMAGE_SUFFIXES = {".jpg", ".jpeg"}
+
+
+def find_pdfs(root: str | Path, level: int = 1) -> list[str]:
+    """Find all PDF files under `root`, descending up to `level` directories
+    deep. level=1 (default): PDFs directly in `root` only. level=2: `root`
+    and one subfolder deep. Etc. If `root` itself is a PDF file, returns
+    just that file."""
+    root = Path(root)
+    if root.is_file():
+        return [str(root)] if root.suffix.lower() == ".pdf" else []
+
+    results: list[str] = []
+
+    def walk(directory: Path, depth: int) -> None:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                full = Path(entry.path)
+                if entry.is_file() and full.suffix.lower() == ".pdf":
+                    results.append(str(full))
+                elif entry.is_dir() and depth < level:
+                    walk(full, depth + 1)
+
+    walk(root, 1)
+    return results
+
+
+def find_images_deep(root: str | Path) -> list[str]:
+    """Recursively find all image files (jpg/jpeg) under `root`, any depth.
+    Used by gather/check, since split output can be nested by flatten mode."""
+    root = Path(root)
+    results: list[str] = []
+
+    def walk(directory: Path) -> None:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                full = Path(entry.path)
+                if entry.is_file() and full.suffix.lower() in _IMAGE_SUFFIXES:
+                    results.append(str(full))
+                elif entry.is_dir():
+                    walk(full)
+
+    walk(root)
+    return results
+
+
+def page_image_name(base_name: str, page: int, template: str = DEFAULT_TEMPLATE) -> str:
+    """Build the page-image filename using a template (default:
+    "{{filename}}.{{page_number}}.jpg"). Page number is zero-padded to 3
+    digits; if the number itself is wider than 3 digits, no padding is
+    applied (natural width is used)."""
+    return compile_template(template).render(base_name, page)
+
+
+def parse_page_from_image_name(file_name: str, template: str = DEFAULT_TEMPLATE) -> int | None:
+    """Parse a page number back out of a name produced by page_image_name,
+    using the same template it was generated with."""
+    return compile_template(template).parse_page(file_name)

pdfslice_py/filename_template.py

@@ -0,0 +1,55 @@
+"""Page-image filename templating. Direct port of lib/filename-template.ts."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+DEFAULT_TEMPLATE = "{{filename}}.{{page_number}}.jpg"
+
+_PLACEHOLDER_PATTERN = re.compile(r"(\{\{filename\}\}|\{\{page_number\}\})")
+
+
+def _pad_page_number(page: int) -> str:
+    return str(page).zfill(3) if page < 1000 else str(page)
+
+
+@dataclass(frozen=True)
+class FilenameTemplate:
+    render: Callable[[str, int], str]
+    parse_page: Callable[[str], int | None]
+
+
+def compile_template(template: str) -> FilenameTemplate:
+    page_count = template.count("{{page_number}}")
+    if page_count != 1:
+        raise ValueError(
+            f"Template must contain exactly one {{{{page_number}}}} placeholder, "
+            f'found {page_count} in "{template}"'
+        )
+
+    parts = _PLACEHOLDER_PATTERN.split(template)
+    regex_source = ""
+    for i, part in enumerate(parts):
+        if i % 2 == 0:
+            regex_source += re.escape(part)
+        elif part == "{{page_number}}":
+            regex_source += r"(\d+)"
+        elif part == "{{filename}}":
+            regex_source += ".+?"
+
+    regex = re.compile(f"^{regex_source}$", re.IGNORECASE)
+
+    def render(base_name: str, page: int) -> str:
+        return template.replace("{{filename}}", base_name).replace(
+            "{{page_number}}", _pad_page_number(page)
+        )
+
+    def parse_page(file_name: str) -> int | None:
+        m = regex.match(file_name)
+        if not m:
+            return None
+        return int(m.group(1))
+
+    return FilenameTemplate(render=render, parse_page=parse_page)

pdfslice_py/gather.py

@@ -0,0 +1,254 @@
+"""Rebuild a PDF from split page images, or just check for missing pages.
+Direct port of lib/gather.ts.
+
+pdf-lib's `PDFDocument.create()` + `embedJpg`/`addPage`/`drawImage` at
+image-pixel dimensions (TS) is equivalent here to Pillow saving a multi-page
+PDF from the JPEGs directly with `resolution=72.0`, since both put one
+image pixel per PDF point (i.e. treat the image as if it were 72 DPI),
+regardless of the image's own DPI metadata.
+"""
+
+from __future__ import annotations
+
+import shutil
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from PIL import Image
+from pypdf import PdfReader
+
+from .discover import find_images_deep, parse_page_from_image_name
+from .filename_template import DEFAULT_TEMPLATE
+from .hash import hash_file
+from .logger import Logger
+from .manifest import Manifest, ManifestImageEntry, manifest_path_for, read_manifest, write_manifest
+
+_PDF_PAGE_RESOLUTION = 72.0  # 1 image pixel == 1 PDF point
+
+Action = Literal["created", "skipped-unchanged", "would-create", "missing-source", "check-only"]
+
+
+@dataclass
+class UnitReport:
+    folder: str
+    source_pdf: str | None
+    page_count: int | None
+    found_images: int
+    missing_pages: list[int]
+    action: Action
+    output_pdf: str | None = None
+
+
+@dataclass
+class GatherOptions:
+    input: str
+    dry_run: bool = False
+    check_only: bool = False
+    backup: bool = True
+    logger: Logger = field(default=None)  # type: ignore[assignment]
+
+
+def _find_unit_folders(root: str | Path) -> list[str]:
+    """Discover "unit" folders: a folder produced by `split` — recognized by
+    the `.pdfslice-manifest.json` written by split (not by the mere presence
+    of a PDF, since the source folder the PDF was found in also still
+    contains a PDF that split never deletes)."""
+    root = Path(root)
+    if not root.is_dir():
+        return []
+
+    units: list[str] = []
+
+    def walk(directory: Path) -> None:
+        if manifest_path_for(directory).exists():
+            units.append(str(directory))
+            return  # don't descend further into a recognized unit
+        for entry in sorted(directory.iterdir()):
+            if entry.is_dir():
+                walk(entry)
+
+    walk(root)
+    return units
+
+
+def gather_all(
+    input: str | Path,  # noqa: A002 - mirrors TS `input` option name
+    logger: Logger,
+    dry_run: bool = False,
+    check_only: bool = False,
+    backup: bool = True,
+) -> list[UnitReport]:
+    units = _find_unit_folders(input)
+    logger.info(f"Found {len(units)} unit folder(s) under {input}")
+
+    reports: list[UnitReport] = []
+    for folder in units:
+        reports.append(
+            _gather_one(
+                folder, logger=logger, dry_run=dry_run, check_only=check_only, backup=backup
+            )
+        )
+    return reports
+
+
+def _gather_one(
+    folder: str,
+    *,
+    logger: Logger,
+    dry_run: bool = False,
+    check_only: bool = False,
+    backup: bool = True,
+) -> UnitReport:
+    manifest = read_manifest(folder)
+    if manifest is None:
+        logger.warn("No manifest found in unit folder", folder=folder)
+        return UnitReport(
+            folder=folder,
+            source_pdf=None,
+            page_count=None,
+            found_images=0,
+            missing_pages=[],
+            action="missing-source",
+        )
+
+    source_pdf_path = Path(folder) / manifest.sourcePdf
+    if not source_pdf_path.exists():
+        logger.warn(
+            "Source PDF recorded in manifest is missing",
+            folder=folder,
+            expected=manifest.sourcePdf,
+        )
+        return UnitReport(
+            folder=folder,
+            source_pdf=None,
+            page_count=None,
+            found_images=0,
+            missing_pages=[],
+            action="missing-source",
+        )
+
+    page_count = len(PdfReader(str(source_pdf_path)).pages)
+    template = manifest.filenameTemplate or DEFAULT_TEMPLATE
+
+    image_paths = find_images_deep(folder)
+    found_pages: set[int] = set()
+    for img_path in image_paths:
+        page = parse_page_from_image_name(Path(img_path).name, template)
+        if page is not None:
+            found_pages.add(page)
+
+    missing_pages = [p for p in range(1, page_count + 1) if p not in found_pages]
+
+    if missing_pages:
+        logger.warn(
+            "Missing page image(s)",
+            folder=folder,
+            missing_pages=missing_pages,
+            expected=page_count,
+            found=len(found_pages),
+        )
+    else:
+        logger.info(f"All {page_count} page image(s) present", folder=folder)
+
+    if check_only:
+        return UnitReport(
+            folder=folder,
+            source_pdf=str(source_pdf_path),
+            page_count=page_count,
+            found_images=len(found_pages),
+            missing_pages=missing_pages,
+            action="check-only",
+        )
+
+    # Decide whether to (re)build the combined PDF, comparing the manifest's
+    # recorded image hashes against the current on-disk images.
+    ordered = sorted(
+        (p for p in image_paths if parse_page_from_image_name(Path(p).name, template) is not None),
+        key=lambda p: parse_page_from_image_name(Path(p).name, template),  # type: ignore[arg-type]
+    )
+    current_entries = [
+        ManifestImageEntry(
+            file=Path(p).name,
+            page=parse_page_from_image_name(Path(p).name, template),  # type: ignore[arg-type]
+            hash=hash_file(p),
+        )
+        for p in ordered
+    ]
+
+    # Output overwrites the source PDF in place, per spec.
+    output_pdf_path = source_pdf_path
+
+    unchanged = (
+        bool(manifest.gatheredAt)
+        and manifest.pageCount == page_count
+        and len(manifest.images) == len(current_entries)
+        and all(a.hash == b.hash for a, b in zip(manifest.images, current_entries, strict=True))
+    )
+
+    if unchanged and not missing_pages:
+        logger.info("No changes detected, skipping PDF creation", folder=folder)
+        return UnitReport(
+            folder=folder,
+            source_pdf=str(source_pdf_path),
+            page_count=page_count,
+            found_images=len(found_pages),
+            missing_pages=missing_pages,
+            output_pdf=str(output_pdf_path),
+            action="skipped-unchanged",
+        )
+
+    if dry_run:
+        logger.info(f"[dry-run] would overwrite {output_pdf_path}")
+        return UnitReport(
+            folder=folder,
+            source_pdf=str(source_pdf_path),
+            page_count=page_count,
+            found_images=len(found_pages),
+            missing_pages=missing_pages,
+            output_pdf=str(output_pdf_path),
+            action="would-create",
+        )
+
+    # Back up the existing PDF before overwriting it (default on; --no-backup to skip).
+    if backup:
+        backup_path = Path(folder) / f"{output_pdf_path.stem}.bak-{int(time.time() * 1000)}.pdf"
+        shutil.copyfile(output_pdf_path, backup_path)
+        logger.info("Backed up previous PDF", backup_path=str(backup_path))
+
+    images = [Image.open(p).convert("RGB") for p in ordered]
+    first, rest = images[0], images[1:]
+    first.save(
+        output_pdf_path, "PDF", save_all=True, append_images=rest, resolution=_PDF_PAGE_RESOLUTION
+    )
+    for im in images:
+        im.close()
+
+    from datetime import datetime, timezone
+
+    now = datetime.now(timezone.utc).isoformat()
+    write_manifest(
+        folder,
+        Manifest(
+            version=1,
+            sourcePdf=manifest.sourcePdf,
+            sourcePdfHash=hash_file(output_pdf_path),
+            pageCount=page_count,
+            images=current_entries,
+            updatedAt=now,
+            gatheredAt=now,
+            filenameTemplate=template,
+        ),
+    )
+
+    logger.info("PDF overwritten", output_pdf=str(output_pdf_path))
+    return UnitReport(
+        folder=folder,
+        source_pdf=str(source_pdf_path),
+        page_count=page_count,
+        found_images=len(found_pages),
+        missing_pages=missing_pages,
+        output_pdf=str(output_pdf_path),
+        action="created",
+    )

pdfslice_py/hash.py

@@ -0,0 +1,17 @@
+"""File hashing. Direct port of lib/hash.ts."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+_CHUNK_SIZE = 1024 * 1024
+
+
+def hash_file(path: str | Path) -> str:
+    """SHA-256 hash of a file's contents, streamed (safe for large PDFs/images)."""
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(_CHUNK_SIZE), b""):
+            h.update(chunk)
+    return h.hexdigest()

pdfslice_py/logger.py

@@ -0,0 +1,77 @@
+"""Logging. Port of lib/logger.ts (winston) onto Python's stdlib logging.
+
+Call sites use `logger.info("message", key=value, ...)` the way the
+TypeScript original used `logger.info('message', { key: value })` — extra
+keyword arguments are the "meta" object, printed as JSON after the message
+and, if `log_file` is set, also written as a JSON line per record.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_COLOR_BY_LEVEL = {
+    "debug": "\033[34m",  # blue
+    "info": "\033[32m",  # green
+    "warn": "\033[33m",  # yellow
+    "error": "\033[31m",  # red
+}
+_RESET = "\033[0m"
+
+
+class Logger:
+    def __init__(self, level: str, log_file: str | Path | None = None) -> None:
+        self._level = level
+        self._log_file = Path(log_file) if log_file is not None else None
+        self._order = {"debug": 0, "info": 1, "warn": 2, "error": 3}
+
+    def _enabled(self, level: str) -> bool:
+        return self._order[level] >= self._order[self._level]
+
+    def _emit(self, level: str, message: str, meta: dict[str, Any]) -> None:
+        if not self._enabled(level):
+            return
+
+        color = _COLOR_BY_LEVEL.get(level, "")
+        extra = f" {json.dumps(meta)}" if meta else ""
+        stream = sys.stderr if level == "error" else sys.stdout
+        print(f"{color}{level}{_RESET}: {message}{extra}", file=stream)
+
+        if self._log_file is not None:
+            record = {
+                "level": level,
+                "message": message,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                **meta,
+            }
+            with open(self._log_file, "a", encoding="utf-8") as f:
+                f.write(json.dumps(record) + "\n")
+
+    def debug(self, message: str, **meta: Any) -> None:
+        self._emit("debug", message, meta)
+
+    def info(self, message: str, **meta: Any) -> None:
+        self._emit("info", message, meta)
+
+    def warn(self, message: str, **meta: Any) -> None:
+        self._emit("warn", message, meta)
+
+    def error(self, message: str, **meta: Any) -> None:
+        self._emit("error", message, meta)
+
+
+def create_logger(
+    verbose: bool = False, quiet: bool = False, log_file: str | Path | None = None
+) -> Logger:
+    level = "error" if quiet else "debug" if verbose else "info"
+    return Logger(level=level, log_file=log_file)
+
+
+# Keep the stdlib logging module importable/usable by consumers who'd rather
+# wire pdfslice_py into their own logging config instead of using Logger above.
+_stdlib_logger = logging.getLogger("pdfslice_py")

pdfslice_py/manifest.py

@@ -0,0 +1,76 @@
+"""Per-unit split manifest. Direct port of lib/manifest.ts.
+
+JSON keys are kept camelCase (matching the TypeScript original) so manifest
+files stay readable/interoperable between the two implementations.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+MANIFEST_FILENAME = ".pdfslice-manifest.json"
+
+
+@dataclass
+class ManifestImageEntry:
+    file: str  # file name relative to the manifest's folder
+    page: int
+    hash: str
+
+
+@dataclass
+class Manifest:
+    version: int
+    sourcePdf: str  # noqa: N815 - camelCase to match on-disk JSON schema
+    sourcePdfHash: str  # noqa: N815
+    pageCount: int  # noqa: N815
+    images: list[ManifestImageEntry] = field(default_factory=list)
+    updatedAt: str = ""  # noqa: N815
+    gatheredAt: str | None = None  # noqa: N815 - set once `gather` has run at least once
+    filenameTemplate: str = ""  # noqa: N815
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "version": self.version,
+                "sourcePdf": self.sourcePdf,
+                "sourcePdfHash": self.sourcePdfHash,
+                "pageCount": self.pageCount,
+                "images": [{"file": i.file, "page": i.page, "hash": i.hash} for i in self.images],
+                "updatedAt": self.updatedAt,
+                "gatheredAt": self.gatheredAt,
+                "filenameTemplate": self.filenameTemplate,
+            },
+            indent=2,
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> Manifest:
+        data = json.loads(text)
+        return cls(
+            version=data["version"],
+            sourcePdf=data["sourcePdf"],
+            sourcePdfHash=data["sourcePdfHash"],
+            pageCount=data["pageCount"],
+            images=[ManifestImageEntry(**i) for i in data.get("images", [])],
+            updatedAt=data.get("updatedAt", ""),
+            gatheredAt=data.get("gatheredAt"),
+            filenameTemplate=data.get("filenameTemplate", ""),
+        )
+
+
+def manifest_path_for(folder: str | Path) -> Path:
+    return Path(folder) / MANIFEST_FILENAME
+
+
+def read_manifest(folder: str | Path) -> Manifest | None:
+    p = manifest_path_for(folder)
+    if not p.exists():
+        return None
+    return Manifest.from_json(p.read_text(encoding="utf-8"))
+
+
+def write_manifest(folder: str | Path, manifest: Manifest) -> None:
+    manifest_path_for(folder).write_text(manifest.to_json(), encoding="utf-8")

pdfslice_py/split.py

@@ -0,0 +1,150 @@
+"""PDF -> per-page JPG splitting. Direct port of lib/split.ts.
+
+pdf-to-img + sharp (TS) map to pypdfium2 + Pillow here: pypdfium2 (Google's
+PDFium, BSD-licensed — chosen over PyMuPDF's AGPL license for a permissively
+licensed CLI) rasterizes each page at 2x scale (matching pdf-to-img's
+`{ scale: 2 }`), Pillow re-encodes it to JPEG at quality 90.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pypdfium2 as pdfium
+from pypdf import PdfReader
+
+from .discover import find_pdfs, page_image_name
+from .filename_template import DEFAULT_TEMPLATE
+from .hash import hash_file
+from .logger import Logger
+from .manifest import Manifest, ManifestImageEntry, write_manifest
+
+_RENDER_SCALE = 2  # ~2x native resolution, matches pdf-to-img's `{ scale: 2 }`
+_JPEG_QUALITY = 90
+
+
+@dataclass
+class SplitResult:
+    pdf: str
+    output_folder: str
+    page_count: int
+    images: list[str] = field(default_factory=list)
+    skipped: bool = False
+
+
+def _folder_name_for(pdf_path: str | Path) -> str:
+    return Path(pdf_path).stem
+
+
+def split_all(
+    input: str | Path,  # noqa: A002 - mirrors TS `input` option name
+    logger: Logger,
+    level: int = 1,
+    flatten: bool = False,
+    template: str = DEFAULT_TEMPLATE,
+    dry_run: bool = False,
+) -> list[SplitResult]:
+    pdfs = find_pdfs(input, level)
+    logger.info(f"Found {len(pdfs)} PDF file(s) under {input}", level=level)
+
+    results: list[SplitResult] = []
+    for pdf_path in pdfs:
+        results.append(
+            _split_one(
+                pdf_path,
+                input=input,
+                flatten=flatten,
+                template=template,
+                dry_run=dry_run,
+                logger=logger,
+            )
+        )
+    return results
+
+
+def _split_one(
+    pdf_path: str,
+    *,
+    input: str | Path,  # noqa: A002
+    flatten: bool,
+    template: str,
+    dry_run: bool,
+    logger: Logger,
+) -> SplitResult:
+    base_name = _folder_name_for(pdf_path)
+    parent_dir = Path(input) if flatten else Path(pdf_path).parent
+    output_folder = parent_dir / base_name
+    dest_pdf_path = output_folder / Path(pdf_path).name
+
+    logger.info(f"Processing {pdf_path}", output_folder=str(output_folder))
+
+    if dry_run:
+        logger.info(f"[dry-run] would create folder {output_folder}")
+        logger.info(f"[dry-run] would move {pdf_path} -> {dest_pdf_path} (copy, original kept)")
+        page_count = len(PdfReader(pdf_path).pages)
+        for i in range(1, page_count + 1):
+            logger.info(f"[dry-run] would create image {page_image_name(base_name, i, template)}")
+        return SplitResult(
+            pdf=str(pdf_path),
+            output_folder=str(output_folder),
+            page_count=page_count,
+            images=[],
+            skipped=True,
+        )
+
+    output_folder.mkdir(parents=True, exist_ok=True)
+
+    # "Move" without deleting the original: copy into the new folder. The
+    # original PDF at its source path is left untouched, per spec.
+    if not dest_pdf_path.exists():
+        shutil.copyfile(pdf_path, dest_pdf_path)
+
+    page_count = len(PdfReader(str(dest_pdf_path)).pages)
+
+    images: list[str] = []
+    image_entries: list[ManifestImageEntry] = []
+
+    doc = pdfium.PdfDocument(str(dest_pdf_path))
+    try:
+        for i in range(page_count):
+            page = doc[i]
+            bitmap = page.render(scale=_RENDER_SCALE)
+            img = bitmap.to_pil().convert("RGB")
+
+            page_num = i + 1
+            file_name = page_image_name(base_name, page_num, template)
+            image_path = output_folder / file_name
+            img.save(image_path, "JPEG", quality=_JPEG_QUALITY)
+            file_hash = hash_file(image_path)
+            images.append(str(image_path))
+            image_entries.append(ManifestImageEntry(file=file_name, page=page_num, hash=file_hash))
+            logger.debug("Wrote page image", file_name=file_name, page=page_num)
+
+            bitmap.close()
+            page.close()
+    finally:
+        doc.close()
+
+    source_pdf_hash = hash_file(dest_pdf_path)
+    manifest = Manifest(
+        version=1,
+        sourcePdf=dest_pdf_path.name,
+        sourcePdfHash=source_pdf_hash,
+        pageCount=page_count,
+        images=image_entries,
+        updatedAt=datetime.now(timezone.utc).isoformat(),
+        filenameTemplate=template,
+    )
+    write_manifest(output_folder, manifest)
+
+    logger.info(f"Split complete: {page_count} page(s)", output_folder=str(output_folder))
+    return SplitResult(
+        pdf=str(dest_pdf_path),
+        output_folder=str(output_folder),
+        page_count=page_count,
+        images=images,
+        skipped=False,
+    )

pdfslice_py-1.0.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: pdfslice-py
+Version: 1.0.0
+Summary: Split, gather, and verify PDF <-> page-image sets (Python port of pdfslice)
+Author: DuckyMomo20012
+License: # Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License
+        
+        By exercising the Licensed Rights (defined below), You accept and agree to be
+        bound by the terms and conditions of this Creative Commons
+        Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public
+        License"). To the extent this Public License may be interpreted as a contract,
+        You are granted the Licensed Rights in consideration of Your acceptance of these
+        terms and conditions, and the Licensor grants You such rights in consideration
+        of benefits the Licensor receives from making the Licensed Material available
+        under these terms and conditions.
+        
+        ## Section 1 – Definitions.
+        
+        - **Licensed Material**: the artistic or literary work, database, or other
+          material to which the Licensor applied this Public License.
+        - **Licensor**: the individual(s) or entity(ies) granting rights under this
+          Public License.
+        - **You**: the individual or entity exercising the Licensed Rights under this
+          Public License.
+        - **Share**: to provide material to the public by any means or process.
+        - **Adapted Material**: material derived from or modified based on the Licensed
+          Material.
+        - **NonCommercial**: not primarily intended for or directed towards commercial
+          advantage or monetary compensation.
+        
+        ## Section 2 – Scope.
+        
+        ### 2.1 License Grant
+        
+        Subject to the terms of this Public License, the Licensor grants You a
+        worldwide, royalty-free, non-exclusive, irrevocable license to:
+        
+        - **Share**: copy and redistribute the Licensed Material in any medium or
+          format.
+        - **Adapt**: remix, transform, and build upon the Licensed Material.
+        
+        ### 2.2 Conditions
+        
+        - **Attribution (BY)**: You must give appropriate credit, provide a link to the
+          license, and indicate if changes were made.
+        - **NonCommercial (NC)**: You may **not** use the material for commercial
+          purposes.
+        - **ShareAlike (SA)**: If you remix, transform, or build upon the material, you
+          must distribute your contributions under the same license as the original.
+        
+        ## Section 3 – Disclaimer.
+        
+        The Licensed Material is provided "as-is" without any warranties or guarantees.
+        The Licensor is not liable for any damages arising from its use.
+        
+        **Full License Text:**
+        [Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode)
+        
+Requires-Python: >=3.10
+License-File: LICENSE.md
+Requires-Dist: click>=8.1
+Requires-Dist: pypdf>=4.0
+Requires-Dist: pypdfium2>=4.30
+Requires-Dist: pillow>=10.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6; extra == "lint"
+Dynamic: license-file

pdfslice_py-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pdfslice_py/__init__.py,sha256=G-QH1Xiq_dM5rnFR978Sv2Ceoe3KYl9q66qIWctiwwg,177
+pdfslice_py/cli.py,sha256=_1--jOPg3SBLB1XKc4qmo-zxV_9PzEybKTEJzhJKewg,3817
+pdfslice_py/discover.py,sha256=OJtApa_ZxC37yMtqD52j2YMC_rp4rAU9BmBA4L0ROrQ,2468
+pdfslice_py/filename_template.py,sha256=i3c3W07t54CttFFDc0xOlCLqdrFMdi9U-rsEQblWJp4,1660
+pdfslice_py/gather.py,sha256=ryniS7Gqm1W1dOH6ARWVkfKxu85T7hPSFJa5gMfea_4,8026
+pdfslice_py/hash.py,sha256=eA9YRSyiWys-tAt2XvfjG5lfadoL1q0WJm1Vf_b8gNo,449
+pdfslice_py/logger.py,sha256=mq1LqU_pwzMa3ywmU4W76Jz7Lz3__8lUiigWcp8pklA,2642
+pdfslice_py/manifest.py,sha256=50Ck1QIO5HyExszZT5pGqojB-ZZIPSNhn24QDSpe90c,2457
+pdfslice_py/split.py,sha256=jUJOL-JoVKo5PRyGkgSTUEEv4NdOYvw7WnEUPvIxqCQ,4729
+pdfslice_py-1.0.0.dist-info/licenses/LICENSE.md,sha256=6kiYIyoUFr5c3ZomHtS80ceLoDxDYl8MR-3JN1TqGNU,2313
+pdfslice_py-1.0.0.dist-info/METADATA,sha256=roXnMhq94mHeRc9ZLSTe_mVZ7__7BIVdxiK2DiEETRo,3212
+pdfslice_py-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pdfslice_py-1.0.0.dist-info/entry_points.txt,sha256=GSO-zW8KjyBZnVO-Pehi5u7IdNhkF4jW48-h2vZckRo,49
+pdfslice_py-1.0.0.dist-info/top_level.txt,sha256=_i8YbxJ8q7ojzCHjzJs1J2ggAg2Yr4hNVEMZqqBBi04,12
+pdfslice_py-1.0.0.dist-info/RECORD,,

pdfslice_py-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pdfslice_py-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfslice = pdfslice_py.cli:cli

pdfslice_py-1.0.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,52 @@
+# Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be
+bound by the terms and conditions of this Creative Commons
+Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a contract,
+You are granted the Licensed Rights in consideration of Your acceptance of these
+terms and conditions, and the Licensor grants You such rights in consideration
+of benefits the Licensor receives from making the Licensed Material available
+under these terms and conditions.
+
+## Section 1 – Definitions.
+
+- **Licensed Material**: the artistic or literary work, database, or other
+  material to which the Licensor applied this Public License.
+- **Licensor**: the individual(s) or entity(ies) granting rights under this
+  Public License.
+- **You**: the individual or entity exercising the Licensed Rights under this
+  Public License.
+- **Share**: to provide material to the public by any means or process.
+- **Adapted Material**: material derived from or modified based on the Licensed
+  Material.
+- **NonCommercial**: not primarily intended for or directed towards commercial
+  advantage or monetary compensation.
+
+## Section 2 – Scope.
+
+### 2.1 License Grant
+
+Subject to the terms of this Public License, the Licensor grants You a
+worldwide, royalty-free, non-exclusive, irrevocable license to:
+
+- **Share**: copy and redistribute the Licensed Material in any medium or
+  format.
+- **Adapt**: remix, transform, and build upon the Licensed Material.
+
+### 2.2 Conditions
+
+- **Attribution (BY)**: You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made.
+- **NonCommercial (NC)**: You may **not** use the material for commercial
+  purposes.
+- **ShareAlike (SA)**: If you remix, transform, or build upon the material, you
+  must distribute your contributions under the same license as the original.
+
+## Section 3 – Disclaimer.
+
+The Licensed Material is provided "as-is" without any warranties or guarantees.
+The Licensor is not liable for any damages arising from its use.
+
+**Full License Text:**
+[Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode)

pdfslice_py-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdfslice_py