Release v1.1.0: Added immage support

Author: FlacSy

document_placeholder/__init__.py

@@ -1,3 +1,3 @@
 """DocumentPlaceholder — fill Word templates using YAML configs."""
 
-__version__ = "1.0.0.post1"
+__version__ = "1.1.0"

document_placeholder/cli.py

@@ -7,6 +7,7 @@
 from pathlib import Path
 
 import document_placeholder.functions.date  # noqa: F401 — register functions
+import document_placeholder.functions.image  # noqa: F401
 import document_placeholder.functions.logic  # noqa: F401
 import document_placeholder.functions.math  # noqa: F401
 import document_placeholder.functions.string  # noqa: F401

document_placeholder/functions/image.py

@@ -0,0 +1,24 @@
+"""Функции для вставки изображений в документ."""
+
+from __future__ import annotations
+
+from document_placeholder.functions import FunctionRegistry
+from document_placeholder.image_value import ImageValue
+
+_reg = FunctionRegistry.register
+
+
+@_reg("IMAGE")
+def image(
+    source: str,
+    width_cm: float | None = None,
+    height_cm: float | None = None,
+) -> ImageValue:
+    """Вставить изображение по URL или пути к файлу.
+
+    source: URL (https://...) или путь к файлу (.png, .jpg, ...)
+    width_cm, height_cm: размер в см (опционально). Если не заданы — 5 см по ширине.
+    """
+    w = float(width_cm) if width_cm is not None else 5.0
+    h = float(height_cm) if height_cm is not None else None
+    return ImageValue(source=source, width_cm=w, height_cm=h)

document_placeholder/gui.py

@@ -11,6 +11,7 @@
 from tkinter import filedialog
 
 import document_placeholder.functions.date  # noqa: F401 — register functions
+import document_placeholder.functions.image  # noqa: F401
 import document_placeholder.functions.logic  # noqa: F401
 import document_placeholder.functions.math  # noqa: F401
 import document_placeholder.functions.string  # noqa: F401

document_placeholder/image_value.py

@@ -0,0 +1,19 @@
+"""Значение-изображение для вставки в документ."""
+
+from __future__ import annotations
+
+
+class ImageValue:
+    """Дескриптор изображения: URL или путь к файлу. Processor вставит картинку."""
+
+    __slots__ = ("source", "width_cm", "height_cm")
+
+    def __init__(
+        self,
+        source: str,
+        width_cm: float | None = None,
+        height_cm: float | None = None,
+    ) -> None:
+        self.source = source.strip()
+        self.width_cm = width_cm
+        self.height_cm = height_cm

document_placeholder/processor.py

@@ -2,10 +2,15 @@
 
 from __future__ import annotations
 
+import urllib.request
+from io import BytesIO
 from pathlib import Path
 from typing import Any
 
 from docx import Document
+from docx.shared import Cm
+
+from document_placeholder.image_value import ImageValue
 
 
 class DocumentProcessor:
@@ -43,16 +48,97 @@ def _replace_in_paragraph(paragraph, values: dict[str, Any]) -> None:
         if not runs:
             return
 
-        full_text = "".join(run.text for run in runs)
+        for key, value in values.items():
+            if not isinstance(value, ImageValue):
+                continue
+            placeholder = "{" + key + "}"
+            for run in runs:
+                if placeholder in run.text:
+                    run.text = run.text.replace(placeholder, "")
+                    try:
+                        stream = DocumentProcessor._load_image(value.source)
+                        w = value.width_cm if value.width_cm is not None else 5.0
+                        kwargs: dict[str, Any] = {"width": Cm(w)}
+                        if value.height_cm is not None:
+                            kwargs["height"] = Cm(value.height_cm)
+                        run.add_picture(stream, **kwargs)
+                    except (OSError, ValueError, KeyError):
+                        pass
+                    break
 
+        full_text = "".join(run.text for run in runs)
         new_text = full_text
         for key, value in values.items():
+            if isinstance(value, ImageValue):
+                continue
             placeholder = "{" + key + "}"
             if placeholder in new_text:
                 display = str(value) if value is not None else ""
+                display = DocumentProcessor._sanitize_xml_text(display)
                 new_text = new_text.replace(placeholder, display)
 
         if new_text != full_text:
-            runs[0].text = new_text
+            runs[0].text = DocumentProcessor._sanitize_xml_text(new_text)
             for run in runs[1:]:
                 run.text = ""
+
+    @staticmethod
+    def _sanitize_xml_text(text: str) -> str:
+        """Удалить символы, недопустимые в XML (NULL, control chars)."""
+        if not text:
+            return ""
+        result = []
+        for c in str(text):
+            code = ord(c)
+            if code == 0x9 or code == 0xA or code == 0xD:
+                result.append(c)
+            elif 0x20 <= code <= 0xD7FF or 0xE000 <= code <= 0xFFFD:
+                result.append(c)
+            elif 0x10000 <= code <= 0x10FFFF:
+                result.append(c)
+            else:
+                result.append(" ")
+        return "".join(result)
+
+    @staticmethod
+    def _load_image(source: str) -> BytesIO:
+        """Загрузить изображение из URL или файла. SVG конвертируется в PNG."""
+        source = source.strip()
+        if source.startswith(("http://", "https://")):
+            req = urllib.request.Request(
+                source,
+                headers={"User-Agent": "DocumentPlaceholder/1.0"},
+            )
+            with urllib.request.urlopen(req, timeout=30) as resp:
+                data = resp.read()
+        else:
+            path = Path(source)
+            if path.exists():
+                data = path.read_bytes()
+            else:
+                raise FileNotFoundError(source)
+
+        return DocumentProcessor._ensure_raster(data, source)
+
+    @staticmethod
+    def _ensure_raster(data: bytes, source: str = "") -> BytesIO:
+        """Конвертировать SVG в PNG, остальные форматы вернуть как есть."""
+        if DocumentProcessor._is_svg(data, source):
+            try:
+                from cairosvg import svg2png
+
+                png_out = BytesIO()
+                svg2png(bytestring=data, write_to=png_out)
+                png_out.seek(0)
+                return png_out
+            except Exception:
+                raise ValueError("SVG conversion failed")
+        return BytesIO(data)
+
+    @staticmethod
+    def _is_svg(data: bytes, source: str) -> bool:
+        """Проверить, является ли контент SVG."""
+        if source.lower().endswith(".svg") or source.lower().endswith(".svgz"):
+            return True
+        start = data.lstrip()[:200].decode("utf-8", errors="ignore")
+        return start.lstrip().startswith("<svg") or start.lstrip().startswith("<?xml")

pyproject.toml

@@ -33,6 +33,7 @@ classifiers = [
 dependencies = [
     "python-docx>=1.1.0",
     "PyYAML>=6.0",
+    "cairosvg>=2.7.0",
 ]
 
 [project.optional-dependencies]