edof 3.0.0__py3-none-any.whl

edof/__init__.py

@@ -0,0 +1,91 @@
+# edof/__init__.py
+"""
+from __future__ import annotations
+edof – Easy Document Format 3.0
+================================
+Programmatic document creation, template filling, and export.
+
+Quick start::
+
+    import edof
+
+    doc  = edof.Document(title="Hello")
+    page = doc.add_page()
+    tb   = page.add_textbox(10, 10, 120, 20, "Hello, World!")
+    tb.style.font_size  = 36
+    tb.style.auto_shrink = True
+    doc.save("hello.edof")
+    doc.export_bitmap("hello.png", dpi=300)
+"""
+
+from edof.version    import __version__, FORMAT_VERSION_STR  # noqa: F401
+from edof.exceptions import (                                 # noqa: F401
+    EdofError, EdofVersionError, EdofResourceError,
+    EdofRenderError, EdofVariableError, EdofAPIError,
+    EdofValidationError, EdofPrintError,
+    EdofNewerVersionWarning, EdofMissingOptionalWarning,
+)
+
+from edof.format.document  import Document, Page, ResourceStore   # noqa: F401
+from edof.format.objects   import (                               # noqa: F401
+    EdofObject, TextBox, ImageBox, Shape, QRCode, Group,
+    SHAPE_RECT, SHAPE_ELLIPSE, SHAPE_LINE, SHAPE_POLYGON, SHAPE_ARROW,
+)
+from edof.format.styles    import TextStyle, StrokeStyle, FillStyle, ShadowStyle  # noqa: F401
+from edof.format.variables import VariableStore, VariableDef      # noqa: F401
+from edof.format.variables import (                               # noqa: F401
+    VAR_TEXT, VAR_IMAGE, VAR_NUMBER, VAR_DATE, VAR_BOOL, VAR_QR, VAR_URL,
+)
+from edof.format.serializer import EdofSerializer                 # noqa: F401
+from edof.format.document   import (                              # noqa: F401
+    CS_RGB, CS_RGBA, CS_GRAY, CS_BW, CS_CMYK, BD_8, BD_16,
+)
+from edof.engine.transform  import Transform, to_mm, from_mm, mm_to_px  # noqa: F401
+from edof.engine.renderer   import render_page, render_document    # noqa: F401
+from edof.export.bitmap     import (                               # noqa: F401
+    export_page_bitmap, export_all_pages, export_to_bytes,
+)
+
+# ── Convenience aliases ───────────────────────────────────────────────────────
+
+def load(path: str) -> Document:
+    """Load an .edof file and return a Document."""
+    return Document.load(path)
+
+
+def new(width: float = 210.0, height: float = 297.0, **kwargs) -> Document:
+    """Create a new blank Document."""
+    return Document(width=width, height=height, **kwargs)
+
+
+__all__ = [
+    # Core
+    "Document", "Page", "ResourceStore",
+    # Objects
+    "EdofObject", "TextBox", "ImageBox", "Shape", "QRCode", "Group",
+    "SHAPE_RECT", "SHAPE_ELLIPSE", "SHAPE_LINE", "SHAPE_POLYGON", "SHAPE_ARROW",
+    # Styles
+    "TextStyle", "StrokeStyle", "FillStyle", "ShadowStyle",
+    # Variables
+    "VariableStore", "VariableDef",
+    "VAR_TEXT", "VAR_IMAGE", "VAR_NUMBER", "VAR_DATE", "VAR_BOOL", "VAR_QR", "VAR_URL",
+    # Serializer
+    "EdofSerializer",
+    # Color-space / bit-depth constants
+    "CS_RGB", "CS_RGBA", "CS_GRAY", "CS_BW", "CS_CMYK", "BD_8", "BD_16",
+    # Transform
+    "Transform", "to_mm", "from_mm", "mm_to_px",
+    # Render
+    "render_page", "render_document",
+    # Export helpers
+    "export_page_bitmap", "export_all_pages", "export_to_bytes",
+    # Convenience
+    "load", "new",
+    # Version
+    "__version__", "FORMAT_VERSION_STR",
+    # Exceptions
+    "EdofError", "EdofVersionError", "EdofResourceError",
+    "EdofRenderError", "EdofVariableError", "EdofAPIError",
+    "EdofValidationError", "EdofPrintError",
+    "EdofNewerVersionWarning", "EdofMissingOptionalWarning",
+]

edof/api/commands.py

