epub-pdf-wrap 0.1.1__tar.gz

epub_pdf_wrap-0.1.1/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026, Andrea Esuli (andrea@esuli.it)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1 Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+2 Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+3 Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

epub_pdf_wrap-0.1.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: epub-pdf-wrap
+Version: 0.1.1
+Summary: Convert a PDF to an EPUB by wrapping each rendered page in an EPUB page
+Author-email: Andrea Esuli <andrea@esuli.it>
+License-Expression: BSD-3-Clause
+Project-URL: Home, https://github.com/aesuli/epub_pdf_wrap
+Keywords: pdf,epub,conversion,render
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyMuPDF>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ebooklib>=0.18; extra == "dev"
+Dynamic: license-file
+
+# EPUB PDF wrap
+
+Converts a PDF into an EPUB by rendering and wrapping each page of the PDF in
+an EPUB page. This is specifically aimed at PDF files that cannot be converted
+into EPUB any other way without corrupting their visual rendering (comics,
+scientific papers...).
+
+## Installation
+
+```
+pip install epub-pdf-wrap
+```
+
+From source (with dev dependencies for testing):
+
+```
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```
+epub-pdf-wrap <pdf-filename> [-o <epub-filename>]
+```
+
+By default the output filename is the input filename with the `pdf` extension
+replaced by the `epub` extension. Running without `pip install` also works via
+`python -m epub_pdf_wrap`.
+
+### Options
+
+- `-r <num>, --resolution <num>`: target render width in pixels for the pages
+  in the output file. By default the pages are rendered at the resolution the
+  PDF itself declares.
+- `-c, --crop-global`: trim the white margins around the page content using
+  one common inset for all pages (safe: never clips content on any page, all
+  pages keep the same size).
+- `--crop-page`: trim the white margins around each page's own content, page
+  by page (trims more aggressively but page sizes may vary).
+
+`-c/--crop-global` and `--crop-page` are mutually exclusive; with neither
+flag the margins are left as-is.
+
+## Metadata
+
+Document metadata (title, author, subject, keywords and creation date) is
+taken from the PDF and written into the EPUB. Empty fields are omitted; the
+title falls back to the input filename if the PDF has none.
+
+## Examples
+
+Convert a paper at a wider resolution and name the output explicitly:
+
+```
+epub-pdf-wrap paper.pdf -o paper.epub -r 1400
+```
+
+## Development
+
+```
+python -m venv .venv
+.venv\Scripts\activate        # Windows  (or `source .venv/bin/activate` elsewhere)
+pip install -e ".[dev]"
+pytest
+```
+
+`samples/` contains real input PDFs for manually verifying the output.
+
+## License
+
+Distributed under the BSD 3-Clause License; see `LICENSE`.
+Copyright (c) 2026, Andrea Esuli (andrea@esuli.it).

epub_pdf_wrap-0.1.1/README.md

@@ -0,0 +1,72 @@
+# EPUB PDF wrap
+
+Converts a PDF into an EPUB by rendering and wrapping each page of the PDF in
+an EPUB page. This is specifically aimed at PDF files that cannot be converted
+into EPUB any other way without corrupting their visual rendering (comics,
+scientific papers...).
+
+## Installation
+
+```
+pip install epub-pdf-wrap
+```
+
+From source (with dev dependencies for testing):
+
+```
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```
+epub-pdf-wrap <pdf-filename> [-o <epub-filename>]
+```
+
+By default the output filename is the input filename with the `pdf` extension
+replaced by the `epub` extension. Running without `pip install` also works via
+`python -m epub_pdf_wrap`.
+
+### Options
+
+- `-r <num>, --resolution <num>`: target render width in pixels for the pages
+  in the output file. By default the pages are rendered at the resolution the
+  PDF itself declares.
+- `-c, --crop-global`: trim the white margins around the page content using
+  one common inset for all pages (safe: never clips content on any page, all
+  pages keep the same size).
+- `--crop-page`: trim the white margins around each page's own content, page
+  by page (trims more aggressively but page sizes may vary).
+
+`-c/--crop-global` and `--crop-page` are mutually exclusive; with neither
+flag the margins are left as-is.
+
+## Metadata
+
+Document metadata (title, author, subject, keywords and creation date) is
+taken from the PDF and written into the EPUB. Empty fields are omitted; the
+title falls back to the input filename if the PDF has none.
+
+## Examples
+
+Convert a paper at a wider resolution and name the output explicitly:
+
+```
+epub-pdf-wrap paper.pdf -o paper.epub -r 1400
+```
+
+## Development
+
+```
+python -m venv .venv
+.venv\Scripts\activate        # Windows  (or `source .venv/bin/activate` elsewhere)
+pip install -e ".[dev]"
+pytest
+```
+
+`samples/` contains real input PDFs for manually verifying the output.
+
+## License
+
+Distributed under the BSD 3-Clause License; see `LICENSE`.
+Copyright (c) 2026, Andrea Esuli (andrea@esuli.it).

epub_pdf_wrap-0.1.1/epub_pdf_wrap/__init__.py

