pdfdancer-client-python 0.3.9__tar.gz → 0.3.10__tar.gz

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/.gitignore

@@ -18,3 +18,4 @@ __pycache__/
 .Python
 /.run/
 /build
+.env

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.9
+Version: 0.3.10
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 
@@ -672,6 +672,7 @@ Contributions are welcome via pull request. Please:
 - [PyPI](https://pypi.org/project/pdfdancer-client-python/)
 - [Changelog](https://www.pdfdancer.com/changelog/?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
 - [Status](https://status.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
+- [Issue tracker](https://github.com/MenschMachine/pdfdancer)
 
 ## Related SDKs
 

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/README.md

@@ -433,6 +433,7 @@ Contributions are welcome via pull request. Please:
 - [PyPI](https://pypi.org/project/pdfdancer-client-python/)
 - [Changelog](https://www.pdfdancer.com/changelog/?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
 - [Status](https://status.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
+- [Issue tracker](https://github.com/MenschMachine/pdfdancer)
 
 ## Related SDKs
 

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pdfdancer-client-python"
-version = "0.3.9"
+version = "0.3.10"
 description = "Python client for PDFDancer API"
 readme = "README.md"
 authors = [

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/src/pdfdancer/models.py

@@ -1686,18 +1686,22 @@ class TemplateReplacement:
 
     Parameters:
     - placeholder: The exact text to find and replace in the PDF.
-    - text: The text to replace the placeholder with.
+    - text: The text to replace the placeholder with. None for image replacements.
     - font: Optional font for the replacement text.
     - color: Optional color for the replacement text.
+    - image: Optional Image to replace the placeholder with. When set, text should be None.
     """
 
     placeholder: str
-    text: str
+    text: Optional[str] = None
     font: Optional[Font] = None
     color: Optional[Color] = None
+    image: Optional[Image] = None
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        import base64
+
         result: Dict[str, Any] = {
             "placeholder": self.placeholder,
             "text": self.text,
@@ -1711,6 +1715,20 @@ class TemplateReplacement:
                 "blue": self.color.b,
                 "alpha": self.color.a,
             }
+        if self.image:
+            image_dict: Dict[str, Any] = {}
+            if self.image.data:
+                image_dict["data"] = base64.b64encode(self.image.data).decode("utf-8")
+            if self.image.format:
+                image_dict["format"] = self.image.format
+            if self.image.width is not None or self.image.height is not None:
+                size: Dict[str, float] = {}
+                if self.image.width is not None:
+                    size["width"] = self.image.width
+                if self.image.height is not None:
+                    size["height"] = self.image.height
+                image_dict["size"] = size
+            result["image"] = image_dict
         return result
 
 

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/src/pdfdancer/pdfdancer_v1.py

@@ -131,6 +131,34 @@ def _dict_to_replacements(
     for placeholder, value in replacements.items():
         if isinstance(value, str):
             result.append(TemplateReplacement(placeholder=placeholder, text=value))
+        elif "image" in value:
+            image_source = value["image"]
+            if isinstance(image_source, Path):
+                image_data = image_source.read_bytes()
+                image_format = image_source.suffix.lstrip(".").upper()
+                if image_format == "JPG":
+                    image_format = "JPEG"
+            elif isinstance(image_source, bytes):
+                image_data = image_source
+                image_format = None
+            else:
+                raise ValueError(
+                    f"Unsupported image source type: {type(image_source)}. "
+                    "Use a Path or bytes."
+                )
+            img = Image(
+                data=image_data,
+                format=value.get("format", image_format),
+                width=value.get("width"),
+                height=value.get("height"),
+            )
+            result.append(
+                TemplateReplacement(
+                    placeholder=placeholder,
+                    text=None,
+                    image=img,
+                )
+            )
         else:
             result.append(
                 TemplateReplacement(
@@ -644,6 +672,8 @@ class PageClient:
             replacements: Dict mapping placeholder strings to replacement values.
                 - Simple: {"{{NAME}}": "John Doe"}
                 - With options: {"{{NAME}}": {"text": "John", "font": Font(...), "color": Color(...)}}
+                - With image: {"{{LOGO}}": {"image": Path("logo.png")}}
+                - With image and size: {"{{LOGO}}": {"image": Path("logo.png"), "width": 50, "height": 50}}
             reflow_preset: Optional ReflowPreset to control text reflow behavior.
                 - BEST_EFFORT: Attempt to reflow, proceed even if imperfect
                 - FIT_OR_FAIL: Reflow must succeed or operation fails
@@ -2281,6 +2311,8 @@ class PDFDancer:
             replacements: Dict mapping placeholder strings to replacement values.
                 - Simple: {"{{NAME}}": "John Doe"}
                 - With options: {"{{NAME}}": {"text": "John", "font": Font(...), "color": Color(...)}}
+                - With image: {"{{LOGO}}": {"image": Path("logo.png")}}
+                - With image and size: {"{{LOGO}}": {"image": Path("logo.png"), "width": 50, "height": 50}}
             reflow_preset: Optional ReflowPreset to control text reflow behavior.
                 - BEST_EFFORT: Attempt to reflow, proceed even if imperfect
                 - FIT_OR_FAIL: Reflow must succeed or operation fails

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/src/pdfdancer_client_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.9
+Version: 0.3.10
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 
@@ -672,6 +672,7 @@ Contributions are welcome via pull request. Please:
 - [PyPI](https://pypi.org/project/pdfdancer-client-python/)
 - [Changelog](https://www.pdfdancer.com/changelog/?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
 - [Status](https://status.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
+- [Issue tracker](https://github.com/MenschMachine/pdfdancer)
 
 ## Related SDKs
 

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/tests/e2e/__init__.py

@@ -4,6 +4,7 @@ from typing import Tuple
 
 import httpx
 import pytest
+from dotenv import load_dotenv
 
 
 def _get_base_url():
@@ -11,6 +12,7 @@ def _get_base_url():
 
 
 def _read_token() -> str | None:
+    load_dotenv()
     # Check PDFDANCER_API_TOKEN first (preferred), then PDFDANCER_TOKEN (legacy)
     token = os.getenv("PDFDANCER_API_TOKEN") or os.getenv("PDFDANCER_TOKEN")
     if token:

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/tests/e2e/test_line.py

@@ -21,7 +21,7 @@ def test_find_lines_by_position():
 
     with PDFDancer.open(pdf_path, token=token, base_url=base_url, timeout=30.0) as pdf:
         lines = pdf.select_text_lines()
-        assert len(lines) == 35
+        assert len(lines) == 36
 
         first = lines[0]
         assert first.position is not None

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/tests/e2e/test_template_replace.py

@@ -1,5 +1,7 @@
 """E2E tests for template replacement functionality."""
 
+from pathlib import Path
+
 import pytest
 
 from pdfdancer import Color, Font, ReflowPreset, ValidationException
@@ -222,3 +224,53 @@ def test_reflow_preset_values():
     assert ReflowPreset.BEST_EFFORT.value == "BEST_EFFORT"
     assert ReflowPreset.FIT_OR_FAIL.value == "FIT_OR_FAIL"
     assert ReflowPreset.NONE.value == "NONE"
+
+
+def test_replace_template_with_image():
+    """Test replacing a placeholder with an image file (natural size)."""
+    base_url, token, pdf_path = _require_env_and_fixture("Showcase.pdf")
+    logo_path = Path(__file__).resolve().parent.parent / "fixtures" / "logo-80.png"
+    assert logo_path.exists(), "logo-80.png fixture not found"
+
+    with PDFDancer.open(pdf_path, token=token, base_url=base_url, timeout=30.0) as pdf:
+        # Count images before replacement
+        images_before = pdf.select_images()
+        count_before = len(images_before)
+
+        # Replace "Showcase" placeholder with an image
+        result = pdf.apply_replacements({
+            "Showcase": {"image": logo_path},
+        })
+
+        assert result is True
+
+        # The placeholder text should be gone
+        (
+            PDFAssertions(pdf)
+            .assert_textline_does_not_exist("Showcase")
+        )
+
+        # There should be more images now
+        images_after = pdf.select_images()
+        assert len(images_after) > count_before
+
+
+def test_replace_template_with_image_explicit_size():
+    """Test replacing a placeholder with an image file with explicit width/height."""
+    base_url, token, pdf_path = _require_env_and_fixture("Showcase.pdf")
+    logo_path = Path(__file__).resolve().parent.parent / "fixtures" / "logo-80.png"
+    assert logo_path.exists(), "logo-80.png fixture not found"
+
+    with PDFDancer.open(pdf_path, token=token, base_url=base_url, timeout=30.0) as pdf:
+        # Replace "Showcase" placeholder with a sized image
+        result = pdf.apply_replacements({
+            "Showcase": {"image": logo_path, "width": 50, "height": 50},
+        })
+
+        assert result is True
+
+        # The placeholder text should be gone
+        (
+            PDFAssertions(pdf)
+            .assert_textline_does_not_exist("Showcase")
+        )

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.10}/tests/test_models.py

@@ -16,9 +16,13 @@ from pdfdancer import (
     PositionMode,
     ShapeType,
 )
+from pdfdancer.models import TemplateReplacement
 
 # Import Point class for tests
+from pathlib import Path
+
 from pdfdancer.models import Point
+from pdfdancer.pdfdancer_v1 import _dict_to_replacements
 
 
 class TestPosition:
@@ -274,3 +278,94 @@ class TestPoint:
 
         assert point.x == 123.45
         assert point.y == 678.90
+
+
+class TestTemplateReplacement:
+    """Test TemplateReplacement serialization."""
+
+    def test_text_replacement_to_dict(self):
+        """Test basic text replacement serializes correctly."""
+        r = TemplateReplacement(placeholder="{{NAME}}", text="John")
+        d = r.to_dict()
+        assert d == {"placeholder": "{{NAME}}", "text": "John"}
+
+    def test_text_none_with_image_to_dict(self):
+        """Test image replacement has text=None in serialized output."""
+        img = Image(data=b"\x89PNG", format="PNG")
+        r = TemplateReplacement(placeholder="{{LOGO}}", text=None, image=img)
+        d = r.to_dict()
+        assert d["text"] is None
+        assert "image" in d
+        assert d["image"]["format"] == "PNG"
+
+    def test_image_replacement_base64_encoding(self):
+        """Test image data is base64-encoded in serialized output."""
+        import base64
+
+        raw = b"\x89PNG\r\n\x1a\nfakedata"
+        img = Image(data=raw, format="PNG")
+        r = TemplateReplacement(placeholder="{{LOGO}}", image=img)
+        d = r.to_dict()
+        assert d["image"]["data"] == base64.b64encode(raw).decode("utf-8")
+
+    def test_image_replacement_with_size(self):
+        """Test image replacement with explicit width/height includes size."""
+        img = Image(data=b"img", format="JPEG", width=50, height=30)
+        r = TemplateReplacement(placeholder="{{PIC}}", image=img)
+        d = r.to_dict()
+        assert d["image"]["size"] == {"width": 50, "height": 30}
+
+    def test_image_replacement_without_size(self):
+        """Test image replacement without width/height omits size."""
+        img = Image(data=b"img", format="PNG")
+        r = TemplateReplacement(placeholder="{{PIC}}", image=img)
+        d = r.to_dict()
+        assert "size" not in d["image"]
+
+    def test_image_replacement_with_partial_size(self):
+        """Test image replacement with only width includes partial size."""
+        img = Image(data=b"img", format="PNG", width=100)
+        r = TemplateReplacement(placeholder="{{PIC}}", image=img)
+        d = r.to_dict()
+        assert d["image"]["size"] == {"width": 100}
+
+
+class TestDictToReplacements:
+    """Test _dict_to_replacements helper."""
+
+    def test_string_value(self):
+        """Test simple string values produce text replacements."""
+        result = _dict_to_replacements({"{{A}}": "hello"})
+        assert len(result) == 1
+        assert result[0].placeholder == "{{A}}"
+        assert result[0].text == "hello"
+        assert result[0].image is None
+
+    def test_dict_with_text(self):
+        """Test dict values with 'text' key produce text replacements."""
+        result = _dict_to_replacements({"{{A}}": {"text": "hi", "font": Font("Arial", 12)}})
+        assert result[0].text == "hi"
+        assert result[0].font.name == "Arial"
+
+    def test_dict_with_image_path(self):
+        """Test dict values with 'image' Path produce image replacements."""
+        logo = Path(__file__).parent / "fixtures" / "logo-80.png"
+        result = _dict_to_replacements({"{{LOGO}}": {"image": logo}})
+        assert len(result) == 1
+        assert result[0].text is None
+        assert result[0].image is not None
+        assert result[0].image.data == logo.read_bytes()
+        assert result[0].image.format == "PNG"
+
+    def test_dict_with_image_path_and_size(self):
+        """Test dict values with 'image' Path and width/height."""
+        logo = Path(__file__).parent / "fixtures" / "logo-80.png"
+        result = _dict_to_replacements({"{{LOGO}}": {"image": logo, "width": 50, "height": 30}})
+        assert result[0].image.width == 50
+        assert result[0].image.height == 30
+
+    def test_dict_with_image_bytes(self):
+        """Test dict values with 'image' as raw bytes."""
+        result = _dict_to_replacements({"{{LOGO}}": {"image": b"rawdata"}})
+        assert result[0].image.data == b"rawdata"
+        assert result[0].text is None