@@ -0,0 +1,326 @@
+# edof/api/commands.py
+"""
+Command API – a string-based command system usable from:
+  • editor undo/redo stacks
+  • external scripts / automation
+  • network / IPC APIs
+
+Every command is a plain dict:
+  {"cmd": "set_text", "object_id": "...", "text": "Hello"}
+
+The CommandRegistry maps command names → handler functions.
+The CommandHistory manages undo/redo.
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from edof.format.document import Document
+
+Handler = Callable[["Document", dict], Any]
+
+
+# ── Registry ──────────────────────────────────────────────────────────────────
+
+class CommandRegistry:
+    def __init__(self) -> None:
+        self._handlers: Dict[str, Handler] = {}
+        self._register_builtins()
+
+    def register(self, name: str, handler: Handler) -> None:
+        self._handlers[name] = handler
+
+    def execute(self, doc: "Document", command: dict) -> Any:
+        from edof.exceptions import EdofAPIError
+        name = command.get("cmd")
+        if not name:
+            raise EdofAPIError("Command dict must have a 'cmd' key.")
+        handler = self._handlers.get(name)
+        if handler is None:
+            raise EdofAPIError(f"Unknown command: {name!r}")
+        return handler(doc, command)
+
+    # ── Built-in commands ──────────────────────────────────────────────────────
+
+    def _register_builtins(self) -> None:
+        self.register("set_text",         _cmd_set_text)
+        self.register("set_variable",     _cmd_set_variable)
+        self.register("fill_variables",   _cmd_fill_variables)
+        self.register("add_page",         _cmd_add_page)
+        self.register("remove_page",      _cmd_remove_page)
+        self.register("add_textbox",      _cmd_add_textbox)
+        self.register("add_image",        _cmd_add_image)
+        self.register("add_shape",        _cmd_add_shape)
+        self.register("add_qrcode",       _cmd_add_qrcode)
+        self.register("remove_object",    _cmd_remove_object)
+        self.register("move_object",      _cmd_move_object)
+        self.register("resize_object",    _cmd_resize_object)
+        self.register("rotate_object",    _cmd_rotate_object)
+        self.register("set_style",        _cmd_set_style)
+        self.register("set_visibility",   _cmd_set_visibility)
+        self.register("set_layer",        _cmd_set_layer)
+        self.register("export_bitmap",    _cmd_export_bitmap)
+        self.register("export_pdf",       _cmd_export_pdf)
+        self.register("save",             _cmd_save)
+        self.register("validate",         _cmd_validate)
+
+
+# ── Command handlers ──────────────────────────────────────────────────────────
+
+def _get_obj(doc: "Document", command: dict):
+    from edof.exceptions import EdofAPIError
+    oid = command.get("object_id")
+    if not oid:
+        raise EdofAPIError("'object_id' required.")
+    page_idx = int(command.get("page", 0))
+    page = doc.pages[page_idx]
+    obj = page.get_object(oid)
+    if obj is None:
+        raise EdofAPIError(f"Object {oid!r} not found on page {page_idx}.")
+    return obj
+
+
+def _cmd_set_text(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    from edof.format.objects import TextBox
+    if not isinstance(obj, TextBox):
+        from edof.exceptions import EdofAPIError
+        raise EdofAPIError("Object is not a TextBox.")
+    obj.text = str(cmd.get("text", ""))
+    return obj.id
+
+
+def _cmd_set_variable(doc, cmd):
+    name  = cmd.get("name")
+    value = cmd.get("value", "")
+    doc.set_variable(name, value)
+    return name
+
+
+def _cmd_fill_variables(doc, cmd):
+    mapping = cmd.get("mapping", {})
+    doc.fill_variables(mapping)
+    return list(mapping.keys())
+
+
+def _cmd_add_page(doc, cmd):
+    page = doc.add_page(
+        width=cmd.get("width"), height=cmd.get("height"),
+        dpi=cmd.get("dpi"), color_space=cmd.get("color_space"),
+    )
+    return page.id
+
+
+def _cmd_remove_page(doc, cmd):
+    doc.remove_page(int(cmd.get("index", 0)))
+
+
+def _cmd_add_textbox(doc, cmd):
+    page = doc.pages[int(cmd.get("page", 0))]
+    tb = page.add_textbox(
+        x=float(cmd.get("x", 0)),
+        y=float(cmd.get("y", 0)),
+        width=float(cmd.get("width", 80)),
+        height=float(cmd.get("height", 20)),
+        text=str(cmd.get("text", "")),
+        unit=cmd.get("unit", "mm"),
+    )
+    if "variable" in cmd:
+        tb.variable = cmd["variable"]
+    return tb.id
+
+
+def _cmd_add_image(doc, cmd):
+    page = doc.pages[int(cmd.get("page", 0))]
+    rid = cmd.get("resource_id") or doc.add_resource_from_file(cmd["path"])
+    ib = page.add_image(resource_id=rid,
+                         x=float(cmd.get("x", 0)),
+                         y=float(cmd.get("y", 0)),
+                         width=float(cmd.get("width", 50)),
+                         height=float(cmd.get("height", 50)),
+                         unit=cmd.get("unit", "mm"))
+    return ib.id
+
+
+def _cmd_add_shape(doc, cmd):
+    page = doc.pages[int(cmd.get("page", 0))]
+    sh = page.add_shape(
+        shape_type=cmd.get("shape_type", "rect"),
+        x=float(cmd.get("x", 0)), y=float(cmd.get("y", 0)),
+        width=float(cmd.get("width", 50)), height=float(cmd.get("height", 30)),
+        unit=cmd.get("unit", "mm"),
+    )
+    return sh.id
+
+
+def _cmd_add_qrcode(doc, cmd):
+    page = doc.pages[int(cmd.get("page", 0))]
+    qr = page.add_qrcode(
+        data=cmd.get("data", ""),
+        x=float(cmd.get("x", 0)), y=float(cmd.get("y", 0)),
+        size=float(cmd.get("size", 30)),
+        unit=cmd.get("unit", "mm"),
+        error_correction=cmd.get("error_correction", "M"),
+    )
+    return qr.id
+
+
+def _cmd_remove_object(doc, cmd):
+    page = doc.pages[int(cmd.get("page", 0))]
+    return page.remove_object(cmd.get("object_id", ""))
+
+
+def _cmd_move_object(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    obj.transform.translate(
+        float(cmd.get("dx", 0)),
+        float(cmd.get("dy", 0)),
+        cmd.get("unit", "mm"),
+    )
+
+
+def _cmd_resize_object(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    if "factor" in cmd:
+        obj.transform.resize_uniform(float(cmd["factor"]))
+    else:
+        obj.transform.resize_free(
+            float(cmd.get("width",  obj.transform.width)),
+            float(cmd.get("height", obj.transform.height)),
+            cmd.get("unit", "mm"),
+            cmd.get("anchor", "top-left"),
+        )
+
+
+def _cmd_rotate_object(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    if "angle_absolute" in cmd:
+        obj.transform.rotate_to(float(cmd["angle_absolute"]))
+    else:
+        obj.transform.rotate(float(cmd.get("angle", 0)))
+
+
+def _cmd_set_style(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    from edof.format.objects import TextBox
+    if isinstance(obj, TextBox):
+        for k, v in cmd.get("style", {}).items():
+            if hasattr(obj.style, k):
+                setattr(obj.style, k, v)
+
+
+def _cmd_set_visibility(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    obj.visible = bool(cmd.get("visible", True))
+
+
+def _cmd_set_layer(doc, cmd):
+    obj = _get_obj(doc, cmd)
+    obj.layer = int(cmd.get("layer", 0))
+
+
+def _cmd_export_bitmap(doc, cmd):
+    from edof.export.bitmap import export_page_bitmap
+    export_page_bitmap(
+        doc,
+        page_index=int(cmd.get("page", 0)),
+        path=cmd["path"],
+        dpi=cmd.get("dpi"),
+        color_space=cmd.get("color_space"),
+        format=cmd.get("format", "PNG"),
+    )
+
+
+def _cmd_export_pdf(doc, cmd):
+    from edof.export.pdf import export_pdf
+    export_pdf(doc, cmd["path"])
+
+
+def _cmd_save(doc, cmd):
+    doc.save(cmd["path"])
+
+
+def _cmd_validate(doc, cmd):
+    return doc.validate()
+
+
+# ── History (undo/redo) ────────────────────────────────────────────────────────
+
+@dataclass
+class HistoryEntry:
+    description: str
+    snapshot:    bytes         # serialised document state
+
+
+class CommandHistory:
+    """
+    Undo/redo stack based on document snapshots.
+    Each snapshot is a full .edof file in memory (~fast for small documents).
+    """
+
+    def __init__(self, max_undo: int = 50) -> None:
+        self._stack:   List[HistoryEntry] = []
+        self._pointer: int                = -1
+        self._max:     int                = max_undo
+
+    def _snapshot(self, doc: "Document") -> bytes:
+        from edof.format.serializer import EdofSerializer
+        return EdofSerializer.to_bytes(doc)
+
+    def _restore(self, data: bytes) -> "Document":
+        from edof.format.serializer import EdofSerializer
+        return EdofSerializer.from_bytes(data)
+
+    def push(self, doc: "Document", description: str = "") -> None:
+        # Drop any redo states ahead of current pointer
+        self._stack = self._stack[:self._pointer + 1]
+        entry = HistoryEntry(description=description,
+                             snapshot=self._snapshot(doc))
+        self._stack.append(entry)
+        if len(self._stack) > self._max:
+            self._stack.pop(0)
+        self._pointer = len(self._stack) - 1
+
+    def undo(self, doc: "Document") -> Optional["Document"]:
+        if self._pointer <= 0:
+            return None
+        self._pointer -= 1
+        return self._restore(self._stack[self._pointer].snapshot)
+
+    def redo(self, doc: "Document") -> Optional["Document"]:
+        if self._pointer >= len(self._stack) - 1:
+            return None
+        self._pointer += 1
+        return self._restore(self._stack[self._pointer].snapshot)
+
+    def can_undo(self) -> bool:
+        return self._pointer > 0
+
+    def can_redo(self) -> bool:
+        return self._pointer < len(self._stack) - 1
+
+    def description_undo(self) -> str:
+        if self._pointer > 0:
+            return self._stack[self._pointer].description
+        return ""
+
+    def description_redo(self) -> str:
+        if self._pointer < len(self._stack) - 1:
+            return self._stack[self._pointer + 1].description
+        return ""
+
+    def clear(self) -> None:
+        self._stack.clear()
+        self._pointer = -1
+
+
+# ── Module-level singleton registry ───────────────────────────────────────────
+
+registry = CommandRegistry()
+
+
+def execute(doc: "Document", command: dict) -> Any:
+    """Execute a command dict against a document using the global registry."""
+    return registry.execute(doc, command)

edof/engine/__init__.py

@@ -0,0 +1 @@
+# edof sub-package

edof/engine/color.py

@@ -0,0 +1,90 @@
+# edof/engine/color.py
+"""
+Colour-space helpers.
+Conversion is delegated to Pillow; this module provides a clean interface
+and validates the settings chosen in the document.
+"""
+
+from __future__ import annotations
+from typing import Optional
+from PIL import Image
+
+# Mapping from edof CS constants → Pillow mode
+PILLOW_MODE: dict[str, str] = {
+    "RGB":  "RGB",
+    "RGBA": "RGBA",
+    "L":    "L",       # 8-bit grayscale
+    "1":    "1",       # 1-bit B&W
+    "CMYK": "CMYK",
+}
+
+VALID_COLOR_SPACES = set(PILLOW_MODE.keys())
+VALID_BIT_DEPTHS   = {8, 16}
+
+
+def validate(color_space: str, bit_depth: int) -> None:
+    from edof.exceptions import EdofValidationError
+    if color_space not in VALID_COLOR_SPACES:
+        raise EdofValidationError(
+            f"Unknown colour space {color_space!r}. "
+            f"Valid: {sorted(VALID_COLOR_SPACES)}"
+        )
+    if bit_depth not in VALID_BIT_DEPTHS:
+        raise EdofValidationError(
+            f"Unsupported bit depth {bit_depth}. Valid: {VALID_BIT_DEPTHS}"
+        )
+
+
+def pillow_mode(color_space: str) -> str:
+    return PILLOW_MODE.get(color_space, "RGB")
+
+
+def convert_image(img: Image.Image,
+                  color_space: str,
+                  bit_depth: int = 8) -> Image.Image:
+    """
+    Convert a Pillow image to the target colour space and bit depth.
+    Always works non-destructively (returns new image).
+    """
+    validate(color_space, bit_depth)
+    mode = pillow_mode(color_space)
+
+    # ── Colour-space conversion ────────────────────────────────────────────────
+    if img.mode != mode:
+        if mode == "1":
+            # Convert to grayscale first for clean B&W threshold
+            img = img.convert("L").convert("1")
+        elif mode == "CMYK" and img.mode in ("RGBA", "LA"):
+            img = img.convert("RGB").convert("CMYK")
+        else:
+            try:
+                img = img.convert(mode)
+            except Exception:
+                img = img.convert("RGB").convert(mode)
+
+    # ── Bit depth ─────────────────────────────────────────────────────────────
+    if bit_depth == 16 and mode in ("RGB", "L", "RGBA"):
+        import numpy as np
+        arr = np.array(img, dtype=np.uint16) * 257   # 8-bit → 16-bit range
+        # Pillow doesn't natively save 16-bit RGB; return as I;16 for TIFF
+        if mode == "L":
+            img = Image.fromarray(arr.astype(np.uint16), mode="I;16")
+        # For RGB 16-bit export Pillow uses mode "I;16" only for grayscale;
+        # callers should save as TIFF with bit_depth hint in metadata.
+
+    return img
+
+
+def background_image(width_px: int, height_px: int,
+                     color_space: str,
+                     background: tuple = (255, 255, 255)) -> Image.Image:
+    """Create a blank canvas in the correct mode."""
+    mode = pillow_mode(color_space)
+    if mode == "1":
+        return Image.new("1", (width_px, height_px), 1)
+    if mode == "CMYK":
+        return Image.new("CMYK", (width_px, height_px), (0, 0, 0, 0))
+    # Clamp alpha for RGBA
+    if mode == "RGBA" and len(background) == 3:
+        background = (*background, 255)
+    return Image.new(mode, (width_px, height_px), background[:len(background)])