@@ -0,0 +1,14 @@
+"""Convert PDFs to EPUBs by rendering each page as an EPUB page."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .core import ConversionError, convert
+
+try:
+    __version__ = version("epub-pdf-wrap")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+__all__ = ["ConversionError", "convert", "__version__"]

epub_pdf_wrap-0.1.1/epub_pdf_wrap/__main__.py

@@ -0,0 +1,77 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .core import ConversionError, convert
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="epub-pdf-wrap",
+        description=(
+            "Convert a PDF into an EPUB by rendering and wrapping each page "
+            "of the PDF in an EPUB page. Aims at PDFs whose layout would be "
+            "corrupted by text-based conversion (comics, scientific papers)."
+        ),
+        epilog="Copyright (c) 2026 Andrea Esuli — BSD-3-Clause license",
+    )
+    parser.add_argument(
+        "-V", "--version", action="version", version=f"epub-pdf-wrap {__version__}",
+    )
+    parser.add_argument("input", help="input PDF file")
+    parser.add_argument(
+        "-o", "--output",
+        help="output EPUB file (default: input filename with .epub extension)",
+    )
+    parser.add_argument(
+        "-r", "--resolution", type=int,
+        help="target render width in pixels for the output (default: input resolution)",
+    )
+    crop = parser.add_mutually_exclusive_group()
+    crop.add_argument(
+        "-c", "--crop-global", action="store_true",
+        help="trim white margins using one common inset for all pages",
+    )
+    crop.add_argument(
+        "--crop-page", action="store_true",
+        help="trim white margins per page, to each page's own content",
+    )
+    return parser
+
+
+def _progress(done: int, total: int) -> None:
+    # Redraw a single-line progress meter over the conversion.
+    bar_width = 30
+    filled = int(bar_width * done / total) if total else bar_width
+    bar = "#" * filled + "-" * (bar_width - filled)
+    sys.stdout.write(f"\rrendering {bar} {done}/{total}")
+    if done != total:
+        sys.stdout.flush()
+    else:
+        sys.stdout.write("\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    crop = "global" if args.crop_global else ("page" if args.crop_page else None)
+    try:
+        out = convert(
+            args.input,
+            args.output,
+            args.resolution,
+            crop=crop,
+            log=lambda line: print(line),
+            progress=_progress,
+        )
+    except ConversionError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

epub_pdf_wrap-0.1.1/epub_pdf_wrap/core.py

@@ -0,0 +1,412 @@
+"""Convert a PDF into an EPUB by rendering each page to an image."""
+
+from __future__ import annotations
+
+import re
+import time
+import uuid
+from io import BytesIO
+from pathlib import Path
+from xml.sax.saxutils import escape
+from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
+
+import pymupdf
+
+
+class ConversionError(RuntimeError):
+    """Raised when the PDF cannot be read or rendered."""
+
+
+def slugify(name: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9]+", "-", name.strip())
+    return slug.strip("-") or "document"
+
+
+# An edge inset counts as a real margin only if it is at least this fraction
+# of the page dimension; anything smaller is treated as a sliver
+# (anti-aliasing, registration marks) and the page is left untrimmed.
+_MARGINS_FRACTION = 0.01
+
+
+def content_bbox(page: "pymupdf.Page"):
+    """Union of the bounding boxes of all content on the page, or None if
+    the page is blank.
+
+    ``get_bboxlog`` returns a list of ``(kind, bbox)`` tuples; the union of
+    those boxes is the extent of the page's content.
+    """
+    log = page.get_bboxlog()
+    if not log:
+        return None
+    bbox = pymupdf.Rect(*log[0][1])
+    for _, b in log[1:]:
+        bbox |= pymupdf.Rect(*b)
+    if not bbox.is_valid or bbox.is_empty or bbox.is_infinite:
+        return None
+    return bbox
+
+
+def margin_insets(bbox: "pymupdf.Rect", rect: "pymupdf.Rect") -> tuple[int, int, int, int]:
+    """Return (left, right, top, bottom) booleans flagging real margins.
+
+    An inset counts as a real margin when it is at least
+    ``_MARGINS_FRACTION`` of the corresponding page dimension.
+    """
+    left = rect.x0 < bbox.x0 - _MARGINS_FRACTION * rect.width
+    right = rect.x1 > bbox.x1 + _MARGINS_FRACTION * rect.width
+    top = rect.y0 < bbox.y0 - _MARGINS_FRACTION * rect.height
+    bottom = rect.y1 > bbox.y1 + _MARGINS_FRACTION * rect.height
+    return (1 if left else 0, 1 if right else 0, 1 if top else 0, 1 if bottom else 0)
+
+
+def page_clip_rect(page: "pymupdf.Page"):
+    """Per-page clip: the content bbox clamped to the page, or the page rect
+    if the page is blank or has no real margins on every side."""
+    rect = page.rect
+    bbox = content_bbox(page)
+    if bbox is None or not any(margin_insets(bbox, rect)):
+        return rect
+    clip = bbox & rect  # intersection, clamps the bbox within the page
+    if clip.is_empty:
+        return rect
+    return clip
+
+
+def global_clip_rects(doc: "pymupdf.Document") -> list["pymupdf.Rect"]:
+    """One common clip rect for every page, safe for all of them.
+
+    For a common clip to never cut into any page's content it must fully
+    contain each page's content region; the union of the per-page content
+    boxes is the smallest box with that property, hence the most aggressive
+    safe common trim (and it yields a uniform size for all pages). Blank
+    pages fall back to their own full rect.
+    """
+    per_page = [(doc.load_page(i), content_bbox(doc.load_page(i)))
+                for i in range(doc.page_count)]
+    nonblank = [bbox for _, bbox in per_page if bbox is not None]
+    if not nonblank:
+        return [page.rect for page, _ in per_page]
+
+    common = pymupdf.Rect(
+        min(b.x0 for b in nonblank),
+        min(b.y0 for b in nonblank),
+        max(b.x1 for b in nonblank),
+        max(b.y1 for b in nonblank),
+    )
+    clips = []
+    for page, bbox in per_page:
+        if bbox is None:
+            clips.append(page.rect)
+            continue
+        clip = common & page.rect  # clamp the common box inside this page
+        clips.append(clip if clip.width > 0 and clip.height > 0 else page.rect)
+    return clips
+
+
+def _clean(value: str) -> str:
+    return " ".join(value.split()) if value else ""
+
+
+def _w3cdtf(value: str) -> str:
+    """Convert a PDF creation date (``D:YYYYMMDDHHmmSSz``) to W3CDTF, or
+    ``""`` if it does not look parseable."""
+    s = value.strip()
+    if not s:
+        return ""
+    if s.startswith("D:"):
+        s = s[2:]
+    digits = s[:14]
+    if len(digits) < 8 or not digits[:8].isdigit():
+        return ""
+    if len(digits) == 8:
+        return f"{digits[0:4]}-{digits[4:6]}-{digits[6:8]}"
+    if len(digits) == 14 and digits[8:14].isdigit():
+        return (
+            f"{digits[0:4]}-{digits[4:6]}-{digits[6:8]}"
+            f"T{digits[8:10]}:{digits[10:12]}:{digits[12:14]}"
+        )
+    return ""
+
+
+def epub_metadata(doc: "pymupdf.Document") -> dict:
+    """Transfer the PDF document metadata into an EPUB-friendly mapping.
+
+    Only non-empty fields are included: ``title``, ``creator`` (from the PDF
+    ``author``), ``subject``, ``keywords`` and ``date`` (from the PDF
+    ``creationDate``, W3CDTF). Tooling fields (creator/producer) are
+    deliberately skipped.
+    """
+    meta = doc.metadata or {}
+    out: dict[str, str] = {}
+    for key, field in (
+        ("title", "title"),
+        ("creator", "author"),
+        ("subject", "subject"),
+        ("keywords", "keywords"),
+    ):
+        if value := _clean(meta.get(field) or ""):
+            out[key] = value
+    for field in ("creationDate", "modDate"):
+        if value := _w3cdtf(meta.get(field) or ""):
+            out["date"] = value
+            break
+    return out
+
+
+def render_page(page: "pymupdf.Page", resolution: int | None = None,
+                clip: "pymupdf.Rect | None" = None) -> bytes:
+    """Render one PDF page to a PNG byte string.
+
+    *resolution*, when given, is the target width in pixels; the height is
+    scaled proportionally. *clip*, when given, is a ``Rect`` in page
+    coordinates to render only that region (e.g. with margins trimmed).
+    """
+    rect = clip if clip is not None else page.rect
+    if resolution is not None:
+        if resolution <= 0:
+            raise ConversionError(f"resolution must be positive, got {resolution}")
+        scale = resolution / rect.width
+    else:
+        scale = 1.0
+    kwargs = {"alpha": True, "colorspace": pymupdf.csRGB}
+    if clip is not None:
+        kwargs["clip"] = clip
+    pix = page.get_pixmap(matrix=pymupdf.Matrix(scale, scale), **kwargs)
+    return pix.tobytes("png")
+
+
+class _EpubWriter:
+    """Minimal EPUB 2 writer: one XHTML section per page, one PNG per page.
+
+    The spine is built from the XHTML sections (never directly from images),
+    which strict readers require.
+    """
+
+    def __init__(self, path: Path, metadata: dict):
+        self.path = Path(path)
+        self.metadata = metadata
+        self.image_names: list[str] = []
+        self.images: list[bytes] = []
+        self.uuid = str(uuid.uuid4())
+        self._tmp = self.path.with_suffix(self.path.suffix + ".tmp")
+
+    def add_image(self, name: str, data: bytes):
+        self.image_names.append(name)
+        self.images.append(data)
+
+    @property
+    def _section_ids(self) -> list[str]:
+        return [f"sec-{i:04d}" for i in range(len(self.image_names))]
+
+    def _container_xml(self) -> str:
+        return (
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            '<container version="1.0" '
+            'xmlns="urn:oasis:names:tc:opendocument:xmlns:container">'
+            "<rootfiles>"
+            '<rootfile full-path="OEBPS/content.opf" '
+            'media-type="application/oebps-package+xml"/>'
+            "</rootfiles></container>"
+        )
+
+    def _metadata_xml(self) -> str:
+        # Order follows the OPF/DC convention; only fields present are emitted.
+        parts = [f'<dc:identifier id="epubid">{self.uuid}</dc:identifier>']
+        if "title" in self.metadata:
+            parts.append(f"<dc:title>{escape(self.metadata['title'])}</dc:title>")
+        if "creator" in self.metadata:
+            parts.append(f"<dc:creator>{escape(self.metadata['creator'])}</dc:creator>")
+        if "subject" in self.metadata:
+            parts.append(f"<dc:subject>{escape(self.metadata['subject'])}</dc:subject>")
+        if "date" in self.metadata:
+            parts.append(f"<dc:date>{escape(self.metadata['date'])}</dc:date>")
+        parts.append("<dc:language>en</dc:language>")
+        if "keywords" in self.metadata:
+            parts.append(
+                f'<meta name="keywords" content="{escape(self.metadata["keywords"])}"/>'
+            )
+        return "".join(parts)
+
+    def _opf_xml(self) -> str:
+        manifest = (
+            '<item id="ncx" media-type="application/x-dtbncx+xml" href="toc.ncx"/>'
+            + "".join(
+                f'<item id="{sid}" media-type="application/xhtml+xml" '
+                f'href="page-{i:04d}.xhtml"/>'
+                for i, sid in enumerate(self._section_ids, start=1)
+            )
+            + "".join(
+                f'<item id="img-{i:04d}" media-type="image/png" '
+                f'href="images/{name}"/>'
+                for i, name in enumerate(self.image_names, start=1)
+            )
+        )
+        spine = "".join(
+            f'<itemref idref="{sid}"/>' for sid in self._section_ids
+        )
+        return (
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            '<package xmlns="http://www.idpf.org/2007/opf" version="2.0">'
+            '<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">'
+            f"{self._metadata_xml()}"
+            "</metadata>"
+            f"<manifest>{manifest}</manifest>"
+            f'<spine toc="ncx">{spine}</spine></package>'
+        )
+
+    def _ncx_xml(self) -> str:
+        nav = "".join(
+            f'<navPoint id="nav-{i:04d}" playOrder="{i}">'
+            f'<navLabel><text>{i}. Page {i}</text></navLabel>'
+            f'<content src="page-{i:04d}.xhtml"/>'
+            "</navPoint>"
+            for i in range(1, len(self.image_names) + 1)
+        )
+        return (
+            '<?xml version="1.0" encoding="UTF-8"?>\n'
+            '<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">'
+            f'<head><meta name="dtb:uid" content="{self.uuid}"/></head>'
+            f"<docTitle><text>{escape(self.metadata.get('title', 'Document'))}</text></docTitle>"
+            f"<navMap>{nav}</navMap></ncx>"
+        )
+
+    def _section_xhtml(self, index: int, name: str) -> str:
+        css = "html,body{margin:0;padding:0;}img{display:block;max-width:100vw;margin:auto;}"
+        return (
+            '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" '
+            '"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\n'
+            '<html xmlns="http://www.w3.org/1999/xhtml" lang="en" '
+            'xmlns:epub="http://www.idpf.org/2007/ops">'
+            f"<head><title>Page {index}</title>"
+            f'<style type="text/css">{css}</style></head>'
+            '<body epub:type="bodymatter">'
+            f'<p style="margin:0;padding:0;border:none;">\u200b</p>'
+            f'<img src="images/{escape(name)}" alt="Page {index}"/>'
+            "</body></html>"
+        )
+
+    def build(self) -> None:
+        assert len(self.image_names) == len(self.images)
+        buf = BytesIO()
+        with ZipFile(buf, "w", ZIP_DEFLATED) as z:
+            z.writestr("mimetype", "application/epub+zip", compress_type=ZIP_STORED)
+            z.writestr("META-INF/container.xml", self._container_xml())
+            z.writestr("OEBPS/content.opf", self._opf_xml())
+            z.writestr("OEBPS/toc.ncx", self._ncx_xml())
+            for i, name in enumerate(self.image_names, start=1):
+                z.writestr(f"OEBPS/page-{i:04d}.xhtml", self._section_xhtml(i, name))
+            for name, data in zip(self.image_names, self.images):
+                z.writestr(f"OEBPS/images/{name}", data)
+
+        self._tmp.write_bytes(buf.getvalue())
+        self._tmp.replace(self.path)
+
+
+def format_size(num_bytes: int) -> str:
+    size = float(num_bytes)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if size < 1024 or unit == "TB":
+            if unit == "B":
+                return f"{int(size)} {unit}"
+            return f"{size:.1f} {unit}"
+        size /= 1024
+
+
+def convert(input_path: Path, output_path: Path | None = None,
+            resolution: int | None = None, crop: str | None = None,
+            log=None, progress=None) -> Path:
+    """Convert *input_path* (a PDF) to an EPUB and return the output path.
+
+    Every PDF page is rendered to a PNG and placed in its own EPUB section in
+    document order. The output file defaults to the input name with the
+    extension swapped to ``.epub``. *resolution*, when given, is the target
+    render width in pixels. *crop*, when given, trims white margins:
+    ``"global"`` uses one common inset for all pages, ``"page"`` trims each
+    page to its own content.
+
+    *log* (optional callable(str)) receives descriptive lines (input info,
+    output result). *progress* (optional callable(done, total)) is called for
+    every rendered page.
+    """
+    if crop is not None and crop not in ("global", "page"):
+        raise ConversionError(f"crop must be 'global' or 'page', got {crop!r}")
+
+    def _log(message: str) -> None:
+        if log is not None:
+            log(message)
+
+    def _progress(done: int, total: int) -> None:
+        if progress is not None:
+            progress(done, total)
+
+    started = time.monotonic()
+
+    input_path = Path(input_path)
+    if not input_path.exists():
+        raise ConversionError(f"input file not found: {input_path}")
+    if output_path is None:
+        output_path = input_path.with_suffix(".epub")
+    output_path = Path(output_path)
+
+    input_size = input_path.stat().st_size
+    _log(f"input:   {input_path}  ({format_size(input_size)})")
+
+    try:
+        doc = pymupdf.open(str(input_path))
+    except Exception as exc:
+        raise ConversionError(f"could not open PDF: {exc}") from exc
+
+    try:
+        page_count = doc.page_count
+        if page_count == 0:
+            raise ConversionError(f"PDF has no pages: {input_path}")
+        metadata = epub_metadata(doc)
+        metadata.setdefault("title", slugify(input_path.stem))
+        pages_list = [doc.load_page(i) for i in range(page_count)]
+
+        first = pages_list[0]
+        w, h = first.rect.width, first.rect.height
+        uniform = all(
+            p.rect.width == w and p.rect.height == h for p in pages_list[1:]
+        )
+        native = f"{w:.0f} x {h:.0f} px" + ("" if uniform else " (varies)")
+        _log(f"pages:   {page_count}  (native resolution: {native})")
+        if crop == "global":
+            clips = global_clip_rects(doc)
+        elif crop == "page":
+            clips = [page_clip_rect(p) for p in pages_list]
+        else:
+            clips = [None] * page_count
+        if resolution is not None:
+            _log(f"output:  {output_path}  ({resolution} px wide)")
+        else:
+            _log(f"output:  {output_path}  (native resolution)")
+        if crop is not None:
+            trimmed = sum(
+                1 for p, c in zip(pages_list, clips) if c is not None and c != p.rect
+            )
+            _log(f"crop:    {crop}  ({trimmed} of {page_count} pages trimmed)")
+
+        rendered: list[tuple[str, bytes]] = []
+        for i, (page, clip_raw) in enumerate(zip(pages_list, clips)):
+            clip = None if (clip_raw is None or clip_raw == page.rect) else clip_raw
+            png = render_page(page, resolution, clip)
+            rendered.append((f"page-{i + 1:04d}.png", png))
+            _progress(i + 1, page_count)
+    finally:
+        doc.close()
+
+    pages = rendered
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    writer = _EpubWriter(output_path, metadata)
+    for name, data in pages:
+        writer.add_image(name, data)
+    writer.build()
+
+    _log(
+        f"wrote:   {output_path}  "
+        f"({format_size(output_path.stat().st_size)}, "
+        f"{page_count} pages, {time.monotonic() - started:.1f}s)"
+    )
+    return output_path

epub_pdf_wrap-0.1.1/epub_pdf_wrap.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: epub-pdf-wrap
+Version: 0.1.1
+Summary: Convert a PDF to an EPUB by wrapping each rendered page in an EPUB page
+Author-email: Andrea Esuli <andrea@esuli.it>
+License-Expression: BSD-3-Clause
+Project-URL: Home, https://github.com/aesuli/epub_pdf_wrap
+Keywords: pdf,epub,conversion,render
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyMuPDF>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ebooklib>=0.18; extra == "dev"
+Dynamic: license-file
+
+# EPUB PDF wrap
+
+Converts a PDF into an EPUB by rendering and wrapping each page of the PDF in
+an EPUB page. This is specifically aimed at PDF files that cannot be converted
+into EPUB any other way without corrupting their visual rendering (comics,
+scientific papers...).
+
+## Installation
+
+```
+pip install epub-pdf-wrap
+```
+
+From source (with dev dependencies for testing):
+
+```
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```
+epub-pdf-wrap <pdf-filename> [-o <epub-filename>]
+```
+
+By default the output filename is the input filename with the `pdf` extension
+replaced by the `epub` extension. Running without `pip install` also works via
+`python -m epub_pdf_wrap`.
+
+### Options
+
+- `-r <num>, --resolution <num>`: target render width in pixels for the pages
+  in the output file. By default the pages are rendered at the resolution the
+  PDF itself declares.
+- `-c, --crop-global`: trim the white margins around the page content using
+  one common inset for all pages (safe: never clips content on any page, all
+  pages keep the same size).
+- `--crop-page`: trim the white margins around each page's own content, page
+  by page (trims more aggressively but page sizes may vary).
+
+`-c/--crop-global` and `--crop-page` are mutually exclusive; with neither
+flag the margins are left as-is.
+
+## Metadata
+
+Document metadata (title, author, subject, keywords and creation date) is
+taken from the PDF and written into the EPUB. Empty fields are omitted; the
+title falls back to the input filename if the PDF has none.
+
+## Examples
+
+Convert a paper at a wider resolution and name the output explicitly:
+
+```
+epub-pdf-wrap paper.pdf -o paper.epub -r 1400
+```
+
+## Development
+
+```
+python -m venv .venv
+.venv\Scripts\activate        # Windows  (or `source .venv/bin/activate` elsewhere)
+pip install -e ".[dev]"
+pytest
+```
+
+`samples/` contains real input PDFs for manually verifying the output.
+
+## License
+
+Distributed under the BSD 3-Clause License; see `LICENSE`.
+Copyright (c) 2026, Andrea Esuli (andrea@esuli.it).

epub_pdf_wrap-0.1.1/epub_pdf_wrap.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+epub_pdf_wrap/__init__.py
+epub_pdf_wrap/__main__.py
+epub_pdf_wrap/core.py
+epub_pdf_wrap.egg-info/PKG-INFO
+epub_pdf_wrap.egg-info/SOURCES.txt
+epub_pdf_wrap.egg-info/dependency_links.txt
+epub_pdf_wrap.egg-info/entry_points.txt
+epub_pdf_wrap.egg-info/requires.txt
+epub_pdf_wrap.egg-info/top_level.txt
+tests/test_core.py

epub_pdf_wrap-0.1.1/epub_pdf_wrap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

epub_pdf_wrap-0.1.1/epub_pdf_wrap.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+epub-pdf-wrap = epub_pdf_wrap.__main__:main

epub_pdf_wrap-0.1.1/epub_pdf_wrap.egg-info/requires.txt

@@ -0,0 +1,5 @@
+PyMuPDF>=1.24
+
+[dev]
+pytest>=7
+ebooklib>=0.18

epub_pdf_wrap-0.1.1/epub_pdf_wrap.egg-info/top_level.txt

@@ -0,0 +1 @@
+epub_pdf_wrap

epub_pdf_wrap-0.1.1/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "epub-pdf-wrap"
+version = "0.1.1"
+description = "Convert a PDF to an EPUB by wrapping each rendered page in an EPUB page"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Andrea Esuli", email = "andrea@esuli.it" },
+]
+urls = { "Home" = "https://github.com/aesuli/epub_pdf_wrap" }
+keywords = ["pdf", "epub", "conversion", "render"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Text Processing :: Markup :: HTML",
+]
+dependencies = [
+    "PyMuPDF>=1.24",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "ebooklib>=0.18",
+]
+
+[project.scripts]
+epub-pdf-wrap = "epub_pdf_wrap.__main__:main"
+
+[tool.setuptools]
+packages = ["epub_pdf_wrap"]

epub_pdf_wrap-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

epub_pdf_wrap-0.1.1/tests/test_core.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pymupdf
+import pytest
+
+from epub_pdf_wrap.core import ConversionError, convert, format_size, page_clip_rect, render_page, slugify
+
+
+@pytest.fixture
+def tiny_pdf(tmp_path: Path) -> Path:
+    """Three-page PDF: text page, white-blank page is omitted; use text + image pages."""
+    doc = pymupdf.open()
+    page = doc.new_page(width=200, height=260)
+    page.insert_text((20, 40), "First page")
+    page = doc.new_page(width=200, height=260)
+    page.insert_text((20, 40), "Second page")
+    out = tmp_path / "tiny.pdf"
+    doc.save(str(out))
+    doc.close()
+    return out
+
+
+def test_convert_produces_epub(tmp_path: Path, tiny_pdf: Path) -> None:
+    out = convert(tiny_pdf, tmp_path / "out.epub")
+    assert out.exists()
+    import zipfile
+
+    with zipfile.ZipFile(out) as z:
+        names = z.namelist()
+        assert names[0] == "mimetype"
+        assert z.read("mimetype") == b"application/epub+zip"
+        assert "OEBPS/images/page-0001.png" in names
+        assert "OEBPS/images/page-0002.png" in names
+
+
+def test_epub_is_readable_by_ebooklib(tmp_path: Path, tiny_pdf: Path) -> None:
+    """Reader-grade check: ebooklib must parse metadata, spine and content."""
+    import ebooklib
+    from ebooklib import epub
+
+    out = convert(tiny_pdf, tmp_path / "reader.epub")
+    book = epub.read_epub(str(out), options={"ignore_ncx": True})
+
+    # Metadata
+    titles = book.get_metadata("DC", "title")
+    assert titles and titles[0][0] == "tiny"
+
+    # Spine (reading order) must resolve to real items
+    spine_refs = [ref for ref, _ in book.spine]
+    assert spine_refs == ["sec-0000", "sec-0001"]
+    for ref in spine_refs:
+        item = book.get_item_with_id(ref)
+        assert item is not None
+        assert "<img" in item.get_content().decode("utf-8")
+
+    # Every spine image must be present
+    images = {i.get_name() for i in book.get_items_of_type(ebooklib.ITEM_IMAGE)}
+    assert images == {"images/page-0001.png", "images/page-0002.png"}
+
+    # A default load must also succeed without the ignore_ncx bypass:
+    # the NCX toc id has to resolve in the manifest (id="ncx").
+    fresh = epub.read_epub(str(out))
+    assert len(list(fresh.get_items_of_type(ebooklib.ITEM_DOCUMENT))) == 2
+    # Navigation must provide one TOC entry per page, each resolving to a
+    # real item (this is what readers do when a user opens the TOC).
+    toc = list(fresh.toc)
+    assert len(toc) == 2
+    for link in toc:
+        item = fresh.get_item_with_href(link.href)
+        assert item is not None
+        assert "<img" in item.get_content().decode("utf-8")
+
+
+def test_convert_default_output_name(tiny_pdf: Path) -> None:
+    out = convert(tiny_pdf)
+    assert out.name == "tiny.epub"
+    out.unlink()
+
+
+def test_resolution_flag(tmp_path: Path, tiny_pdf: Path) -> None:
+    out = convert(tiny_pdf, tmp_path / "res.epub", resolution=600)
+    import zipfile
+
+    with zipfile.ZipFile(out) as z:
+        png = z.read("OEBPS/images/page-0001.png")
+    import struct
+
+    # IHDR: width at bytes 16..20
+    width = struct.unpack(">I", png[16:20])[0]
+    assert width == 600
+
+
+def test_blank_only_pdf_still_produces_epub(tmp_path: Path) -> None:
+    doc = pymupdf.open()
+    doc.new_page(width=200, height=260)
+    blank = tmp_path / "blank.pdf"
+    doc.save(str(blank))
+    doc.close()
+
+    out = convert(blank, tmp_path / "blank.epub")
+    assert out.exists()
+    import zipfile
+
+    with zipfile.ZipFile(out) as z:
+        assert "OEBPS/images/page-0001.png" in z.namelist()
+    out.unlink()
+    blank.unlink()
+
+
+def test_missing_input_raises(tmp_path: Path) -> None:
+    with pytest.raises(ConversionError):
+        convert(tmp_path / "nope.pdf", tmp_path / "nope.epub")
+
+
+def test_bad_resolution_raises(tiny_pdf: Path) -> None:
+    doc = pymupdf.open(str(tiny_pdf))
+    page = doc.load_page(0)
+    try:
+        with pytest.raises(ConversionError):
+            render_page(page, resolution=0)
+        with pytest.raises(ConversionError):
+            render_page(page, resolution=-5)
+    finally:
+        doc.close()
+
+
+def test_convert_reports_input_info_and_progress(tmp_path: Path, tiny_pdf: Path) -> None:
+    logged: list[str] = []
+    steps: list[tuple[int, int]] = []
+    out = convert(
+        tiny_pdf,
+        tmp_path / "report.epub",
+        log=logged.append,
+        progress=lambda done, total: steps.append((done, total)),
+    )
+    joined = "\n".join(logged)
+    assert str(tiny_pdf) in joined
+    assert "pages:   2" in joined
+    assert str(out) in joined
+    assert "2 pages" in joined
+    assert steps[-1] == (2, 2)
+    assert len(steps) == 2
+
+
+def test_slugify() -> None:
+    assert slugify("Some Comic 42") == "Some-Comic-42"
+    assert slugify("2406.12128v2") == "2406-12128v2"
+    assert slugify("   ") == "document"
+
+
+def test_format_size() -> None:
+    assert format_size(0) == "0 B"
+    assert format_size(999) == "999 B"
+    assert format_size(1024) == "1.0 KB"
+    assert format_size(2048) == "2.0 KB"
+    assert format_size(1536) == "1.5 KB"
+    assert format_size(1536 * 1024) == "1.5 MB"
+
+
+def _png_size(png: bytes) -> tuple[int, int]:
+    import struct
+
+    return struct.unpack(">II", png[16:24])
+
+
+@pytest.fixture
+def inset_pdf(tmp_path: Path) -> Path:
+    """Two pages with content inset in the middle (real margins around it).
+
+    Page 1: content from (50, 50) to (150, 210).
+    Page 2: content from (30, 30) to (170, 230) — wider than page 1, so the
+    global (union) clip keeps the wider extent on that side.
+    """
+    doc = pymupdf.open()
+    p = doc.new_page(width=200, height=260)
+    p.insert_text((50, 80), "page one")
+    p.draw_rect(pymupdf.Rect(50, 100, 150, 200))
+    p = doc.new_page(width=200, height=260)
+    p.insert_text((30, 60), "page two")
+    p.draw_rect(pymupdf.Rect(30, 80, 170, 220))
+    out = tmp_path / "inset.pdf"
+    doc.save(str(out))
+    doc.close()
+    return out
+
+
+def test_crop_page_trims_to_content(tmp_path: Path, inset_pdf: Path) -> None:
+    out = convert(inset_pdf, tmp_path / "crop.epub", crop="page")
+
+    # Compare against the no-crop render of the same PDF
+    nocrop = convert(inset_pdf, tmp_path / "nocrop.epub")
+    import zipfile
+
+    with zipfile.ZipFile(out) as z:
+        cropped = _png_size(z.read("OEBPS/images/page-0001.png"))
+    with zipfile.ZipFile(nocrop) as z:
+        full = _png_size(z.read("OEBPS/images/page-0001.png"))
+    assert full == (200, 260)
+    # Page 1 content spans roughly 50..150 wide, 70..200 tall: the crop must
+    # clearly remove margins on all four sides.
+    assert cropped[0] < full[0] * 0.7
+    assert cropped[1] < full[1] * 0.7
+
+
+def test_crop_global_uniform_but_safe(tmp_path: Path, inset_pdf: Path) -> None:
+    out = convert(inset_pdf, tmp_path / "g.epub", crop="global")
+    import zipfile
+
+    with zipfile.ZipFile(out) as z:
+        s1 = _png_size(z.read("OEBPS/images/page-0001.png"))
+        s2 = _png_size(z.read("OEBPS/images/page-0002.png"))
+    # Union of content boxes is the same size for both pages (each clipped
+    # to the same global box), so both page images have equal dimensions.
+    assert s1 == s2
+    # The global box must never clip content: page 2, which extends
+    # furthest (30..170 wide), must not have been cut.
+    assert s1[0] >= 170 - 30
+
+
+def test_full_bleed_crop_unchanged(tmp_path: Path) -> None:
+    doc = pymupdf.open()
+    p = doc.new_page(width=200, height=260)
+    p.draw_rect(pymupdf.Rect(0, 0, 200, 260))  # content touches all edges
+    full = tmp_path / "full.pdf"
+    doc.save(str(full))
+    doc.close()
+
+    a = convert(full, tmp_path / "a.epub")
+    b = convert(full, tmp_path / "b.epub", crop="global")
+    c = convert(full, tmp_path / "c.epub", crop="page")
+    import zipfile
+
+    with zipfile.ZipFile(a) as z:
+        base = z.read("OEBPS/images/page-0001.png")
+    with zipfile.ZipFile(b) as z:
+        assert z.read("OEBPS/images/page-0001.png") == base
+    with zipfile.ZipFile(c) as z:
+        assert z.read("OEBPS/images/page-0001.png") == base
+    full.unlink()
+
+
+def test_blank_page_crop_does_not_crash(tmp_path: Path) -> None:
+    doc = pymupdf.open()
+    doc.new_page(width=200, height=260)
+    blank = tmp_path / "blank.pdf"
+    doc.save(str(blank))
+    doc.close()
+
+    a = convert(blank, tmp_path / "gb.epub", crop="global")
+    b = convert(blank, tmp_path / "pb.epub", crop="page")
+    import zipfile
+
+    for f in (a, b):
+        with zipfile.ZipFile(f) as z:
+            assert _png_size(z.read("OEBPS/images/page-0001.png")) == (200, 260)
+    blank.unlink()
+
+
+def test_crop_invalid_value_raises(inset_pdf: Path) -> None:
+    with pytest.raises(ConversionError):
+        convert(inset_pdf, inset_pdf.with_suffix(".epub"), crop="bogus")
+
+
+def test_cli_parser_crop_flags() -> None:
+    from epub_pdf_wrap.__main__ import build_parser
+
+    p = build_parser()
+    args = p.parse_args(["in.pdf", "-c"])
+    assert args.crop_global is True and args.crop_page is False
+    args = p.parse_args(["in.pdf", "--crop-global"])
+    assert args.crop_global is True
+    args = p.parse_args(["in.pdf", "--crop-page"])
+    assert args.crop_global is False and args.crop_page is True
+    with pytest.raises(SystemExit) as exc:
+        p.parse_args(["in.pdf", "-c", "--crop-page"])
+    assert exc.value.code == 2
+
+
+@pytest.fixture
+def metadata_pdf(tmp_path: Path) -> Path:
+    doc = pymupdf.open()
+    page = doc.new_page(width=200, height=260)
+    page.insert_text((20, 40), "content")
+    doc.set_metadata(
+        {
+            "title": "A <Great> Book & Co",
+            "author": "Jane Doe, John Roe",
+            "subject": "Typesetting with pypdf",
+            "keywords": "epub, pdf, wrap",
+            "creationDate": "D:20041212120000+01'00'",
+        }
+    )
+    out = tmp_path / "meta.pdf"
+    doc.save(str(out))
+    doc.close()
+    return out
+
+
+def test_metadata_is_transferred_to_epub(tmp_path: Path, metadata_pdf: Path) -> None:
+    import ebooklib
+    from ebooklib import epub
+
+    out = convert(metadata_pdf, tmp_path / "meta.epub")
+    book = epub.read_epub(str(out), options={"ignore_ncx": True})
+
+    assert book.get_metadata("DC", "title")[0][0] == "A <Great> Book & Co"
+    assert book.get_metadata("DC", "creator")[0][0] == "Jane Doe, John Roe"
+    assert book.get_metadata("DC", "subject")[0][0] == "Typesetting with pypdf"
+    assert book.get_metadata("DC", "date")[0][0] == "2004-12-12T12:00:00"
+    # Tooling fields are not transferred
+    assert not book.get_metadata("DC", "source")
+
+    # The OPF XML itself: identifier still present, values escaped in title,
+    # keywords present as an EPUB-3 meta element.
+    from zipfile import ZipFile
+
+    with ZipFile(out) as z:
+        opf = z.read("OEBPS/content.opf").decode("utf-8")
+    assert "A &lt;Great&gt; Book &amp; Co" in opf
+    assert '<dc:identifier id="epubid"' in opf
+    assert '<meta name="keywords" content="epub, pdf, wrap"/>' in opf
+
+
+def test_metadata_fallback_title_when_empty(tmp_path: Path) -> None:
+    import pymupdf
+
+    doc = pymupdf.open()
+    doc.new_page(width=200, height=260)
+    blank = tmp_path / "no-meta.pdf"
+    doc.save(str(blank))
+    doc.close()
+
+    out = convert(blank, tmp_path / "no-meta.epub")
+    import zipfile
+
+    with zipfile.ZipFile(out) as z:
+        opf = z.read("OEBPS/content.opf").decode("utf-8")
+    assert "<dc:title>no-meta</dc:title>" in opf
+    # Only empty fields are omitted, not the required title
+    assert "<dc:creator>" not in opf
+    assert "<dc:subject>" not in opf
+    assert "<dc:date>" not in opf
+    blank.unlink()