mcruft 0.1.1__py3-none-any.whl

mcruft/__init__.py

@@ -0,0 +1,80 @@
+# this_file: packages/mcruft/src/mcruft/__init__.py
+from pathlib import Path
+
+from .engines.base import Capability, Engine, EngineInfo
+from .engines.registry import engines
+from .model import Asset, Document, Frame, Media, Page, merge
+from .ops import convert
+from .package import load, refresh, save
+from .report import (
+    EngineFailed,
+    EngineUnavailable,
+    Loss,
+    McruftError,
+    PackageError,
+    Policy,
+    Report,
+    UnsupportedRoute,
+    UnsupportedSchema,
+)
+
+try:
+    from .__version__ import __version__ as __version__
+except ImportError:
+    from importlib.metadata import version
+
+    __version__ = version("mcruft")
+
+__all__ = [
+    "Asset",
+    "Capability",
+    "Document",
+    "Engine",
+    "EngineFailed",
+    "EngineInfo",
+    "EngineUnavailable",
+    "Frame",
+    "Loss",
+    "McruftError",
+    "Media",
+    "PackageError",
+    "Page",
+    "Policy",
+    "Report",
+    "UnsupportedRoute",
+    "UnsupportedSchema",
+    "__version__",
+    "convert",
+    "convert_editable",
+    "convert_fidelity",
+    "engines",
+    "load",
+    "merge",
+    "new",
+    "open",
+    "refresh",
+    "save",
+]
+
+
+def new(title: str = "") -> Document:
+    doc = Document()
+    doc.meta["title"] = title
+    return doc
+
+
+def open(path: Path | str) -> Document:
+    path = Path(path)
+    if path.is_dir():
+        return load(path)
+    doc = new(path.stem)
+    doc.add_file(path)
+    return doc
+
+
+def convert_editable(src: Path | str, dst: Path | str) -> Report:
+    return convert(src, dst, policy="editable")
+
+
+def convert_fidelity(src: Path | str, dst: Path | str) -> Report:
+    return convert(src, dst, policy="fidelity")

mcruft/__version__.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None

mcruft/editing.py

@@ -0,0 +1,145 @@
+# this_file: packages/mcruft/src/mcruft/editing.py
+"""Page edit transactions and optional PDF previews."""
+
+import mimetypes
+import os
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+from .engines.base import normalize_format
+from .engines.registry import inspect_file
+from .model import Asset, Document, Page, identifier
+from .ops import convert, export, owner
+from .package import digest, member
+from .page_ops import joined, run
+from .report import Report, UnsupportedRoute
+
+
+def previews(doc: Document, root: Path) -> Report:
+    reports = []
+    pending = []
+    with tempfile.TemporaryDirectory(dir=root) as directory:
+        for n, page in enumerate(doc.pages):
+            previous = doc.assets.get(page.preview)
+            source = doc.assets[page.source["asset"]]
+            path = member(root, f"previews/page-{n:04d}.pdf")
+            valid = (
+                previous
+                and previous.role == "preview"
+                and previous.derived_from == source.id
+                and previous.path.is_file()
+                and digest(previous.path) == previous.sha256
+                and digest(source.path) == source.sha256
+            )
+            if valid and previous.path == path:
+                continue
+            staged = Path(directory) / path.name
+            if valid:
+                shutil.copyfile(previous.path, staged)
+                via = previous.via
+            else:
+                report = export(doc, staged, policy="editable", pages=[n], fonts="embed")
+                reports.append(report)
+                via = {
+                    "engine": report.engine,
+                    "engine_version": report.engine_version,
+                    "op": "export_pages",
+                    "policy": "editable",
+                }
+            asset = Asset(
+                identifier(), path, "application/pdf", digest(staged), "preview", source.id, via
+            )
+            doc.assets[asset.id] = asset
+            page.preview = asset.id
+            pending.append((staged, path))
+        # Stage every page before replacing paths: reordering must not overwrite another preview.
+        for staged, path in pending:
+            member(root, "previews").mkdir(parents=True, exist_ok=True)
+            os.replace(staged, path)
+    referenced = {page.preview for page in doc.pages}
+    doc.assets = {
+        key: a for key, a in doc.assets.items() if a.role != "preview" or key in referenced
+    }
+    return joined("save", None, reports, [])
+
+
+@contextmanager
+def edit_in(page: Page, engine: str):
+    """Register changed edits before inspection; inspection errors retain the old size and propagate.
+
+    A failed body leaves the document unchanged but preserves a changed working file.
+    """
+    native = {
+        "photocraft": {"png", "jpg", "psd", "pcraft"},
+        "vectorcraft": {"svg", "ai", "vectorcraft", "pdf"},
+        "deckcraft": {"pptx", "deckcraft"},
+        "pdfcraft": {"pdf"},
+        "designcraft": {"idml", "designcraft"},
+    }
+    formats = {
+        "photocraft": "psd",
+        "vectorcraft": "vectorcraft",
+        "deckcraft": "pptx",
+        "pdfcraft": "pdf",
+        "designcraft": "designcraft",
+    }
+    if engine not in formats:
+        raise UnsupportedRoute(f"Unknown edit engine: {engine}")
+    doc = owner(page)
+    source = doc.assets[page.source["asset"]]
+    fmt = normalize_format(source.path.suffix[1:])
+    copied = fmt in native[engine]
+    index = page.source["index"] if copied else 0
+    folder = (
+        member(doc.path, "derived") if doc.path else Path(tempfile.mkdtemp(prefix="mcruft-edit-"))
+    )
+    folder.mkdir(parents=True, exist_ok=True)
+    suffix = source.path.suffix if copied else f".{formats[engine]}"
+    path = folder / f"{identifier()}{suffix}"
+    retained = False
+    try:
+        if copied:
+            shutil.copyfile(source.path, path)
+        elif formats[engine] == "pdf":
+            with tempfile.TemporaryDirectory(dir=folder) as directory:
+                whole = Path(directory) / "converted.pdf"
+                convert(source.path, whole, policy="editable")
+                run(
+                    "extract_pages",
+                    whole,
+                    path,
+                    "editable",
+                    pages=[page.source["index"]],
+                )
+        else:
+            if len(inspect_file(source.path)) != 1:
+                raise UnsupportedRoute(f"No single-page editable route: {fmt} -> {formats[engine]}")
+            convert(source.path, path, policy="editable")
+        before = digest(path)
+        try:
+            yield path
+        finally:
+            retained = True
+            after = digest(path)
+            retained = after != before
+        if retained:
+            asset = Asset(
+                identifier(),
+                path,
+                mimetypes.guess_type(path)[0] or "application/octet-stream",
+                after,
+                "derived",
+                page.source["asset"],
+                {"engine": engine, "op": "edit_in"},
+            )
+            doc.assets[asset.id] = asset
+            page.source = {"asset": asset.id, "index": index}
+            page.preview = None
+            page.size = inspect_file(path)[index]
+    finally:
+        if not retained:
+            path.unlink(missing_ok=True)
+            if doc.path is None:
+                folder.rmdir()

