pdfdancer-client-python 0.3.5__py3-none-any.whl → 0.3.7__py3-none-any.whl

pdfdancer/__init__.py

@@ -40,6 +40,7 @@ from .models import (
     PositionMode,
     RedactResponse,
     RedactTarget,
+    ReflowPreset,
     ShapeType,
     Size,
     StandardFonts,
@@ -90,6 +91,7 @@ __all__ = [
     "Path",
     "RedactTarget",
     "RedactResponse",
+    "ReflowPreset",
     "PdfDancerException",
     "FontNotFoundException",
     "ValidationException",

pdfdancer/models.py

@@ -1662,6 +1662,95 @@ class ImageFlipDirection(Enum):
     BOTH = "BOTH"
 
 
+class ReflowPreset(Enum):
+    """Reflow preset for template replacement operations.
+
+    Controls how text reflow is handled when replacement text differs in length
+    from the original placeholder.
+
+    Values:
+    - BEST_EFFORT: Attempt to reflow text, but proceed even if it doesn't fit perfectly.
+    - FIT_OR_FAIL: Reflow must succeed or the operation fails.
+    - NONE: No reflow - replacement text is placed as-is.
+    """
+
+    BEST_EFFORT = "BEST_EFFORT"
+    FIT_OR_FAIL = "FIT_OR_FAIL"
+    NONE = "NONE"
+
+
+@dataclass
+class TemplateReplacement:
+    """A single template placeholder replacement.
+
+    Parameters:
+    - placeholder: The exact text to find and replace in the PDF.
+    - text: The text to replace the placeholder with.
+    - font: Optional font for the replacement text.
+    - color: Optional color for the replacement text.
+    """
+
+    placeholder: str
+    text: str
+    font: Optional[Font] = None
+    color: Optional[Color] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        result: Dict[str, Any] = {
+            "placeholder": self.placeholder,
+            "text": self.text,
+        }
+        if self.font:
+            result["font"] = {"name": self.font.name, "size": self.font.size}
+        if self.color:
+            result["color"] = {
+                "red": self.color.r,
+                "green": self.color.g,
+                "blue": self.color.b,
+                "alpha": self.color.a,
+            }
+        return result
+
+
+@dataclass
+class TemplateReplaceRequest:
+    """Request for batch template placeholder replacements.
+
+    Parameters:
+    - replacements: List of TemplateReplacement objects.
+    - page_index: Optional 0-based page index. If None, applies to all pages.
+    - reflow_preset: Optional ReflowPreset for text reflow behavior.
+
+    Example:
+    ```python
+    request = TemplateReplaceRequest(
+        replacements=[
+            TemplateReplacement("{{NAME}}", "John Doe"),
+            TemplateReplacement("{{DATE}}", "2025-01-15"),
+        ],
+        page_index=0,  # First page (0-based)
+        reflow_preset=ReflowPreset.BEST_EFFORT,
+    )
+    ```
+    """
+
+    replacements: List[TemplateReplacement]
+    page_index: Optional[int] = None
+    reflow_preset: Optional[ReflowPreset] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        result: Dict[str, Any] = {
+            "replacements": [r.to_dict() for r in self.replacements],
+        }
+        if self.page_index is not None:
+            result["pageIndex"] = self.page_index
+        if self.reflow_preset is not None:
+            result["reflowPreset"] = self.reflow_preset.value
+        return result
+
+
 @dataclass
 class ImageTransformRequest:
     """Request to transform an image in the PDF document.

pdfdancer/pdfdancer_v1.py

@@ -16,7 +16,7 @@ import time
 from datetime import datetime, timezone
 from importlib.metadata import version as get_package_version
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, BinaryIO, List, Mapping, Optional, Union
+from typing import TYPE_CHECKING, Any, BinaryIO, Dict, List, Mapping, Optional, Union
 
 import httpx
 from dotenv import load_dotenv
@@ -62,7 +62,10 @@ from .models import (
     RedactRequest,
     RedactResponse,
     RedactTarget,
+    ReflowPreset,
     ShapeType,
+    TemplateReplacement,
+    TemplateReplaceRequest,
     TextLine,
     TextObjectRef,
 )
@@ -120,6 +123,26 @@ DEFAULT_RETRY_BACKOFF_FACTOR = float(
 )
 
 
+def _dict_to_replacements(
+    replacements: Dict[str, Union[str, dict]]
+) -> List[TemplateReplacement]:
+    """Convert dict-based replacements to TemplateReplacement list."""
+    result = []
+    for placeholder, value in replacements.items():
+        if isinstance(value, str):
+            result.append(TemplateReplacement(placeholder=placeholder, text=value))
+        else:
+            result.append(
+                TemplateReplacement(
+                    placeholder=placeholder,
+                    text=value["text"],
+                    font=value.get("font"),
+                    color=value.get("color"),
+                )
+            )
+    return result
+
+
 def _generate_timestamp() -> str:
     """
     Generate a timestamp string in the format expected by the API.
@@ -606,6 +629,44 @@ class PageClient:
             self.position = Position.at_page(target_page_number)
         return moved
 
+    def apply_replacements(
+        self,
+        replacements: Dict[str, Union[str, dict]],
+        reflow_preset: Optional[ReflowPreset] = None,
+    ) -> bool:
+        """
+        Replace template placeholders on this page.
+
+        Finds exact text matches for placeholders and replaces them with specified
+        content. All placeholders must be found or the operation fails atomically.
+
+        Args:
+            replacements: Dict mapping placeholder strings to replacement values.
+                - Simple: {"{{NAME}}": "John Doe"}
+                - With options: {"{{NAME}}": {"text": "John", "font": Font(...), "color": Color(...)}}
+            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
+                - NONE: No reflow, replacement placed as-is
+
+        Returns:
+            True if all replacements were successful
+
+        Example:
+            ```python
+            page.apply_replacements({
+                "{{NAME}}": "John Doe",
+            })
+            ```
+        """
+        replacement_list = _dict_to_replacements(replacements)
+        # noinspection PyProtectedMember
+        return self.root._apply_replacements(
+            replacements=replacement_list,
+            page_number=self.page_number,
+            reflow_preset=reflow_preset,
+        )
+
     def _ref(self):
         return ObjectRef(
             internal_id=self.internal_id, position=self.position, type=self.object_type
@@ -2163,6 +2224,86 @@ class PDFDancer:
         targets = [RedactTarget(obj.internal_id, replacement) for obj in objects]
         return self._redact(targets, replacement, placeholder_color)
 
+    # Template Replacement Operations
+
+    def _apply_replacements(
+        self,
+        replacements: List[TemplateReplacement],
+        page_number: Optional[int] = None,
+        reflow_preset: Optional[ReflowPreset] = None,
+    ) -> bool:
+        """
+        Internal method to replace template placeholders in the PDF.
+
+        Args:
+            replacements: List of TemplateReplacement objects
+            page_number: Optional 1-based page number. If None, applies to all pages.
+            reflow_preset: Optional reflow behavior preset
+
+        Returns:
+            True if replacement was successful
+        """
+        if not replacements:
+            raise ValidationException("At least one replacement is required")
+
+        # Convert 1-based page_number to 0-based page_index for API
+        page_index = None
+        if page_number is not None:
+            page_index = page_number - 1
+
+        request = TemplateReplaceRequest(
+            replacements=replacements,
+            page_index=page_index,
+            reflow_preset=reflow_preset,
+        )
+        response = self._make_request(
+            "POST", "/template/replace", data=request.to_dict()
+        )
+        result = response.json()
+
+        if result:
+            self._invalidate_snapshots()
+
+        return result
+
+    def apply_replacements(
+        self,
+        replacements: Dict[str, Union[str, dict]],
+        reflow_preset: Optional[ReflowPreset] = None,
+    ) -> bool:
+        """
+        Replace template placeholders in the PDF document.
+
+        Finds exact text matches for placeholders and replaces them with specified
+        content. All placeholders must be found or the operation fails atomically.
+
+        Args:
+            replacements: Dict mapping placeholder strings to replacement values.
+                - Simple: {"{{NAME}}": "John Doe"}
+                - With options: {"{{NAME}}": {"text": "John", "font": Font(...), "color": Color(...)}}
+            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
+                - NONE: No reflow, replacement placed as-is
+
+        Returns:
+            True if all replacements were successful
+
+        Example:
+            ```python
+            pdf.apply_replacements({
+                "{{NAME}}": "John Doe",
+                "{{DATE}}": "2025-01-15",
+            })
+            ```
+        """
+        replacement_list = _dict_to_replacements(replacements)
+        return self._apply_replacements(
+            replacements=replacement_list,
+            page_number=None,
+            reflow_preset=reflow_preset,
+        )
+
     # Add Operations
 
     def _add_image(self, image: Image, position: Optional[Position] = None) -> bool:

{pdfdancer_client_python-0.3.5.dist-info → pdfdancer_client_python-0.3.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.5
+Version: 0.3.7
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 

{pdfdancer_client_python-0.3.5.dist-info → pdfdancer_client_python-0.3.7.dist-info}/RECORD

@@ -1,17 +1,17 @@
-pdfdancer/__init__.py,sha256=IOh8tTro6MQ3dnNT1TcNBtYMBFBdnWqAaEBSwf6hx7Q,2685
+pdfdancer/__init__.py,sha256=I4dxD9zvsj9poA8JRcnuU3ETI9kjaaNjFlSj13Dc3Ug,2723
 pdfdancer/exceptions.py,sha256=mJacmUJTPGUsB8Bo_FgfeXYkvZkH5OPJCVBfilBVmQo,2058
 pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
 pdfdancer/image_builder.py,sha256=aBxMFAMFzzbGTjlVH0hi94mA81cH8tp37Pk84HRPV00,1892
-pdfdancer/models.py,sha256=HztGaGHOH81qvca5aFhEwQ16xlORVWaT1mk9c0RtS58,55644
+pdfdancer/models.py,sha256=nhyVIOr70PMrp3etwrtaduzRLC7jUrJxTa9ZuJXhj9Y,58371
 pdfdancer/page_builder.py,sha256=ARWLRtlrLGbES-0nbiigTOsRVmodRX0DNK8YIAkA9Ig,3850
 pdfdancer/paragraph_builder.py,sha256=OmhzYazMnq0n0rhrjWcKbo0LQfEC7BZoiLB29ycF630,20504
 pdfdancer/path_builder.py,sha256=safKb_IeHRWlQbyBTIXfcoBfXxUZhuzYvBIob5Tbp-8,23938
-pdfdancer/pdfdancer_v1.py,sha256=DURns2KrstV14WyzP3Swydzd0DgH6T7U-ULDcYf99Kc,125122
+pdfdancer/pdfdancer_v1.py,sha256=xr_JdiXnv1X3gIt5qsy-WrlLNy_DJZHFZSF94NurI2M,130060
 pdfdancer/text_line_builder.py,sha256=8jYknV4hw0fyzwX0OI_oLvnh5aMmCV3jXaVkmYLu6MQ,10273
 pdfdancer/types.py,sha256=GJpfp7nuIUbnDBmQ3yoyGyQYFuFO1ppHmo7fcfCM0Ks,21554
-pdfdancer_client_python-0.3.5.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-pdfdancer_client_python-0.3.5.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
-pdfdancer_client_python-0.3.5.dist-info/METADATA,sha256=1ZSqvW_nOKKOH49Mcb14S-YoMFIQLfKne6BABqh5VIw,27907
-pdfdancer_client_python-0.3.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.3.5.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.3.5.dist-info/RECORD,,
+pdfdancer_client_python-0.3.7.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pdfdancer_client_python-0.3.7.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
+pdfdancer_client_python-0.3.7.dist-info/METADATA,sha256=ANHM-uaHat85Owb6YPSxyMSxB9cGfOkfxlpBEf0YPaQ,27907
+pdfdancer_client_python-0.3.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.3.7.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.3.7.dist-info/RECORD,,