pdfpixel 0.3.1__py3-none-any.whl

pdfpixel/__init__.py

@@ -0,0 +1,3 @@
+"""PDFPixel — render each page of one or more PDFs to PNG images."""
+
+__version__ = "0.3.1"

pdfpixel/__main__.py

@@ -0,0 +1,3 @@
+from pdfpixel.cli import run
+
+run()

pdfpixel/cli.py

@@ -0,0 +1,194 @@
+"""pdfpixel CLI — the single entry point every OS's context-menu shim invokes.
+
+  pdfpixel FILE [FILE...]                 convert all pages (default verb)
+  pdfpixel [--pages SPEC] [--ask] \
+           [--format {png,jpg,webp,tiff}] [--dpi N] FILE [...]
+  pdfpixel merge    FILE.pdf FILE2.pdf...   concatenate into one PDF
+  pdfpixel split    FILE.pdf                one single-page PDF per page
+  pdfpixel compress [--quality low|medium|high] FILE.pdf   shrink images + qpdf
+  pdfpixel --version
+
+The default verb is ``convert``: unless the first token is one of
+{merge, split, compress}, the whole argv is routed to the convert path, so
+every historical invocation (bare file, ``--pages``, ``--ask``) still works.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from pdfpixel import __version__, core, pdfops
+from pdfpixel.dialog import AskResult
+from pdfpixel.notify import notify as _notify
+
+_OPS = ("merge", "split", "compress")
+_FORMATS = ("png", "jpg", "webp", "tiff")
+
+
+def _default_ask(path) -> AskResult:
+    from pdfpixel.dialog import ask_pages
+    return ask_pages(path)
+
+
+# --- convert (default verb) ----------------------------------------------
+
+def _build_convert_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pdfpixel")
+    parser.add_argument("--pages", help="page range, e.g. 5-8 or 1,3-5,9")
+    parser.add_argument("--ask", action="store_true",
+                        help="prompt for a page range (single file)")
+    parser.add_argument("--format", choices=_FORMATS, default="png",
+                        help="output image format (default: png)")
+    parser.add_argument("--dpi", type=int, default=core.DEFAULT_DPI,
+                        help=f"render resolution (default: {core.DEFAULT_DPI})")
+    parser.add_argument("files", nargs="*")
+    return parser
+
+
+def _normalize_ask(result, fmt: str, dpi: int):
+    """Coerce whatever ``ask`` returned into ``(spec, fmt, dpi)``.
+
+    Accepts an ``AskResult`` (whose fmt/dpi OVERRIDE the CLI ones) or a plain
+    string spec (which keeps the CLI's fmt/dpi). This keeps the injected-ask
+    seam working for both shapes.
+    """
+    if isinstance(result, str):
+        return result, fmt, dpi
+    spec = getattr(result, "spec", "")
+    return spec, getattr(result, "fmt", fmt), getattr(result, "dpi", dpi)
+
+
+def _convert(argv, ask, notifier) -> int:
+    args = _build_convert_parser().parse_args(argv)
+    fmt, dpi = args.format, args.dpi
+
+    if args.ask:
+        if len(args.files) != 1:
+            print("usage: pdfpixel --ask FILE.pdf", file=sys.stderr)
+            return 2
+        spec, fmt, dpi = _normalize_ask(ask(args.files[0]), fmt, dpi)
+        if not spec.strip():
+            return 0  # cancelled / empty -> no-op
+        try:
+            segments = core.parse_pages(spec)
+        except ValueError:
+            notifier(f"Invalid page range: {spec}", "")
+            return 2
+        results = [core.convert_pdf(Path(args.files[0]), segments,
+                                    fmt=fmt, dpi=dpi)]
+    else:
+        if not args.files:
+            print("usage: pdfpixel [--pages RANGE] [--format FMT] [--dpi N] "
+                  "FILE.pdf [FILE2.pdf ...]", file=sys.stderr)
+            return 2
+        segments = None
+        if args.pages is not None:
+            try:
+                segments = core.parse_pages(args.pages)
+            except ValueError:
+                notifier(f"Invalid page range: {args.pages}", "")
+                return 2
+        results = [core.convert_pdf(Path(p), segments, fmt=fmt, dpi=dpi)
+                   for p in args.files]
+
+    summary, body = core.build_summary(results)
+    notifier(summary, body)
+    print(summary)
+    return 0 if all(r.ok for r in results) else 1
+
+
+# --- merge / split / compress --------------------------------------------
+
+def _merge(argv, notifier) -> int:
+    parser = argparse.ArgumentParser(prog="pdfpixel merge")
+    parser.add_argument("files", nargs="*")
+    args = parser.parse_args(argv)
+    if not args.files:
+        print("usage: pdfpixel merge FILE.pdf [FILE2.pdf ...]", file=sys.stderr)
+        return 2
+    r = pdfops.merge([Path(p) for p in args.files])
+    if not r.ok:
+        notifier(r.error, "")
+        return 1
+    summary = f"Merged {len(args.files)} PDFs"
+    notifier(summary, str(r.path))
+    print(summary)
+    return 0
+
+
+def _split(argv, notifier) -> int:
+    parser = argparse.ArgumentParser(prog="pdfpixel split")
+    parser.add_argument("file")
+    args = parser.parse_args(argv)
+    r = pdfops.split(Path(args.file))
+    if not r.ok:
+        notifier(r.error, "")
+        return 1
+    summary = f"Split into {r.pages} pages"
+    notifier(summary, "")
+    print(summary)
+    return 0
+
+
+def _hsize(n: int) -> str:
+    """Human-readable byte size: 678 KB, 4.2 MB."""
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.0f} {unit}" if unit == "B" else f"{n:.1f} {unit}"
+        n /= 1024.0
+
+
+def _compress(argv, notifier) -> int:
+    parser = argparse.ArgumentParser(prog="pdfpixel compress")
+    parser.add_argument("file")
+    parser.add_argument("--quality", choices=("low", "medium", "high"),
+                        default="medium",
+                        help="image compression level (default: medium)")
+    args = parser.parse_args(argv)
+    src = Path(args.file)
+    before = src.stat().st_size if src.exists() else 0
+    r = pdfops.compress(src, quality=args.quality)
+    if not r.ok:
+        notifier(r.error, "")
+        return 1
+    after = r.path.stat().st_size
+    if before and after < before:
+        summary = f"Compressed {_hsize(before)} → {_hsize(after)} (-{(1 - after / before) * 100:.0f}%)"
+    elif before:
+        summary = f"Compressed {_hsize(before)} → {_hsize(after)} (no size reduction)"
+    else:
+        summary = "Compressed"
+    notifier(summary, r.path.name)
+    print(summary)
+    return 0
+
+
+# --- entry point ----------------------------------------------------------
+
+def main(argv, ask=None, notifier=None) -> int:
+    ask = ask or _default_ask
+    notifier = notifier or _notify
+
+    if argv and argv[0] == "--version":
+        print(f"pdfpixel {__version__}")
+        return 0
+
+    if argv and argv[0] in _OPS:
+        verb, rest = argv[0], argv[1:]
+        if verb == "merge":
+            return _merge(rest, notifier)
+        if verb == "split":
+            return _split(rest, notifier)
+        return _compress(rest, notifier)
+
+    # default verb = convert: bare files, --pages/--ask/--format/--dpi, or empty
+    return _convert(argv, ask, notifier)
+
+
+def run():  # console-script / frozen entry point
+    raise SystemExit(main(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    run()

pdfpixel/core.py

@@ -0,0 +1,174 @@
+"""pdfpixel core — portable PDF-to-PNG engine (pypdfium2 + Pillow).
+
+Pure conversion/naming/range logic with no GUI or notification code, so it is
+fully unit-testable and identical across Linux, Windows and macOS.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+import pypdfium2 as pdfium
+
+DEFAULT_DPI = 200  # preserve current behaviour (pypdfium2 renders relative to 72 dpi)
+
+# fmt -> output extension; "jpeg" is an alias of "jpg"
+_FMT_EXT = {"png": "png", "jpg": "jpg", "jpeg": "jpg", "webp": "webp", "tiff": "tiff"}
+
+
+@dataclass
+class FileResult:
+    path: Path
+    ok: bool
+    pages: int = 0
+    error: str | None = None
+
+
+def unique_output_dir(pdf_path: Path) -> Path:
+    """Return a non-existing output dir beside the PDF, suffixed (n) on collision."""
+    pdf_path = Path(pdf_path)
+    candidate = pdf_path.parent / pdf_path.stem
+    n = 1
+    while candidate.exists():
+        candidate = pdf_path.parent / f"{pdf_path.stem} ({n})"
+        n += 1
+    return candidate
+
+
+# --- page-range parsing --------------------------------------------------
+
+def _pos_int(s: str) -> int:
+    if not s.isdigit():
+        raise ValueError(f"not a positive integer: {s!r}")
+    v = int(s)
+    if v < 1:
+        raise ValueError(f"page numbers start at 1: {s!r}")
+    return v
+
+
+def _parse_segment(s: str):
+    """Parse one contiguous segment into (first, last); None means open-ended."""
+    if "-" in s:
+        left, _, right = s.partition("-")
+        if "-" in right:
+            raise ValueError(f"too many dashes: {s!r}")
+        left, right = left.strip(), right.strip()
+        first = _pos_int(left) if left else None
+        last = _pos_int(right) if right else None
+        if first is None and last is None:
+            raise ValueError(f"empty range: {s!r}")
+        if first is not None and last is not None and first > last:
+            raise ValueError(f"reversed range: {s!r}")
+        return (first, last)
+    n = _pos_int(s)
+    return (n, n)
+
+
+def parse_pages(spec: str):
+    """Parse a page spec into a list of (first, last) segments.
+
+    Comma-separated segments, each ``N`` -> (N, N), ``N-M`` -> (N, M),
+    ``N-`` -> (N, None), ``-M`` -> (None, M). Pages are 1-based; None means
+    open-ended. Blank segments (stray commas) are ignored. Raises ValueError on
+    a malformed segment or if no segment remains.
+    """
+    segments = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        segments.append(_parse_segment(part))
+    if not segments:
+        raise ValueError(f"no pages: {spec!r}")
+    return segments
+
+
+def _expand(segments, total: int):
+    """Segments -> sorted, deduped list of page numbers clamped to [1, total].
+
+    Out-of-range pages are dropped (a mix like 1,50 on a 12-page doc yields [1])."""
+    pages = set()
+    for first, last in segments:
+        lo = 1 if first is None else first
+        hi = total if last is None else last
+        for n in range(lo, hi + 1):
+            if 1 <= n <= total:
+                pages.add(n)
+    return sorted(pages)
+
+
+# --- conversion ----------------------------------------------------------
+
+def page_count(pdf_path: Path):
+    """Page count, or None if the PDF can't be read (encrypted/corrupt)."""
+    try:
+        doc = pdfium.PdfDocument(str(pdf_path))
+    except pdfium.PdfiumError:
+        return None
+    try:
+        return len(doc)
+    finally:
+        doc.close()
+
+
+def convert_pdf(pdf_path: Path, segments=None, fmt: str = "png",
+                dpi: int = DEFAULT_DPI) -> FileResult:
+    """Render pages of one PDF to images in a sibling folder.
+
+    ``segments`` is None (all pages) or a list of (first, last) tuples
+    (None = open-ended). ``fmt`` is one of png/jpg/webp/tiff ("jpeg" aliases
+    "jpg"). ``dpi`` sets the render scale (dpi / 72). Images are named by
+    original page number, zero-padded to the document's page-count width, with
+    the format's extension. JPG has no alpha so the image is flattened to RGB.
+    """
+    fmt = fmt.lower()
+    ext = _FMT_EXT.get(fmt)
+    if ext is None:
+        return FileResult(pdf_path, ok=False, error=f"unsupported format: {fmt}")
+    pdf_path = Path(pdf_path)
+    if not os.access(pdf_path.parent, os.W_OK):
+        return FileResult(pdf_path, ok=False, error="read-only directory")
+    try:
+        doc = pdfium.PdfDocument(str(pdf_path))
+    except pdfium.PdfiumError:
+        return FileResult(pdf_path, ok=False, error="encrypted or unreadable PDF")
+    try:
+        total = len(doc)
+        pages = list(range(1, total + 1)) if segments is None else _expand(segments, total)
+        if not pages:  # nothing in range -> don't create an empty folder
+            return FileResult(pdf_path, ok=False, error="no pages produced")
+        out_dir = unique_output_dir(pdf_path)
+        try:
+            out_dir.mkdir()
+        except OSError as e:
+            return FileResult(pdf_path, ok=False, error=str(e))
+        width = len(str(total))
+        scale = dpi / 72.0
+        try:
+            for n in pages:
+                bitmap = doc[n - 1].render(scale=scale)
+                img = bitmap.to_pil()
+                if ext == "jpg":  # JPG has no alpha channel
+                    img = img.convert("RGB")
+                img.save(out_dir / f"{n:0{width}d}.{ext}")
+        except Exception as e:  # render/save failure -> no half-written folder
+            shutil.rmtree(out_dir, ignore_errors=True)
+            return FileResult(pdf_path, ok=False, error=str(e))
+        return FileResult(pdf_path, ok=True, pages=len(pages))
+    finally:
+        doc.close()
+
+
+def build_summary(results):
+    ok = [r for r in results if r.ok]
+    failed = [r for r in results if not r.ok]
+    total_pages = sum(r.pages for r in ok)
+    summary = f"Converted {len(ok)} PDF{'s' if len(ok) != 1 else ''}"
+    if failed:
+        summary += f" · {len(failed)} failed"
+    lines = [f"{total_pages} pages total"]
+    for r in failed:
+        lines.append(f"✗ {r.path.name}: {r.error}")
+    return summary, "\n".join(lines)

pdfpixel/dialog.py

@@ -0,0 +1,85 @@
+"""Cross-platform Custom… prompt via tkinter (bundled with the frozen
+runtime). Returns an ``AskResult(spec, fmt, dpi)``; spec is "" if
+cancelled/empty (the caller treats an empty spec as a no-op)."""
+from __future__ import annotations
+
+from collections import namedtuple
+
+from pdfpixel import core
+
+AskResult = namedtuple("AskResult", "spec fmt dpi")
+
+_PROMPT = "Pages to convert (e.g. 1  ·  5-8  ·  -4  ·  1,3-5,9  ·  10-):"
+
+# Format dropdown labels -> fmt string passed to core.convert_pdf
+_FORMATS = [("PNG", "png"), ("JPG", "jpg"), ("WEBP", "webp"), ("TIFF", "tiff")]
+
+# Resolution dropdown labels -> dpi int
+_RESOLUTIONS = [
+    ("Screen (96)", 96),
+    ("Default (200)", 200),
+    ("Print (300)", 300),
+    ("High (600)", 600),
+]
+
+
+def ask_pages(pdf_path) -> AskResult:
+    import tkinter as tk
+    from tkinter import ttk
+
+    n = core.page_count(pdf_path)
+    state = {"spec": "", "fmt": "png", "dpi": core.DEFAULT_DPI}
+
+    root = tk.Tk()
+    root.title("PDFPixel")
+    root.resizable(False, False)
+
+    frm = tk.Frame(root, padx=16, pady=12)
+    frm.pack()
+    if n:
+        tk.Label(frm, text=f"Document has {n} page{'' if n == 1 else 's'}").pack(
+            anchor="w")
+
+    fmt_labels = [label for label, _ in _FORMATS]
+    res_labels = [label for label, _ in _RESOLUTIONS]
+    fmt_var = tk.StringVar(value=fmt_labels[0])          # PNG
+    res_var = tk.StringVar(value=res_labels[1])          # Default (200)
+
+    tk.Label(frm, text="Format:").pack(anchor="w")
+    fmt_box = ttk.Combobox(frm, textvariable=fmt_var, values=fmt_labels,
+                           state="readonly", width=36)
+    fmt_box.pack(fill="x", pady=(2, 8))
+
+    tk.Label(frm, text="Resolution:").pack(anchor="w")
+    res_box = ttk.Combobox(frm, textvariable=res_var, values=res_labels,
+                           state="readonly", width=36)
+    res_box.pack(fill="x", pady=(2, 8))
+
+    tk.Label(frm, text=_PROMPT).pack(anchor="w")
+
+    entry = tk.Entry(frm, width=38)
+    entry.pack(fill="x", pady=(4, 10))
+    entry.focus_set()
+
+    def convert(*_):
+        state["spec"] = entry.get()
+        state["fmt"] = dict(_FORMATS)[fmt_var.get()]
+        state["dpi"] = dict(_RESOLUTIONS)[res_var.get()]
+        root.destroy()
+
+    def cancel(*_):
+        state["spec"] = ""
+        state["fmt"] = "png"
+        state["dpi"] = core.DEFAULT_DPI
+        root.destroy()
+
+    btns = tk.Frame(frm)
+    btns.pack(anchor="e")
+    tk.Button(btns, text="Cancel", command=cancel).pack(side="left", padx=4)
+    tk.Button(btns, text="Convert", command=convert, default="active").pack(side="left")
+
+    entry.bind("<Return>", convert)
+    root.bind("<Escape>", cancel)
+
+    root.mainloop()
+    return AskResult(state["spec"].strip(), state["fmt"], state["dpi"])

pdfpixel/notify.py

@@ -0,0 +1,30 @@
+"""Best-effort desktop notifications, per OS. Never raises."""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+
+
+def notify(summary: str, body: str = "") -> None:
+    system = platform.system()
+    try:
+        if system == "Linux":
+            if shutil.which("notify-send"):
+                subprocess.run(["notify-send", summary, body], check=False)
+        elif system == "Darwin":
+            safe = body.replace('"', "'")
+            title = summary.replace('"', "'")
+            subprocess.run(
+                ["osascript", "-e",
+                 f'display notification "{safe}" with title "{title}"'],
+                check=False,
+            )
+        elif system == "Windows":
+            try:
+                from winotify import Notification
+                Notification(app_id="PDFPixel", title=summary, msg=body).show()
+            except Exception:
+                pass
+    except Exception:
+        pass  # notifications are non-essential

pdfpixel/pdfops.py

@@ -0,0 +1,230 @@
+"""pdfpixel pdfops — portable PDF operations (merge/split/compress) via pikepdf.
+
+Pure file-level PDF manipulation with no GUI or notification code, so it is
+fully unit-testable and identical across Linux, Windows and macOS. Reuses the
+``FileResult`` dataclass from :mod:`pdfpixel.core` for the ``ok``/``error``
+contract shared with the render engine.
+"""
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import pikepdf
+from PIL import Image  # noqa: F401  (kept for parity with the render engine)
+
+from pdfpixel.core import FileResult
+
+# Image-compression quality presets: (max_pixel_dimension | None, jpeg_quality).
+QUALITY_PRESETS = {
+    "low": (1200, 60),
+    "medium": (2000, 75),
+    "high": (None, 85),
+}
+
+
+def unique_output_path(directory: Path, stem: str, suffix: str = ".pdf") -> Path:
+    """Return a non-existing path ``stem{suffix}`` in ``directory``.
+
+    On collision, bump to ``stem-1``, ``stem-2``... so an existing file is never
+    overwritten.
+    """
+    directory = Path(directory)
+    candidate = directory / f"{stem}{suffix}"
+    n = 1
+    while candidate.exists():
+        candidate = directory / f"{stem}-{n}{suffix}"
+        n += 1
+    return candidate
+
+
+def merge(inputs: list[Path], out: Path | None = None) -> FileResult:
+    """Concatenate all pages of ``inputs`` (in order) into one PDF.
+
+    ``out`` defaults to a non-clobbering ``merged.pdf`` in ``inputs[0].parent``.
+    On any unreadable/encrypted input, or zero inputs, returns
+    ``FileResult(ok=False, ...)`` and writes nothing. ``pages`` is the total
+    number of pages written.
+    """
+    inputs = [Path(p) for p in inputs]
+    if not inputs:
+        return FileResult(Path(), ok=False, error="no input files")
+
+    merged = pikepdf.Pdf.new()
+    try:
+        total = 0
+        for src in inputs:
+            try:
+                with pikepdf.Pdf.open(src) as doc:
+                    merged.pages.extend(doc.pages)
+                    total += len(doc.pages)
+            except (pikepdf.PasswordError, pikepdf.PdfError):
+                return FileResult(src, ok=False, error="encrypted or unreadable PDF")
+            except OSError as e:
+                return FileResult(src, ok=False, error=str(e))
+
+        if out is None:
+            out = unique_output_path(inputs[0].parent, "merged")
+        else:
+            out = Path(out)
+        try:
+            merged.save(out)
+        except OSError as e:
+            return FileResult(out, ok=False, error=str(e))
+        return FileResult(out, ok=True, pages=total)
+    finally:
+        merged.close()
+
+
+def split(pdf_path: Path) -> FileResult:
+    """Write one single-page PDF per page beside the source.
+
+    Files are named ``f"{stem}_p{n:0{width}d}.pdf"`` where ``width`` is the
+    page-count width. Never overwrites the source. ``pages`` is the number of
+    files written. Encrypted/unreadable input -> ``FileResult(ok=False, ...)``.
+    """
+    pdf_path = Path(pdf_path)
+    try:
+        doc = pikepdf.Pdf.open(pdf_path)
+    except (pikepdf.PasswordError, pikepdf.PdfError):
+        return FileResult(pdf_path, ok=False, error="encrypted or unreadable PDF")
+    except OSError as e:
+        return FileResult(pdf_path, ok=False, error=str(e))
+    try:
+        total = len(doc.pages)
+        width = len(str(total))
+        written = 0
+        for n in range(1, total + 1):
+            single = pikepdf.Pdf.new()
+            try:
+                single.pages.append(doc.pages[n - 1])
+                out = pdf_path.parent / f"{pdf_path.stem}_p{n:0{width}d}.pdf"
+                single.save(out)
+            finally:
+                single.close()
+            written += 1
+        return FileResult(pdf_path, ok=True, pages=written)
+    finally:
+        doc.close()
+
+
+def _iter_image_xobjects(doc):
+    """Yield each unique image XObject stream reachable from any page.
+
+    Walks page Resources and recurses into Form XObjects' Resources. Dedups by
+    object id so a shared image is visited (and recompressed) once.
+    """
+    seen = set()
+    stack = []
+    for page in doc.pages:
+        res = page.get("/Resources")
+        if res is not None:
+            stack.append(res)
+    while stack:
+        res = stack.pop()
+        xobjs = res.get("/XObject")
+        if xobjs is None:
+            continue
+        for _name, xobj in xobjs.items():
+            try:
+                key = xobj.objgen
+            except Exception:
+                key = id(xobj)
+            if key in seen:
+                continue
+            seen.add(key)
+            subtype = str(xobj.get("/Subtype"))
+            if subtype == "/Image":
+                yield xobj
+            elif subtype == "/Form":
+                fres = xobj.get("/Resources")
+                if fres is not None:
+                    stack.append(fres)
+
+
+def _recompress_image(xobj, max_dim, jpeg_quality):
+    """Re-encode one image XObject to JPEG, downscaled to ``max_dim``.
+
+    Returns ``(jpeg_bytes, (w, h), mode)`` if the image is safe to recompress
+    AND the result is smaller than the current stream; otherwise ``None`` (leave
+    the original untouched). Safe = plain RGB/grayscale, 8-bit, no transparency
+    mask, not a stencil — so text, vectors, CMYK, indexed, and masked/alpha
+    images are never corrupted.
+    """
+    if bool(xobj.get("/ImageMask", False)):
+        return None
+    if "/SMask" in xobj or "/Mask" in xobj:
+        return None
+    try:
+        pil = pikepdf.PdfImage(xobj).as_pil_image()
+    except Exception:
+        return None  # undecodable colorspace/filter -> leave as-is
+    if pil.mode not in ("RGB", "L"):
+        return None  # indexed/CMYK/etc -> leave as-is
+
+    w, h = pil.size
+    if max_dim and max(w, h) > max_dim:
+        scale = max_dim / float(max(w, h))
+        pil = pil.resize((max(1, round(w * scale)), max(1, round(h * scale))))
+
+    buf = io.BytesIO()
+    pil.save(buf, format="JPEG", quality=jpeg_quality, optimize=True)
+    data = buf.getvalue()
+    try:
+        old = len(xobj.read_raw_bytes())
+    except Exception:
+        old = None
+    if old is not None and len(data) >= old:
+        return None  # would not shrink -> keep original
+    return data, pil.size, pil.mode
+
+
+def compress(pdf_path: Path, quality: str = "medium") -> FileResult:
+    """Write ``f"{stem}_compressed.pdf"`` beside source, shrinking images.
+
+    Walks the PDF's image XObjects and re-encodes the safe ones (RGB/grayscale,
+    no transparency) to downscaled JPEG per the ``quality`` preset, then applies
+    a qpdf structural pass (object streams + stream recompression). Text and
+    vectors are preserved; CMYK/indexed/masked images are left untouched. Never
+    overwrites the source. ``pages`` is the page count. Encrypted/unreadable
+    input or an unknown ``quality`` -> ``FileResult(ok=False, ...)``.
+    """
+    pdf_path = Path(pdf_path)
+    if quality not in QUALITY_PRESETS:
+        return FileResult(pdf_path, ok=False, error=f"unknown quality: {quality}")
+    max_dim, jpeg_quality = QUALITY_PRESETS[quality]
+    try:
+        doc = pikepdf.Pdf.open(pdf_path)
+    except (pikepdf.PasswordError, pikepdf.PdfError):
+        return FileResult(pdf_path, ok=False, error="encrypted or unreadable PDF")
+    except OSError as e:
+        return FileResult(pdf_path, ok=False, error=str(e))
+    try:
+        for xobj in _iter_image_xobjects(doc):
+            res = _recompress_image(xobj, max_dim, jpeg_quality)
+            if res is None:
+                continue
+            data, (w, h), mode = res
+            xobj.write(data, filter=pikepdf.Name("/DCTDecode"))
+            xobj.ColorSpace = (
+                pikepdf.Name("/DeviceRGB") if mode == "RGB"
+                else pikepdf.Name("/DeviceGray")
+            )
+            xobj.Width, xobj.Height = w, h
+            xobj.BitsPerComponent = 8
+            for k in ("/Decode", "/DecodeParms"):
+                if k in xobj:
+                    del xobj[k]
+
+        out = pdf_path.parent / f"{pdf_path.stem}_compressed.pdf"
+        try:
+            doc.save(
+                out,
+                compress_streams=True,
+                object_stream_mode=pikepdf.ObjectStreamMode.generate,
+            )
+        except OSError as e:
+            return FileResult(pdf_path, ok=False, error=str(e))
+        return FileResult(out, ok=True, pages=len(doc.pages))
+    finally:
+        doc.close()

pdfpixel-0.3.1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: pdfpixel
+Version: 0.3.1
+Summary: Right-click a PDF -> every page as a PNG. Cross-platform (Linux/Windows/macOS).
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pypdfium2>=4
+Requires-Dist: pillow>=9
+Requires-Dist: pikepdf
+Requires-Dist: winotify>=1.1; platform_system == "Windows"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: fpdf2>=2.7; extra == "dev"
+Requires-Dist: pyinstaller>=6; extra == "dev"
+Dynamic: license-file
+
+# PDFPixel
+
+Right-click a PDF → the **PDFPixel** menu → turn its pages into images, or
+merge / split / compress it — straight from your file manager, fully local, no
+app to open. Works on **Linux, Windows, and macOS**.
+
+- **Convert** every page (or a range) to **PNG / JPG / WEBP / TIFF** at any DPI.
+- **Merge** several PDFs into one, **split** a PDF into per-page files.
+- **Compress** — real image downsampling that keeps text sharp and selectable.
+
+📖 [USAGE.md](USAGE.md) — every action, in and out · 🛠 [ARCHITECTURE.md](ARCHITECTURE.md) · 🤝 [CONTRIBUTING.md](CONTRIBUTING.md) · 📦 [DISTRIBUTING.md](packaging/linux/DISTRIBUTING.md)
+
+## Supported platforms
+
+| Platform | Status | How to run it |
+|---|---|---|
+| **Linux**, glibc ≥ 2.31 — Ubuntu 20.04+, Debian 11+, Mint 20+, Pop!_OS 20.04+, Fedora 32+, **RHEL/Rocky/Alma 9+**, openSUSE Leap 15.3+/Tumbleweed, Arch & derivatives | ✅ native | `.deb` / `.rpm` / AppImage / AUR |
+| **Older or musl Linux** — RHEL/Rocky/Alma 8, Debian 10, Ubuntu 18.04, CentOS 7, Alpine (glibc < 2.31 or musl) | ✅ portable | **Flatpak** (own runtime, any distro) or `pipx install pdfpixel` |
+| **CPU architectures** | ✅ | x86-64 (amd64) **and** ARM64 (aarch64) — both built in CI |
+| **Windows** 10 / 11 | ✅ | `pdfpixel-setup.exe` (per-user, unsigned) |
+| **macOS** 12+ (Intel & Apple Silicon) | ⚠️ experimental | `.dmg`, **unsigned** — Terminal install (below) |
+
+> **Signing status — builds are unsigned.** We don't have an **Apple Developer
+> ID**, so the macOS build can't be signed/notarized: expect a Gatekeeper prompt
+> and use the Terminal install method below. Windows shows a one-time SmartScreen
+> prompt. The native right-click menu ships only with the Linux `.deb`/`.rpm`/AUR
+> packages — AppImage, Flatpak and pip are CLI/app-only (a sandbox/portability
+> limit, not a choice).
+
+## Install
+
+Grab the artifact for your OS from the [Releases](../../releases) page.
+
+### Linux
+
+Native packages are built on glibc 2.31, so they run on **glibc ≥ 2.31**
+(Ubuntu 20.04+, Debian 11+, Fedora 32+, RHEL/Rocky/Alma 9+, openSUSE Leap 15.3+),
+amd64 **and** arm64, with no security prompt. On **older distros** (RHEL 8,
+Debian 10, Ubuntu 18.04, CentOS 7) or **musl** (Alpine), use **Flatpak** or
+`pipx install pdfpixel` instead.
+
+| Distro family | Install |
+|---|---|
+| Debian/Ubuntu/Mint/Pop!_OS | `sudo apt install ./pdfpixel_*.deb` |
+| Fedora/RHEL/openSUSE | `sudo dnf install ./pdfpixel-*.rpm` |
+| Arch/CachyOS/EndeavourOS | `yay -S pdfpixel` *(AUR)* |
+| **Any** (no install) | `chmod +x PDFPixel-*.AppImage` then run it |
+| Any (Python) | `pipx install pdfpixel` *(CLI only)* |
+
+The PDF engine and dialog are bundled — no poppler, no system Python. The
+`.deb`/`.rpm` install the **right-click menu** for GNOME Files (Nautilus),
+Cinnamon (Nemo), MATE (Caja) and KDE Dolphin (install the matching binding —
+`nautilus-python` / `nemo-python` / `python3-caja` — for the GTK ones); XFCE
+Thunar takes a one-time manual step (`integrations/linux/thunar-actions.md`).
+After installing, reload the file manager (`nautilus -q`) or log out/in.
+
+The **AppImage** and **pip/Flatpak** builds are the app/CLI only (no host
+right-click menu — a sandbox/portability limit), but run anywhere:
+`./PDFPixel-*.AppImage --pages 1,3-5 file.pdf`.
+
+*(From a checkout: `./install.sh` — uses system Python, needs `python3-tk`.)*
+
+### Windows 10/11
+
+1. Download **`pdfpixel-setup.exe`** and run it (**per-user, no admin**).
+2. **SmartScreen** — "Windows protected your PC": **More info** → **Run anyway**.
+3. Finish the installer (installs to `%LOCALAPPDATA%\Programs\PDFPixel`).
+4. **Right-click a PDF** → **PDFPixel** → **All Pages** / **First Page** /
+   **Custom Range…** / **Split into Pages** / **Compress**
+   (Windows 11: under **Show more options**, or press **Shift+F10**).
+   *(Merge is command-line only on Windows — classic shell verbs run per file.)*
+
+Uninstall via *Settings ▸ Apps* (removes the menu entry too).
+
+### macOS  *(experimental)*
+
+The build is unsigned, and recent macOS no longer offers a right-click "Open" for
+downloaded scripts, so use Terminal (it bypasses Gatekeeper's launch gate
+cleanly):
+
+1. Download **`pdfpixel-*.dmg`** and double-click to mount it.
+2. In **Terminal**, run (prefix with `sudo` if it can't write to `/Applications`):
+   ```bash
+   bash "/Volumes/PDFPixel/Install PDFPixel.command"
+   ```
+   This copies the app to `/Applications/PDFPixel`, installs the Quick Actions to
+   `~/Library/Services`, and clears the quarantine flag.
+3. **Right-click a PDF** in Finder → **Quick Actions** → **PDFPixel: All Pages** /
+   **First Page** / **Custom Range…** / **Split into Pages** / **Compress** /
+   **Merge PDFs** (select 2+ PDFs for Merge).
+4. Not listed? Enable it under **System Settings → Privacy & Security →
+   Extensions → Finder** (or **Keyboard → Keyboard Shortcuts → Services**).
+
+> No prompt at all: build it yourself on your Mac (locally-built files carry no
+> quarantine) — `bash packaging/macos/build_dmg.sh`.
+
+**Always-works fallback** (any OS) — run the bundled CLI directly:
+
+```bash
+/Applications/PDFPixel/pdfpixel --pages 1,3-5 ~/file.pdf    # macOS
+"%LOCALAPPDATA%\Programs\PDFPixel\pdfpixel.exe" file.pdf     # Windows
+pdfpixel --pages 5-8 file.pdf                                # Linux
+```
+
+## Usage at a glance
+
+```bash
+pdfpixel file.pdf                          # all pages → PNG @ 200 DPI
+pdfpixel --pages 1,3-5,9 file.pdf          # a page-range mix
+pdfpixel --format jpg --dpi 300 file.pdf   # JPG at print resolution
+pdfpixel --ask file.pdf                    # pop the Custom… dialog
+pdfpixel merge a.pdf b.pdf                 # → merged.pdf
+pdfpixel split report.pdf                  # → report_p1.pdf, report_p2.pdf, …
+pdfpixel compress --quality low scan.pdf   # shrink images
+```
+
+Outputs land beside the source and never overwrite it. Exit codes: `0` ok ·
+`1` ≥1 file failed · `2` no files / malformed `--pages`. Full reference and the
+right-click flow are in **[USAGE.md](USAGE.md)**.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+The codebase is a thin file-manager shim that launches a self-contained CLI
+(`pdfpixel/`: `core` rendering, `pdfops` merge/split/compress, `cli`, `dialog`,
+`notify`); the menu is generated from one `ACTIONS` list. See
+**[ARCHITECTURE.md](ARCHITECTURE.md)** for the design and
+**[CONTRIBUTING.md](CONTRIBUTING.md)** for setup, build, and release steps.
+
+## Notes / scope
+
+- **Self-contained**: each installer bundles a frozen Python runtime, the PDF
+  engine (PDFium via `pypdfium2`, `pikepdf`), and the tkinter dialog. No system
+  Python or poppler required.
+- **Unsigned** — hence the SmartScreen / Gatekeeper prompts above. macOS
+  signing/notarization needs an Apple Developer ID we don't currently have, so the
+  Terminal install is the supported macOS path; Windows signing may come later
+  with a certificate.
+- **Sandboxed builds** (Flatpak/Snap) and the AppImage/pip CLI can't install a
+  host file-manager menu — that's a platform limit. The full right-click menu
+  ships with the `.deb`/`.rpm`/AUR packages.
+- **Windows/macOS menus** now expose the full action set (All Pages, First Page,
+  Custom Range, Split, Compress; macOS also Merge). Windows Merge stays CLI-only
+  (classic shell verbs run per selected file). Lands in the next release build.

pdfpixel-0.3.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+pdfpixel/__init__.py,sha256=NRvEfzkP6I6kOWbR1FBbRMj4M-XbwHAP_dAY7rBi0VU,94
+pdfpixel/__main__.py,sha256=cDFZ557Ix845vVY25w63zFWACPL1EpG_2jUQrd_7Zj4,36
+pdfpixel/cli.py,sha256=_TuV0Xku1mExbZM1qEo4cDFHWocIf3D9mV30q1qH2N8,6749
+pdfpixel/core.py,sha256=WGxcnjp6-q85MswItU-9ndB9J7NlEh1mGT1NFWKn1eY,6100
+pdfpixel/dialog.py,sha256=sc5yPff4Td7VEAuKZ_XSwCBXokpoVe1BMs1mibYFehc,2737
+pdfpixel/notify.py,sha256=xlO2SpACsRCyiwCBDd25pL2h_RHfEu3FtGKroU5MmuE,992
+pdfpixel/pdfops.py,sha256=4jjSPIRjEAG84xthaMgqRaGwipiWESXu-cJ-A_NbVe8,8328
+pdfpixel-0.3.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pdfpixel-0.3.1.dist-info/METADATA,sha256=-kRVm6S7XcvkHLqN2N3WQKPuH919ACd9oxgLQjWTQ-8,7960
+pdfpixel-0.3.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pdfpixel-0.3.1.dist-info/entry_points.txt,sha256=HymSgEcg3iZSly74RyVu7wIfqvKILPaKiSriOrC7N4k,46
+pdfpixel-0.3.1.dist-info/top_level.txt,sha256=jMrWe6yDFoxTaQK6GSiNIMskEe8bOnzgJ5UVEYmm2ns,9
+pdfpixel-0.3.1.dist-info/RECORD,,

pdfpixel-0.3.1.dist-info/WHEEL

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

pdfpixel-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pdfpixel = pdfpixel.cli:run

pdfpixel-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pdfpixel-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+pdfpixel