mcruft/engines/__init__.py

@@ -0,0 +1 @@
+# this_file: packages/mcruft/src/mcruft/engines/__init__.py

mcruft/engines/base.py

@@ -0,0 +1,49 @@
+# this_file: packages/mcruft/src/mcruft/engines/base.py
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from ..report import Policy, Report, UnsupportedRoute
+
+
+def normalize_format(fmt: str) -> str:
+    return {"jpeg": "jpg", "tif": "tiff"}.get(fmt.lower(), fmt.lower())
+
+
+@dataclass(frozen=True)
+class Capability:
+    op: str
+    src: str
+    dst: str
+    policy: Policy
+    verified_with: str | None = None
+    note: str = ""
+
+
+class Engine:
+    name: str
+    kind: Literal["cli", "mcp", "native", "lib"]
+
+    def available(self) -> bool:
+        return False
+
+    def version(self) -> str | None:
+        return None
+
+    def capabilities(self) -> list[Capability]:
+        return []
+
+    def run(self, op: str, src: Path, dst: Path, *, policy: Policy, **opts) -> Report:
+        raise UnsupportedRoute(f"{self.name}: {op} {policy}")
+
+    def inspect(self, path: Path) -> list[tuple[float, float]]:
+        raise UnsupportedRoute(f"{self.name}: cannot inspect {path.suffix}")
+
+
+@dataclass
+class EngineInfo:
+    name: str
+    kind: str
+    available: bool
+    version: str | None
+    capabilities: list[Capability]

mcruft/engines/cli.py

