pdfdancer-client-python 0.2.25__py3-none-any.whl → 0.2.27__py3-none-any.whl

pdfdancer/__init__.py

@@ -43,11 +43,13 @@ from .models import (
 from .page_builder import PageBuilder
 from .paragraph_builder import ParagraphBuilder
 from .path_builder import BezierBuilder, LineBuilder, PathBuilder
+from .text_line_builder import TextLineBuilder
 
 __version__ = "1.0.0"
 __all__ = [
     "PDFDancer",
     "ParagraphBuilder",
+    "TextLineBuilder",
     "PageBuilder",
     "PathBuilder",
     "LineBuilder",

pdfdancer/models.py

@@ -1102,6 +1102,53 @@ class AddRequest:
                 "lineSpacings": line_spacings,
                 "font": _font_to_dict(obj.font),
             }
+        elif isinstance(obj, TextLine):
+
+            def _font_to_dict(font: Optional[Font]) -> Optional[dict]:
+                if font:
+                    return {"name": font.name, "size": font.size}
+                return None
+
+            def _color_to_dict(color: Optional[Color]) -> Optional[dict]:
+                if color:
+                    return {
+                        "red": color.r,
+                        "green": color.g,
+                        "blue": color.b,
+                        "alpha": color.a,
+                    }
+                return None
+
+            # Build textElement with only non-null fields
+            text_element = {
+                "text": obj.text,
+            }
+
+            if obj.font:
+                text_element["font"] = _font_to_dict(obj.font)
+            if obj.color:
+                text_element["color"] = _color_to_dict(obj.color)
+            if obj.position:
+                text_element["position"] = FindRequest._position_to_dict(obj.position)
+
+            # TEXT_LINE structure matches paragraph line format (textElements only)
+            result = {
+                "type": "TEXT_LINE",
+                "position": (
+                    FindRequest._position_to_dict(obj.position)
+                    if obj.position
+                    else None
+                ),
+                "textElements": [text_element],
+            }
+
+            # Only include top-level font/color if they are not None
+            if obj.font:
+                result["font"] = _font_to_dict(obj.font)
+            if obj.color:
+                result["color"] = _color_to_dict(obj.color)
+
+            return result
         else:
             raise ValueError(f"Unsupported object type: {type(obj)}")
 

pdfdancer/pdfdancer_v1.py

@@ -58,6 +58,7 @@ from .models import (
     Position,
     PositionMode,
     ShapeType,
+    TextLine,
     TextObjectRef,
 )
 from .page_builder import PageBuilder
@@ -2203,6 +2204,33 @@ class PDFDancer:
         self._invalidate_snapshots()
         return result
 
+    def _modify_text_line_full(
+        self, object_ref: ObjectRef, new_text_line: TextLine
+    ) -> CommandResult:
+        """
+        Modifies a text line object with full styling (font, color, position).
+
+        Args:
+            object_ref: Reference to the text line to modify
+            new_text_line: New text line object with styling
+
+        Returns:
+            CommandResult indicating success or failure
+        """
+        if object_ref is None:
+            raise ValidationException("Object reference cannot be null")
+        if new_text_line is None:
+            raise ValidationException("New text line cannot be null")
+
+        # Use /pdf/modify endpoint for full object modification
+        request_data = ModifyRequest(object_ref, new_text_line).to_dict()
+        response = self._make_request("PUT", "/pdf/modify", data=request_data)
+        result = CommandResult.from_dict(response.json())
+
+        # Invalidate snapshot caches after mutation
+        self._invalidate_snapshots()
+        return result
+
     # Font Operations
 
     def find_fonts(self, font_name: str, font_size: int) -> List[Font]:

pdfdancer/text_line_builder.py

@@ -0,0 +1,290 @@
+"""
+TextLineBuilder for the PDFDancer Python client.
+Mirrors the behaviour of ParagraphBuilder for single line text objects.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional, Union
+
+from . import StandardFonts
+from .exceptions import ValidationException
+from .models import (
+    Color,
+    Font,
+    ObjectRef,
+    Position,
+    TextLine,
+    TextObjectRef,
+)
+
+if TYPE_CHECKING:
+    from .pdfdancer_v1 import PDFDancer
+
+DEFAULT_TEXT_COLOR = Color(0, 0, 0)
+_DEFAULT_BASE_FONT_SIZE = 12.0
+
+
+class TextLineBuilder:
+    """
+    Fluent builder used to assemble `TextLine` instances.
+    Behaviour is aligned with ParagraphBuilder but simplified for single-line text.
+    """
+
+    def __init__(self, client: "PDFDancer"):
+        if client is None:
+            raise ValidationException("Client cannot be null")
+
+        self._client = client
+        self._text_line = TextLine()
+        self._text_color: Optional[Color] = None
+        self._text: Optional[str] = None
+        self._ttf_file: Optional[Path] = None
+        self._font: Optional[Font] = None
+        self._font_explicitly_changed = False
+        self._original_text_line_position: Optional[Position] = None
+        self._target_object_ref: Optional[ObjectRef] = None
+        self._original_font: Optional[Font] = None
+        self._original_color: Optional[Color] = None
+        self._position_changed = False
+
+    def only_text_changed(self) -> bool:
+        """Return True when only the text payload has been modified."""
+        return (
+            self._text is not None
+            and self._text_color is None
+            and self._ttf_file is None
+            and (self._font is None or not self._font_explicitly_changed)
+        )
+
+    def text(self, text: str, color: Optional[Color] = None) -> "TextLineBuilder":
+        if text is None:
+            raise ValidationException("Text cannot be null")
+        self._text = text
+        if color is not None:
+            self.color(color)
+        return self
+
+    def font(
+        self, font: Union[Font, str, StandardFonts], font_size: Optional[float] = None
+    ) -> "TextLineBuilder":
+        """
+        Configure the font either by providing a `Font` instance or name + size.
+        """
+        if isinstance(font, Font):
+            resolved_font = font
+        else:
+            if isinstance(font, StandardFonts):
+                font = font.value
+            if font is None:
+                raise ValidationException("Font name cannot be null")
+            if font_size is None:
+                raise ValidationException(
+                    "Font size must be provided when setting font by name"
+                )
+            resolved_font = Font(str(font), font_size)
+
+        self._font = resolved_font
+        self._ttf_file = None
+        self._font_explicitly_changed = True
+        return self
+
+    def font_file(
+        self, ttf_file: Union[Path, str], font_size: float
+    ) -> "TextLineBuilder":
+        if ttf_file is None:
+            raise ValidationException("TTF file cannot be null")
+        if font_size <= 0:
+            raise ValidationException(f"Font size must be positive, got {font_size}")
+
+        ttf_path = Path(ttf_file)
+
+        if not ttf_path.exists():
+            raise ValidationException(f"TTF file does not exist: {ttf_path}")
+        if not ttf_path.is_file():
+            raise ValidationException(f"TTF file is not a file: {ttf_path}")
+        if ttf_path.stat().st_size <= 0:
+            raise ValidationException(f"TTF file is empty: {ttf_path}")
+
+        try:
+            with open(ttf_path, "rb") as handle:
+                handle.read(1)
+        except (IOError, OSError) as exc:
+            raise ValidationException(f"TTF file is not readable: {ttf_path}") from exc
+
+        self._ttf_file = ttf_path
+        self._font = self._register_ttf(ttf_path, font_size)
+        self._font_explicitly_changed = True
+        return self
+
+    def set_font_explicitly_changed(self, changed: bool) -> None:
+        self._font_explicitly_changed = bool(changed)
+
+    def set_original_text_line_position(self, position: Position) -> None:
+        self._original_text_line_position = position
+        if position and self._text_line.position is None:
+            self._text_line.position = deepcopy(position)
+
+    def target(self, object_ref: ObjectRef) -> "TextLineBuilder":
+        if object_ref is None:
+            raise ValidationException("Object reference cannot be null")
+        self._target_object_ref = object_ref
+        return self
+
+    def color(self, color: Color) -> "TextLineBuilder":
+        if color is None:
+            raise ValidationException("Color cannot be null")
+        self._text_color = color
+        return self
+
+    def move_to(self, x: float, y: float) -> "TextLineBuilder":
+        """
+        Move the text line to new coordinates on the same page.
+        """
+        position = self._text_line.position
+        if (
+            position is None
+            and self._target_object_ref
+            and self._target_object_ref.position
+        ):
+            position = deepcopy(self._target_object_ref.position)
+            self._text_line.position = position
+
+        if position is None:
+            raise ValidationException(
+                "Cannot move text line without an existing position"
+            )
+
+        page_index = position.page_index
+        if page_index is None:
+            raise ValidationException(
+                "Text line position must include a page index to move"
+            )
+
+        self._position_changed = True
+        return self.at(page_index, x, y)
+
+    def at_position(self, position: Position) -> "TextLineBuilder":
+        if position is None:
+            raise ValidationException("Position cannot be null")
+        # Defensive copy so builder mutations do not alter original references
+        self._text_line.position = deepcopy(position)
+        self._position_changed = True
+        return self
+
+    def at(self, page_index: int, x: float, y: float) -> "TextLineBuilder":
+        return self.at_position(Position.at_page_coordinates(page_index, x, y))
+
+    def get_text(self) -> Optional[str]:
+        return self._text
+
+    def add(self) -> bool:
+        """
+        Add a new text line to the document.
+        Note: Text lines are typically part of paragraphs. This method is not
+        currently supported for standalone text lines.
+        """
+        raise NotImplementedError(
+            "Adding standalone text lines is not supported. "
+            "Text lines should be added as part of paragraphs."
+        )
+
+    def modify(self, object_ref: Optional[ObjectRef] = None):
+        target_ref = object_ref or self._target_object_ref
+        if target_ref is None:
+            raise ValidationException(
+                "Object reference must be provided to modify a text line"
+            )
+
+        if self.only_text_changed():
+            # Backend accepts plain text updates for simple edits
+            return self._client._modify_text_line(target_ref, self._text or "")
+
+        text_line = self._finalize_text_line()
+        # Use /pdf/modify endpoint for complex modifications
+        return self._client._modify_text_line_full(target_ref, text_line)
+
+    # ------------------------------------------------------------------ #
+    # Internal helpers
+    # ------------------------------------------------------------------ #
+
+    def _finalize_text_line(self) -> TextLine:
+        if self._text_line.position is None:
+            raise ValidationException("Position must be set before building text line")
+
+        if (
+            self._target_object_ref is None
+            and self._font is None
+            and self._text_line.font is None
+        ):
+            raise ValidationException("Font must be set before building text line")
+
+        if self._text is not None:
+            self._text_line.text = self._text
+        elif not self._text_line.text:
+            raise ValidationException("Text must be provided for text line")
+
+        final_font = self._font if self._font is not None else self._original_font
+        if final_font is None:
+            final_font = Font(StandardFonts.HELVETICA.value, _DEFAULT_BASE_FONT_SIZE)
+        self._text_line.font = final_font
+
+        if self._text_color is not None:
+            final_color = self._text_color
+        elif self._text is not None:
+            final_color = self._original_color or DEFAULT_TEXT_COLOR
+        else:
+            final_color = self._original_color
+
+        # Ensure color is never None
+        if final_color is None:
+            final_color = DEFAULT_TEXT_COLOR
+        self._text_line.color = final_color
+
+        return self._text_line
+
+    def _register_ttf(self, ttf_file: Path, font_size: float) -> Font:
+        try:
+            font_name = self._client.register_font(ttf_file)
+            return Font(font_name, font_size)
+        except Exception as exc:
+            raise ValidationException(
+                f"Failed to register font file {ttf_file}: {exc}"
+            ) from exc
+
+    @classmethod
+    def from_object_ref(
+        cls, client: "PDFDancer", object_ref: TextObjectRef
+    ) -> "TextLineBuilder":
+        if object_ref is None:
+            raise ValidationException("Object reference cannot be null")
+
+        builder = cls(client)
+        builder.target(object_ref)
+
+        if object_ref.position:
+            builder.at_position(object_ref.position)
+            builder.set_original_text_line_position(object_ref.position)
+
+        if object_ref.font_name and object_ref.font_size:
+            builder._original_font = Font(object_ref.font_name, object_ref.font_size)
+
+        if object_ref.color:
+            builder._original_color = object_ref.color
+
+        if object_ref.text:
+            builder._text_line.text = object_ref.text
+
+        return builder
+
+
+class TextLinePageBuilder(TextLineBuilder):
+    def __init__(self, client: "PDFDancer", page_index: int):
+        super().__init__(client)
+        self._page_index: Optional[int] = page_index
+
+    # noinspection PyMethodOverriding
+    def at(self, x: float, y: float) -> "TextLineBuilder":
+        return super().at(self._page_index, x, y)

pdfdancer/types.py

@@ -160,12 +160,23 @@ class BaseTextEdit:
 
 class TextLineEdit(BaseTextEdit):
     def apply(self) -> bool:
-        if (
-            self._line_spacing is None
-            and self._font_size is None
+        # Text lines don't support line spacing - ignore if set
+        if self._line_spacing is not None:
+            print(
+                "WARNING: Line spacing is not supported for text lines and will be ignored",
+                file=sys.stderr,
+            )
+
+        # Simple text-only change
+        only_text_changed = (
+            self._new_text is not None
             and self._font_name is None
+            and self._font_size is None
             and self._color is None
-        ):
+            and self._position is None
+        )
+
+        if only_text_changed:
             # noinspection PyProtectedMember
             result = self._target_obj._client._modify_text_line(
                 self._object_ref, self._new_text
@@ -173,10 +184,46 @@ class TextLineEdit(BaseTextEdit):
             if result.warning:
                 print(f"WARNING: {result.warning}", file=sys.stderr)
             return result
-        else:
+
+        # Position-only change (move operation)
+        only_move = (
+            self._position is not None
+            and self._new_text is None
+            and self._font_name is None
+            and self._font_size is None
+            and self._color is None
+        )
+
+        if only_move:
+            page_index = (
+                self._object_ref.position.page_index
+                if self._object_ref.position
+                else None
+            )
+            if page_index is None:
+                raise ValidationException(
+                    "Text line position must include a page index to move"
+                )
+
+            # Extract x, y from self._position
+            x = self._position.x()
+            y = self._position.y()
+            if x is None or y is None:
+                raise ValidationException("Position must have x and y coordinates")
+
+            position = Position.at_page_coordinates(page_index, x, y)
             # noinspection PyProtectedMember
-            # return self._target_obj._client._modify_text_line(self._object_ref, new_textline)
-            raise UnsupportedOperation("Full TextLineEdit not implemented - TODO")
+            result = self._target_obj._client._move(self._object_ref, position)
+            return result
+
+        # Text lines with font/color styling changes are not supported by the PDF API
+        # Text lines are components of paragraphs and can only have their text modified
+        # or be moved, but not have their styling changed independently
+        raise UnsupportedOperation(
+            "Text lines can only have their text content modified or be moved. "
+            "Font and color changes are not supported for individual text lines. "
+            "To modify text styling, please modify the parent paragraph instead."
+        )
 
 
 class ParagraphObject(PDFObjectBase):

{pdfdancer_client_python-0.2.25.dist-info → pdfdancer_client_python-0.2.27.dist-info}/METADATA

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

pdfdancer_client_python-0.2.27.dist-info/RECORD

@@ -0,0 +1,17 @@
+pdfdancer/__init__.py,sha256=DkDPiTq-u5FWGpD5FHFXpAvZ7em79_PWauQgtE5VLIw,2427
+pdfdancer/exceptions.py,sha256=mJacmUJTPGUsB8Bo_FgfeXYkvZkH5OPJCVBfilBVmQo,2058
+pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
+pdfdancer/image_builder.py,sha256=MdSvZYU7-tq5HcuIpj2cfsd1iJKL9nryp87pCGlMnpM,1888
+pdfdancer/models.py,sha256=Ml1eS6u8A16W0xQAdkX7h7nLFwNRMHg5HzwBoIOKz8U,50663
+pdfdancer/page_builder.py,sha256=ecEK0lXk-7CoWEDOftZ-GwgRfNu5h7AD_J__LNkxJwI,3092
+pdfdancer/paragraph_builder.py,sha256=yXdn2hoxpJYcUVAmSEOgoq-ApGIe9k9GWkokIIQWIJA,20489
+pdfdancer/path_builder.py,sha256=2w0LPJo1u8bSjGAbYevTtOF4VD8M9B4SLe_wSLIYJx8,23917
+pdfdancer/pdfdancer_v1.py,sha256=gaI9oDq8lksEi4DJAiZNebnj5XVFB8lYtGFw-ziTZTw,119130
+pdfdancer/text_line_builder.py,sha256=74zc9wDPtSngHVGz_ykB3Bci_rEcwLr0dXGSEbLH5eo,10262
+pdfdancer/types.py,sha256=ghIGh1zVkLDvSYQuHpvBP6WPB5YGclXdLbZ9d2FLf_I,15010
+pdfdancer_client_python-0.2.27.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pdfdancer_client_python-0.2.27.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
+pdfdancer_client_python-0.2.27.dist-info/METADATA,sha256=Ay5WpYTSKzwGjSJFGXuGC4K9MAYMxazRjC_4n29zJ1Y,24729
+pdfdancer_client_python-0.2.27.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.27.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.27.dist-info/RECORD,,

pdfdancer_client_python-0.2.25.dist-info/RECORD

@@ -1,16 +0,0 @@
-pdfdancer/__init__.py,sha256=8E5dsMRws_zZZpM0i8k3zc34wHauCFZOuVa5BkumuBE,2357
-pdfdancer/exceptions.py,sha256=mJacmUJTPGUsB8Bo_FgfeXYkvZkH5OPJCVBfilBVmQo,2058
-pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
-pdfdancer/image_builder.py,sha256=MdSvZYU7-tq5HcuIpj2cfsd1iJKL9nryp87pCGlMnpM,1888
-pdfdancer/models.py,sha256=feEZc7kr5aN2QgIHpayCWksPLhxJVnukkFfe_Ri1E_w,49003
-pdfdancer/page_builder.py,sha256=ecEK0lXk-7CoWEDOftZ-GwgRfNu5h7AD_J__LNkxJwI,3092
-pdfdancer/paragraph_builder.py,sha256=yXdn2hoxpJYcUVAmSEOgoq-ApGIe9k9GWkokIIQWIJA,20489
-pdfdancer/path_builder.py,sha256=2w0LPJo1u8bSjGAbYevTtOF4VD8M9B4SLe_wSLIYJx8,23917
-pdfdancer/pdfdancer_v1.py,sha256=pjNwBHF_tPCXv7fnjxcm-6m5g_u91773rtvz9j_W9Yg,118088
-pdfdancer/types.py,sha256=9F5LqgNVz48s0Q6lGgOcIfIbvE3vkPI_Vr4fOQqFk2k,13225
-pdfdancer_client_python-0.2.25.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-pdfdancer_client_python-0.2.25.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
-pdfdancer_client_python-0.2.25.dist-info/METADATA,sha256=8N-JlJX5sli-sPJ4OhMnW7faak3mu_y0U4sy5Ynjp7I,24729
-pdfdancer_client_python-0.2.25.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.25.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.25.dist-info/RECORD,,