@@ -0,0 +1,140 @@
+# this_file: packages/mcruft/src/mcruft/engines/cli.py
+import importlib
+import json
+import math
+import os
+import re
+import shlex
+import shutil
+import subprocess
+from pathlib import Path
+
+from ..report import EngineFailed, EngineUnavailable, Policy, Report, UnsupportedRoute
+from .base import Engine, normalize_format
+
+
+def run_cli(argv: list[str | Path], timeout: float = 600) -> subprocess.CompletedProcess:
+    args = [str(arg.absolute()) if isinstance(arg, Path) else arg for arg in argv]
+    try:
+        return subprocess.run(args, capture_output=True, text=True, timeout=timeout, check=True)
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, OSError) as exc:
+        tail = getattr(exc, "stderr", "") or str(exc)
+        if isinstance(tail, bytes):
+            tail = tail.decode(errors="replace")
+        raise EngineFailed(f"{shlex.join(args)}\n{tail[-4000:]}") from exc
+
+
+def parse_version(text: str) -> str:
+    match = re.search(r"\b\d+\.\d+\.\d+(?:[a-zA-Z0-9.+-]*)?", text)
+    if match is None:
+        raise EngineFailed(f"No version number in CLI output: {text[:200]}")
+    return match[0]
+
+
+def page_indexes(pages: list[int] | None, count: int) -> list[int]:
+    indexes = list(range(count)) if pages is None else list(pages)
+    if not indexes:
+        raise ValueError("Select at least one page")
+    if any(type(i) is not int or i < 0 or i >= count for i in indexes):
+        raise IndexError(f"Page indexes must be integers in 0..{count - 1}")
+    return indexes
+
+
+def pixel_scale(dpi: float) -> float:
+    if not math.isfinite(dpi) or dpi <= 0:
+        raise ValueError("DPI must be finite and positive")
+    return dpi / 72
+
+
+def json_warnings(value) -> list[str]:
+    if isinstance(value, list):
+        return [warning for item in value for warning in json_warnings(item)]
+    if not isinstance(value, dict):
+        return []
+    return [
+        warning
+        for key, item in value.items()
+        for warning in (
+            item
+            if key in ("warnings", "importWarnings") and isinstance(item, list)
+            else json_warnings(item)
+        )
+    ]
+
+
+class CliEngine(Engine):
+    PRODUCT: str
+    MIN_VERSION = "0.0.0"
+    kind = "cli"
+
+    @property
+    def name(self) -> str:
+        return self.PRODUCT
+
+    def binary(self) -> Path | None:
+        override = os.environ.get(f"MCRUFT_{self.PRODUCT.upper()}_CLI")
+        if override:
+            path = Path(override).expanduser().absolute()
+        else:
+            package = f"mcruft_{self.PRODUCT}_bin"
+            try:
+                path = Path(importlib.import_module(package).BIN).absolute()
+            except ModuleNotFoundError as exc:
+                if exc.name != package:
+                    raise
+                found = shutil.which(f"{self.PRODUCT}-cli")
+                path = Path(found).absolute() if found else None
+        return path if path and path.is_file() and os.access(path, os.X_OK) else None
+
+    def available(self) -> bool:
+        return self.binary() is not None
+
+    def version(self) -> str | None:
+        binary = self.binary()
+        return parse_version(run_cli([binary, "--version"]).stdout) if binary else None
+
+    def report(self, op: str, policy: Policy, outputs: list[Path] | None = None) -> Report:
+        current = self.version()
+        report = Report(op, policy, self.name, current, outputs or [])
+        if current and tuple(map(int, re.match(r"\d+\.\d+\.\d+", current)[0].split("."))) < tuple(
+            map(int, self.MIN_VERSION.split("."))
+        ):
+            report.warnings.append(f"{self.name} {current} is older than {self.MIN_VERSION}")
+        return report
+
+    def check_route(self, op: str, src: Path, dst: Path, policy: Policy) -> None:
+        if op == "inspect" or not any(
+            (c.op, normalize_format(c.src), normalize_format(c.dst), c.policy)
+            == (op, normalize_format(src.suffix[1:]), normalize_format(dst.suffix[1:]), policy)
+            for c in self.capabilities()
+        ):
+            raise UnsupportedRoute(f"{self.name}: {op} {src.suffix} -> {dst.suffix} ({policy})")
+
+    def call(self, args: list[str | Path], report: Report | None = None) -> str:
+        binary = self.binary()
+        if binary is None:
+            raise EngineUnavailable(f"Missing {self.PRODUCT}-cli")
+        result = run_cli([binary, *args])
+        if report is not None:
+            for line in result.stdout.splitlines():
+                try:
+                    report.warnings.extend(json_warnings(json.loads(line)))
+                except json.JSONDecodeError:
+                    pass  # Some CLIs print human-readable progress instead of JSON.
+            report.warnings.extend(
+                line.removeprefix("warning: ")
+                for line in result.stderr.splitlines()
+                if line.startswith("warning: ")
+            )
+        return result.stdout
+
+    def run(self, op: str, src: Path, dst: Path, *, policy: Policy, **opts) -> Report:
+        raise UnsupportedRoute("implemented in Task 6")
+
+    async def session(self, read_root: Path, write_root: Path, extra_args: list[str] | None = None):
+        from ..mcp import McpSession
+
+        binary = self.binary()
+        if binary is None:
+            raise EngineUnavailable(f"Missing {self.PRODUCT}-cli")
+        return await McpSession().open(binary, read_root, write_root, extra_args)

mcruft/engines/lib.py

@@ -0,0 +1,166 @@
+# this_file: packages/mcruft/src/mcruft/engines/lib.py
+import math
+import re
+import xml.etree.ElementTree as ET
+from importlib.metadata import version
+from pathlib import Path
+
+from PIL import Image
+from pptx import Presentation
+from pypdf import PdfReader, PdfWriter
+
+from ..report import EngineFailed, Loss, Policy, Report, UnsupportedRoute
+from . import libs_pdfium, libs_psd, libs_resvg
+from .base import Capability, Engine, normalize_format
+from .cli import page_indexes, pixel_scale
+
+
+def svg_size(path: Path) -> tuple[float, float]:
+    root = ET.parse(path).getroot()
+    dimensions = [root.get(axis, "").strip() for axis in ("width", "height")]
+    if "viewBox" in root.attrib and any(not value or value.endswith("%") for value in dimensions):
+        values = [float(v) for v in re.split(r"[\s,]+", root.attrib["viewBox"].strip())]
+        if len(values) != 4:
+            raise UnsupportedRoute("SVG viewBox must have four numbers")
+        size = values[2] * 0.75, values[3] * 0.75
+    else:
+        units = {"": 0.75, "px": 0.75, "pt": 1, "mm": 72 / 25.4, "cm": 72 / 2.54, "in": 72}
+        size = []
+        for axis in ("width", "height"):
+            match = re.fullmatch(
+                r"\s*(\d*\.?\d+(?:[eE][+-]?\d+)?)\s*(px|pt|mm|cm|in)?\s*", root.get(axis, "")
+            )
+            if match is None:
+                raise UnsupportedRoute("SVG requires viewBox or absolute width/height")
+            size.append(float(match[1]) * units[match[2] or ""])
+    if not all(math.isfinite(v) and v > 0 for v in size):
+        raise UnsupportedRoute("Page dimensions must be finite and positive")
+    return tuple(size)
+
+
+class LibEngine(Engine):
+    name, kind = "lib", "lib"
+
+    def available(self) -> bool:
+        return True
+
+    def version(self) -> str:
+        return version("pypdf")
+
+    def capabilities(self) -> list[Capability]:
+        inspect = [
+            Capability("inspect", fmt, fmt, policy, "lib " + library)
+            for fmt, library in [
+                ("pdf", "pypdf"),
+                ("pptx", "python-pptx"),
+                ("svg", "XML"),
+                ("png", "Pillow"),
+                ("jpg", "Pillow"),
+                ("jpeg", "Pillow"),
+            ]
+            for policy in ("editable", "fidelity")
+        ]
+        raster = [
+            Capability("export_pages", fmt, "png", "fidelity", "lib Pillow")
+            for fmt in ("png", "jpg", "jpeg")
+        ]
+        return (
+            inspect
+            + raster
+            + libs_pdfium.capabilities()
+            + libs_resvg.capabilities()
+            + libs_psd.capabilities()
+            + [
+                Capability(op, "pdf", "pdf", policy, "lib pypdf")
+                for op in ("extract_pages", "combine")
+                for policy in ("editable", "fidelity")
+            ]
+        )
+
+    def inspect(self, path: Path) -> list[tuple[float, float]]:
+        path = Path(path)
+        match path.suffix.lower():
+            case ".pdf":
+                sizes = []
+                for page in PdfReader(path).pages:
+                    size = float(page.mediabox.width), float(page.mediabox.height)
+                    sizes.append(size[::-1] if page.rotation % 180 else size)
+                return sizes
+            case ".pptx":
+                prs = Presentation(str(path))
+                return [(prs.slide_width / 12700, prs.slide_height / 12700)] * len(prs.slides)
+            case ".svg":
+                return [svg_size(path)]
+            case ".psd" if libs_psd.capabilities():
+                return libs_psd.inspect(path)
+            case ".png" | ".jpg" | ".jpeg":
+                with Image.open(path) as image:
+                    dpi = image.info.get("dpi", (72, 72))
+                    if any(d <= 0 for d in dpi):
+                        raise UnsupportedRoute("Image DPI must be positive")
+                    return [(image.width * 72 / dpi[0], image.height * 72 / dpi[1])]
+            case _:
+                return super().inspect(path)
+
+    def run(self, op: str, src: Path, dst: Path, *, policy: Policy, **opts) -> Report:
+        if (
+            not any(
+                (c.op, normalize_format(c.src), normalize_format(c.dst), c.policy)
+                == (
+                    op,
+                    normalize_format(Path(src).suffix[1:]),
+                    normalize_format(Path(dst).suffix[1:]),
+                    policy,
+                )
+                for c in self.capabilities()
+            )
+            or op == "inspect"
+        ):
+            raise UnsupportedRoute(f"lib: {op} ({policy})")
+        if Path(src).suffix.lower() == ".svg":
+            return libs_resvg.render(op, src, dst, policy, **opts)
+        if op == "export_pages" and Path(src).suffix.lower() == ".pdf":
+            return libs_pdfium.export_pages(src, dst, policy, **opts)
+        if op == "export_pages":
+            return self.render_image(src, dst, policy, **opts)
+        writer = PdfWriter()
+        try:
+            if op == "extract_pages":
+                reader = PdfReader(src)
+                indexes = opts["pages"]
+                if any(i < 0 or i >= len(reader.pages) for i in indexes):
+                    raise IndexError("PDF page index out of range")
+                for index in indexes:
+                    writer.add_page(reader.pages[index])
+            else:
+                for path in opts.get("paths", [src]):
+                    writer.append(path)
+            writer.write(dst)
+        except OSError as exc:
+            raise EngineFailed(f"lib {op}: {exc}") from exc
+        finally:
+            writer.close()
+        return Report(op, policy, self.name, self.version(), [Path(dst)])
+
+    def render_image(self, src: Path, dst: Path, policy: Policy, **opts) -> Report:
+        pages = page_indexes(opts.get("pages"), 1)
+        dpi = opts.get("dpi", 150)
+        scale = pixel_scale(dpi)
+        size = tuple(max(1, round(v * scale)) for v in self.inspect(src)[0])
+        outputs = []
+        losses = []
+        try:
+            with Image.open(src) as image:
+                if image.info.get("icc_profile"):
+                    losses.append(Loss("effects", "ICC profile not kept"))
+                rendered = image.convert("RGBA").resize(size, Image.Resampling.LANCZOS)
+                for page in pages:
+                    out = dst.with_name(f"{dst.stem}-{page:04d}.png")
+                    rendered.save(out, dpi=(dpi, dpi), icc_profile=None)
+                    outputs.append(out)
+        except OSError as exc:
+            raise EngineFailed(f"lib export_pages: {exc}") from exc
+        return Report("export_pages", policy, self.name, self.version(), outputs, losses)
+
+
+engine = LibEngine()

mcruft/engines/libs_pdfium.py

@@ -0,0 +1,55 @@
+# this_file: packages/mcruft/src/mcruft/engines/libs_pdfium.py
+"""Optional PDF rasterization; PDFium is not thread-safe, even across documents."""
+
+import importlib.util
+from contextlib import closing
+from importlib.metadata import version
+from pathlib import Path
+from threading import Lock
+
+from ..report import EngineFailed, Loss, Policy, Report
+from .base import Capability
+from .cli import page_indexes, pixel_scale
+
+PDFIUM_LOCK = Lock()
+
+
+def capabilities() -> list[Capability]:
+    if importlib.util.find_spec("pypdfium2") is None:
+        return []
+    return [
+        Capability(
+            "export_pages", "pdf", "png", "fidelity", f"lib pypdfium2 {version('pypdfium2')}"
+        )
+    ]
+
+
+def export_pages(src: Path, dst: Path, policy: Policy, **opts) -> Report:
+    dpi = opts.get("dpi", 150)
+    scale = pixel_scale(dpi)
+    outputs = []
+    with PDFIUM_LOCK:
+        # Import initializes PDFium; creation, rendering and cleanup all need the lock.
+        import pypdfium2 as pdfium
+
+        try:
+            with pdfium.PdfDocument(src) as document:
+                for index in page_indexes(opts.get("pages"), len(document)):
+                    out = dst.with_name(f"{dst.stem}-{index:04d}.png")
+                    with (
+                        closing(document[index]) as page,
+                        closing(page.render(scale=scale)) as bitmap,
+                        bitmap.to_pil() as image,
+                    ):
+                        image.save(out, dpi=(dpi, dpi))
+                    outputs.append(out)
+        except (OSError, pdfium.PdfiumError) as exc:
+            raise EngineFailed(f"lib pypdfium2 export_pages: {exc}") from exc
+    return Report(
+        "export_pages",
+        policy,
+        "lib",
+        version("pypdfium2"),
+        outputs,
+        [Loss("raster", "PDF pages rasterised")],
+    )