pdfdancer-client-python 0.2.20__py3-none-any.whl → 0.2.21__py3-none-any.whl

pdfdancer/models.py

@@ -196,6 +196,7 @@ class ObjectType(Enum):
     RADIO_BUTTON = "RADIO_BUTTON"
     BUTTON = "BUTTON"
     DROPDOWN = "DROPDOWN"
+    TEXT_ELEMENT = "TEXT_ELEMENT"
 
 
 class PositionMode(Enum):
@@ -659,6 +660,34 @@ class Image:
         self.position = position
 
 
+@dataclass
+class TextLine:
+    """
+    One line of text to add to a page.
+
+    Parameters:
+    - position: Anchor position where the first line begins.
+    - text: the text
+      provide separate entries for multiple lines.
+    - font: Font to use for all text elements unless overridden later.
+    - color: Text color.
+
+    """
+    position: Optional[Position] = None
+    font: Optional[Font] = None
+    color: Optional[Color] = None
+    line_spacing: float = 1.2
+    text: str = ""
+
+    def get_position(self) -> Optional[Position]:
+        """Returns the position of this paragraph."""
+        return self.position
+
+    def set_position(self, position: Position) -> None:
+        """Sets the position of this paragraph."""
+        self.position = position
+
+
 @dataclass
 class Paragraph:
     """
@@ -687,10 +716,11 @@ class Paragraph:
     ```
     """
     position: Optional[Position] = None
-    text_lines: Optional[List[str]] = None
+    text_lines: Optional[List[TextLine]] = None
     font: Optional[Font] = None
     color: Optional[Color] = None
     line_spacing: float = 1.2
+    line_spacings: Optional[List[float]] = None
 
     def get_position(self) -> Optional[Position]:
         """Returns the position of this paragraph."""
@@ -700,6 +730,34 @@ class Paragraph:
         """Sets the position of this paragraph."""
         self.position = position
 
+    def clear_lines(self) -> None:
+        """Removes all text lines from this paragraph."""
+        self.text_lines = []
+
+    def add_line(self, text_line: TextLine) -> None:
+        """Appends a text line to this paragraph."""
+        if self.text_lines is None:
+            self.text_lines = []
+        self.text_lines.append(text_line)
+
+    def get_lines(self) -> List[TextLine]:
+        """Returns the list of text lines, defaulting to an empty list."""
+        if self.text_lines is None:
+            self.text_lines = []
+        return self.text_lines
+
+    def set_lines(self, lines: List[TextLine]) -> None:
+        """Replaces the current text lines with the provided list."""
+        self.text_lines = list(lines)
+
+    def set_line_spacings(self, spacings: Optional[List[float]]) -> None:
+        """Sets the per-line spacing factors for this paragraph."""
+        self.line_spacings = list(spacings) if spacings else None
+
+    def get_line_spacings(self) -> Optional[List[float]]:
+        """Returns the per-line spacing factors if present."""
+        return list(self.line_spacings) if self.line_spacings else None
+
 
 # Request classes for API communication
 @dataclass
@@ -900,7 +958,7 @@ class AddRequest:
     def _object_to_dict(self, obj: Any) -> dict:
         """Convert PDF object to dictionary for JSON serialization."""
         import base64
-        from .models import Path as PathModel, Line, Bezier, PathSegment
+        from .models import Path as PathModel
 
         if isinstance(obj, PathModel):
             # Serialize Path object
@@ -935,37 +993,55 @@ class AddRequest:
                 "data": data_b64
             }
         elif isinstance(obj, Paragraph):
-            # Build lines -> List<TextLine> with minimal structure required by server
-            lines = []
+            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
+
+            lines_payload = []
             if obj.text_lines:
                 for line in obj.text_lines:
+                    if isinstance(line, TextLine):
+                        line_text = line.text
+                        line_font = line.font or obj.font
+                        line_color = line.color or obj.color
+                        line_position = line.position or obj.position
+                    else:
+                        line_text = str(line)
+                        line_font = obj.font
+                        line_color = obj.color
+                        line_position = obj.position
+
                     text_element = {
-                        "text": line,
-                        "font": {"name": obj.font.name, "size": obj.font.size} if obj.font else None,
-                        "color": {"red": obj.color.r, "green": obj.color.g, "blue": obj.color.b,
-                                  "alpha": obj.color.a} if obj.color else None,
-                        "position": FindRequest._position_to_dict(obj.position) if obj.position else None
+                        "text": line_text,
+                        "font": _font_to_dict(line_font),
+                        "color": _color_to_dict(line_color),
+                        "position": FindRequest._position_to_dict(line_position) if line_position else None
                     }
-                    text_line = {
-                        "textElements": [text_element]
-                    }
-                    # TextLine has color and position
-                    if obj.color:
-                        text_line["color"] = {"red": obj.color.r, "green": obj.color.g, "blue": obj.color.b,
-                                              "alpha": obj.color.a}
-                    if obj.position:
-                        text_line["position"] = FindRequest._position_to_dict(obj.position)
-                    lines.append(text_line)
+                    text_line = {"textElements": [text_element]}
+                    if line_color:
+                        text_line["color"] = _color_to_dict(line_color)
+                    if line_position:
+                        text_line["position"] = FindRequest._position_to_dict(line_position)
+                    lines_payload.append(text_line)
+
             line_spacings = None
-            if hasattr(obj, "line_spacing") and obj.line_spacing is not None:
-                # Server expects a list
+            if getattr(obj, "line_spacings", None):
+                line_spacings = list(obj.line_spacings)
+            elif getattr(obj, "line_spacing", None) is not None:
                 line_spacings = [obj.line_spacing]
+
             return {
                 "type": "PARAGRAPH",
                 "position": FindRequest._position_to_dict(obj.position) if obj.position else None,
-                "lines": lines,
+                "lines": lines_payload if lines_payload else None,
                 "lineSpacings": line_spacings,
-                "font": {"name": obj.font.name, "size": obj.font.size} if obj.font else None
+                "font": _font_to_dict(obj.font)
             }
         else:
             raise ValueError(f"Unsupported object type: {type(obj)}")

pdfdancer/paragraph_builder.py

@@ -1,108 +1,100 @@
 """
 ParagraphBuilder for the PDFDancer Python client.
-Closely mirrors the Java ParagraphBuilder class with Python conventions.
+Mirrors the behaviour of the Java implementation while keeping Python conventions.
 """
 
+from __future__ import annotations
+
+from copy import deepcopy
 from pathlib import Path
-from typing import Optional, Union
+from typing import List, Optional, Union
 
 from . import StandardFonts
 from .exceptions import ValidationException
-from .models import Paragraph, Font, Color, Position
+from .models import (
+    Paragraph,
+    Font,
+    Color,
+    Position,
+    TextLine,
+    TextObjectRef,
+    Point,
+    ObjectRef,
+)
+
+DEFAULT_LINE_SPACING_FACTOR = 1.2
+DEFAULT_TEXT_COLOR = Color(0, 0, 0)
+_DEFAULT_BASE_FONT_SIZE = 12.0
 
 
 class ParagraphBuilder:
     """
-    Builder class for constructing Paragraph objects with fluent interface.
-    Mirrors the Java ParagraphBuilder class exactly.
+    Fluent builder used to assemble `Paragraph` instances.
+    Behaviour is aligned with the Java `ParagraphBuilder` so that mixed client/server
+    scenarios stay predictable.
     """
 
     def __init__(self, client: 'PDFDancer'):
-        """
-        Initialize the paragraph builder with a client reference.
-
-        Args:
-            client: The ClientV1 instance for font registration
-        """
         if client is None:
             raise ValidationException("Client cannot be null")
 
         self._client = client
         self._paragraph = Paragraph()
-        self._line_spacing = 1.2
-        self._text_color = Color(0, 0, 0)  # Black by default
+        self._line_spacing_factor: Optional[float] = None
+        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_paragraph_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)
+            and self._line_spacing_factor is None
+        )
 
     def text(self, text: str, color: Optional[Color] = None) -> 'ParagraphBuilder':
-        """
-        Set the text content for the paragraph.
-        Equivalent to fromString() methods in Java ParagraphBuilder.
-
-        Args:
-            text: The text content for the paragraph
-            color: Optional text color (uses default if not provided)
-
-        Returns:
-            Self for method chaining
-
-        Raises:
-            ValidationException: If text is None or empty
-        """
         if text is None:
             raise ValidationException("Text cannot be null")
-        if not text.strip():
-            raise ValidationException("Text cannot be empty")
-
         self._text = text
         if color is not None:
-            self._text_color = color
-
+            self.color(color)
         return self
 
-    def font(self, font_name: str | StandardFonts, font_size: float) -> 'ParagraphBuilder':
+    def font(
+            self,
+            font: Union[Font, str, StandardFonts],
+            font_size: Optional[float] = None
+    ) -> 'ParagraphBuilder':
         """
-        Set the font for the paragraph using an existing Font object.
-        Equivalent to withFont(Font) in Java ParagraphBuilder.
-
-        Args:
-            font_name: The Font to use
-            font_size: The font size
-
-        Returns:
-            Self for method chaining
-
-        Raises:
-            ValidationException: If font is None
+        Configure the font either by providing a `Font` instance or name + size.
         """
-        # If font_name is an enum member, use its value
-        if isinstance(font_name, StandardFonts):
-            font_name = font_name.value
-
-        font = Font(font_name, font_size)
-        if font is None:
-            raise ValidationException("Font cannot be null")
-
-        self._font = font
-        self._ttf_file = None  # Clear TTF file when using existing font
+        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) -> 'ParagraphBuilder':
-        """
-        Set the font for the paragraph using a TTF file.
-        Equivalent to withFont(File, double) in Java ParagraphBuilder.
-
-        Args:
-            ttf_file: Path to the TTF font file
-            font_size: Size of the font
-
-        Returns:
-            Self for method chaining
-
-        Raises:
-            ValidationException: If TTF file is invalid or font size is not positive
-        """
         if ttf_file is None:
             raise ValidationException("TTF file cannot be null")
         if font_size <= 0:
@@ -110,170 +102,393 @@ class ParagraphBuilder:
 
         ttf_path = Path(ttf_file)
 
-        # Strict validation like Java client
         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 not ttf_path.stat().st_size > 0:
+        if ttf_path.stat().st_size <= 0:
             raise ValidationException(f"TTF file is empty: {ttf_path}")
 
-        # Check file permissions
         try:
-            with open(ttf_path, 'rb') as f:
-                f.read(1)  # Try to read one byte to check readability
-        except (IOError, OSError):
-            raise ValidationException(f"TTF file is not readable: {ttf_path}")
+            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 line_spacing(self, spacing: float) -> 'ParagraphBuilder':
-        """
-        Set the line spacing for the paragraph.
-        Equivalent to withLineSpacing() in Java ParagraphBuilder.
+    def set_font_explicitly_changed(self, changed: bool) -> None:
+        self._font_explicitly_changed = bool(changed)
 
-        Args:
-            spacing: Line spacing value (typically 1.0 to 2.0)
+    def set_original_paragraph_position(self, position: Position) -> None:
+        self._original_paragraph_position = position
+        if position and self._paragraph.get_position() is None:
+            self._paragraph.set_position(deepcopy(position))
 
-        Returns:
-            Self for method chaining
+    def target(self, object_ref: ObjectRef) -> 'ParagraphBuilder':
+        if object_ref is None:
+            raise ValidationException("Object reference cannot be null")
+        self._target_object_ref = object_ref
+        return self
 
-        Raises:
-            ValidationException: If spacing is not positive
-        """
+    def line_spacing(self, spacing: float) -> 'ParagraphBuilder':
         if spacing <= 0:
             raise ValidationException(f"Line spacing must be positive, got {spacing}")
-
-        self._line_spacing = spacing
+        self._line_spacing_factor = spacing
         return self
 
     def color(self, color: Color) -> 'ParagraphBuilder':
-        """
-        Set the text color for the paragraph.
-        Equivalent to withColor() in Java ParagraphBuilder.
-
-        Args:
-            color: The Color object for the text
-
-        Returns:
-            Self for method chaining
-
-        Raises:
-            ValidationException: If color is None
-        """
         if color is None:
             raise ValidationException("Color cannot be null")
-
         self._text_color = color
         return self
 
-    def at(self, page_index: int, x: float, y: float) -> 'ParagraphBuilder':
+    def move_to(self, x: float, y: float) -> 'ParagraphBuilder':
+        """
+        Move the paragraph anchor to new coordinates on the same page.
         """
-        Set the position for the paragraph.
-        Equivalent to withPosition() in Java ParagraphBuilder.
+        position = self._paragraph.get_position()
+        if position is None and self._target_object_ref and self._target_object_ref.position:
+            position = deepcopy(self._target_object_ref.position)
+            self._paragraph.set_position(position)
 
-        Args:
-            position: The Position object for the paragraph
+        if position is None:
+            raise ValidationException("Cannot move paragraph without an existing position")
 
-        Returns:
-            Self for method chaining
+        page_index = position.page_index
+        if page_index is None:
+            raise ValidationException("Paragraph position must include a page index to move")
 
-        Raises:
-            ValidationException: If position is None
-        """
-        position = Position.at_page_coordinates(page_index, x, y)
+        self._position_changed = True
+        return self.at(page_index, x, y)
+
+    def at_position(self, position: Position) -> 'ParagraphBuilder':
         if position is None:
             raise ValidationException("Position cannot be null")
+        # Defensive copy so builder mutations do not alter original references
+        self._paragraph.set_position(deepcopy(position))
+        self._position_changed = True
+        return self
 
-        self._paragraph.set_position(position)
+    def at(self, page_index: int, x: float, y: float) -> 'ParagraphBuilder':
+        return self.at_position(Position.at_page_coordinates(page_index, x, y))
+
+    def add_text_line(self, text_line: Union[TextLine, TextObjectRef, str]) -> 'ParagraphBuilder':
+        self._paragraph.add_line(self._coerce_text_line(text_line))
         return self
 
-    def _build(self) -> Paragraph:
-        """
-        Build and return the final Paragraph object.
-        Equivalent to build() in Java ParagraphBuilder.
+    def get_text(self) -> Optional[str]:
+        return self._text
 
-        This method validates all required fields and constructs the final paragraph
-        with text processing similar to ParagraphUtil.finalizeText() in Java.
+    def add(self) -> bool:
+        # noinspection PyProtectedMember
+        return self._client._add_paragraph(self._finalize_paragraph())
 
-        Returns:
-            The constructed Paragraph object
+    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 paragraph")
 
-        Raises:
-            ValidationException: If required fields are missing or invalid
-        """
-        # Validate required fields
-        if self._text is None:
-            raise ValidationException("Text must be set before building paragraph")
-        if self._font is None:
-            raise ValidationException("Font must be set before building paragraph")
+        if self.only_text_changed():
+            # Backend accepts plain text updates for simple edits
+            return self._client._modify_paragraph(target_ref, self._text or "")
+
+        paragraph = self._finalize_paragraph()
+        return self._client._modify_paragraph(target_ref, paragraph)
+
+    # ------------------------------------------------------------------ #
+    # Internal helpers
+    # ------------------------------------------------------------------ #
+
+    def _finalize_paragraph(self) -> Paragraph:
         if self._paragraph.get_position() is None:
             raise ValidationException("Position must be set before building paragraph")
 
-        # Set paragraph properties
-        self._paragraph.font = self._font
-        self._paragraph.color = self._text_color
-        self._paragraph.line_spacing = self._line_spacing
-
-        # Process text into lines (simplified version of ParagraphUtil.finalizeText)
-        # In the full implementation, this would handle text wrapping, line breaks, etc.
-        self._paragraph.text_lines = self._process_text_lines(self._text)
+        if self._target_object_ref is None and self._font is None and self._paragraph.font is None:
+            raise ValidationException("Font must be set before building paragraph")
 
+        if self._text is not None:
+            self._finalize_lines_from_text()
+        elif not self._paragraph.text_lines:
+            raise ValidationException("Either text must be provided or existing lines supplied")
+        else:
+            self._finalize_existing_lines()
+
+        self._reposition_lines()
+
+        should_skip_lines = (
+            self._position_changed
+            and self._text is None
+            and self._text_color is None
+            and (self._font is None or not self._font_explicitly_changed)
+            and self._line_spacing_factor is None
+        )
+        if should_skip_lines:
+            self._paragraph.text_lines = None
+            self._paragraph.set_line_spacings(None)
+
+        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._paragraph.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
+        self._paragraph.color = final_color
         return self._paragraph
 
-    def _register_ttf(self, ttf_file: Path, font_size: float) -> Font:
-        """
-        Register a TTF font with the client and return a Font object.
-        Equivalent to registerTTF() private method in Java ParagraphBuilder.
-
-        Args:
-            ttf_file: Path to the TTF font file
-            font_size: Size of the font
+    def _finalize_lines_from_text(self) -> None:
+        base_font = self._font or self._original_font
+        base_color = self._text_color or self._original_color or DEFAULT_TEXT_COLOR
+        color = base_color
+
+        if self._line_spacing_factor is not None:
+            spacing = self._line_spacing_factor
+        else:
+            existing_spacings = self._paragraph.get_line_spacings()
+            if existing_spacings:
+                spacing = existing_spacings[0]
+            elif self._paragraph.line_spacing:
+                spacing = self._paragraph.line_spacing
+            else:
+                spacing = DEFAULT_LINE_SPACING_FACTOR
+
+        self._paragraph.clear_lines()
+        lines: List[TextLine] = []
+        for index, line_text in enumerate(self._split_text(self._text or "")):
+            line_position = self._calculate_line_position(index, spacing)
+            lines.append(
+                TextLine(
+                    position=line_position,
+                    font=base_font,
+                    color=color,
+                    line_spacing=spacing,
+                    text=line_text,
+                )
+            )
+        self._paragraph.set_lines(lines)
+        self._paragraph.set_line_spacings([spacing] * (len(lines) - 1) if len(lines) > 1 else None)
+        self._paragraph.line_spacing = spacing
+
+    def _finalize_existing_lines(self) -> None:
+        lines = self._paragraph.text_lines or []
+        spacing_override = self._line_spacing_factor
+        spacing_for_calc = spacing_override
+
+        if spacing_for_calc is None:
+            existing_spacings = self._paragraph.get_line_spacings()
+            if existing_spacings:
+                spacing_for_calc = existing_spacings[0]
+        if spacing_for_calc is None:
+            spacing_for_calc = self._paragraph.line_spacing or DEFAULT_LINE_SPACING_FACTOR
+
+        updated_lines: List[TextLine] = []
+        for index, line in enumerate(lines):
+            if isinstance(line, TextLine):
+                if spacing_override is not None:
+                    line.line_spacing = spacing_override
+                if self._text_color is not None:
+                    line.color = self._text_color
+                if self._font is not None and self._font_explicitly_changed:
+                    line.font = self._font
+                updated_lines.append(line)
+            else:
+                line_position = self._calculate_line_position(index, spacing_for_calc)
+                updated_lines.append(
+                    TextLine(
+                        position=line_position,
+                        font=self._font if self._font is not None else self._original_font,
+                        color=self._text_color or self._original_color or DEFAULT_TEXT_COLOR,
+                        line_spacing=spacing_override if spacing_override is not None else spacing_for_calc,
+                        text=str(line),
+                    )
+                )
+
+        self._paragraph.set_lines(updated_lines)
+
+        if spacing_override is not None:
+            self._paragraph.set_line_spacings(
+                [spacing_override] * (len(updated_lines) - 1) if len(updated_lines) > 1 else None
+            )
+            self._paragraph.line_spacing = spacing_override
+
+
+    def _reposition_lines(self) -> None:
+        if self._text is not None:
+            # Newly generated text lines already align with the updated paragraph position.
+            return
+        paragraph_pos = self._paragraph.get_position()
+        lines = self._paragraph.text_lines or []
+        if not paragraph_pos or not lines:
+            return
+
+        base_position = self._original_paragraph_position
+        if base_position is None:
+            for line in lines:
+                if isinstance(line, TextLine) and line.position is not None:
+                    base_position = line.position
+                    break
+
+        if base_position is None:
+            return
+
+        target_x = paragraph_pos.x()
+        target_y = paragraph_pos.y()
+        base_x = base_position.x()
+        base_y = base_position.y()
+        if None in (target_x, target_y, base_x, base_y):
+            return
+
+        dx = target_x - base_x
+        dy = target_y - base_y
+        if dx == 0 and dy == 0:
+            return
+
+        for line in lines:
+            if isinstance(line, TextLine) and line.position is not None:
+                current_x = line.position.x()
+                current_y = line.position.y()
+                if current_x is None or current_y is None:
+                    continue
+                line.position.at_coordinates(Point(current_x + dx, current_y + dy))
+
+    def _coerce_text_line(self, source: Union[TextLine, TextObjectRef, str]) -> TextLine:
+        if isinstance(source, TextLine):
+            return source
+
+        if isinstance(source, TextObjectRef):
+            font = None
+            if source.font_name and source.font_size:
+                font = Font(source.font_name, source.font_size)
+            elif getattr(source, "children", None):
+                for child in source.children:
+                    if child.font_name and child.font_size:
+                        font = Font(child.font_name, child.font_size)
+                        break
+            if font is None:
+                font = self._original_font
+
+            spacing = self._line_spacing_factor
+            if spacing is None and source.line_spacings:
+                spacing = source.line_spacings[0]
+            if spacing is None:
+                spacing = self._paragraph.line_spacing or DEFAULT_LINE_SPACING_FACTOR
+
+            color = source.color or self._original_color
+
+            line = TextLine(
+                position=deepcopy(source.position) if source.position else None,
+                font=font,
+                color=color,
+                line_spacing=spacing,
+                text=source.text or "",
+            )
+            if self._original_font is None and font is not None:
+                self._original_font = font
+            if self._original_color is None and color is not None:
+                self._original_color = color
+            return line
+
+        if isinstance(source, str):
+            current_index = len(self._paragraph.get_lines())
+            spacing = self._line_spacing_factor if self._line_spacing_factor is not None else (
+                self._paragraph.line_spacing or DEFAULT_LINE_SPACING_FACTOR
+            )
+            line_position = self._calculate_line_position(current_index, spacing)
+            return TextLine(
+                position=line_position,
+                font=self._font or self._original_font,
+                color=self._text_color or self._original_color or DEFAULT_TEXT_COLOR,
+                line_spacing=spacing,
+                text=source,
+            )
+
+        raise ValidationException(f"Unsupported text line type: {type(source)}")
+
+    def _split_text(self, text: str) -> List[str]:
+        processed = text.replace('\r\n', '\n').replace('\r', '\n').replace('\\n', '\n')
+        parts = processed.split('\n')
+        while parts and parts[-1] == '':
+            parts.pop()
+        if not parts:
+            parts = ['']
+        return parts
+
+    def _calculate_line_position(self, line_index: int, spacing_factor: float) -> Optional[Position]:
+        paragraph_position = self._paragraph.get_position()
+        if paragraph_position is None:
+            return None
+
+        page_index = paragraph_position.page_index
+        base_x = paragraph_position.x()
+        base_y = paragraph_position.y()
+        if page_index is None or base_x is None or base_y is None:
+            return None
+
+        offset = line_index * self._calculate_baseline_distance(spacing_factor)
+        return Position.at_page_coordinates(page_index, base_x, base_y + offset)
+
+    def _calculate_baseline_distance(self, spacing_factor: float) -> float:
+        factor = spacing_factor if spacing_factor > 0 else DEFAULT_LINE_SPACING_FACTOR
+        return self._baseline_font_size() * factor
+
+    def _baseline_font_size(self) -> float:
+        if self._font and self._font.size:
+            return self._font.size
+        if self._original_font and self._original_font.size:
+            return self._original_font.size
+        return _DEFAULT_BASE_FONT_SIZE
 
-        Returns:
-            Font object with the registered font name and size
-        """
+    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 e:
-            raise ValidationException(f"Failed to register font file {ttf_file}: {e}")
+        except Exception as exc:
+            raise ValidationException(f"Failed to register font file {ttf_file}: {exc}") from exc
 
-    def _process_text_lines(self, text: str) -> list[str]:
+    def _build(self) -> Paragraph:
+        """
+        Backwards-compatible alias for callers that invoked the previous `_build`.
         """
-        Process text into lines for the paragraph.
-        This is a simplified version - the full implementation would handle
-        word wrapping, line breaks, and other text formatting based on the font
-        and paragraph width.
+        return self._finalize_paragraph()
 
-        Args:
-            text: The input text to process
+    @classmethod
+    def from_object_ref(cls, client: 'PDFDancer', object_ref: TextObjectRef) -> 'ParagraphBuilder':
+        if object_ref is None:
+            raise ValidationException("Object reference cannot be null")
 
-        Returns:
-            List of text lines for the paragraph
-        """
-        # Handle escaped newlines (\\n) as actual newlines
-        processed_text = text.replace('\\n', '\n')
+        builder = cls(client)
+        builder.target(object_ref)
 
-        # Simple implementation - split on newlines
-        # In the full version, this would implement proper text layout
-        lines = processed_text.split('\n')
+        if object_ref.position:
+            builder.at_position(object_ref.position)
+            builder.set_original_paragraph_position(object_ref.position)
 
-        # Remove empty lines at the end but preserve intentional line breaks
-        while lines and not lines[-1].strip():
-            lines.pop()
+        if object_ref.line_spacings:
+            builder._paragraph.set_line_spacings(object_ref.line_spacings)
+            builder._paragraph.line_spacing = object_ref.line_spacings[0] if object_ref.line_spacings else builder._paragraph.line_spacing
 
-        # Ensure at least one line
-        if not lines:
-            lines = ['']
+        if object_ref.font_name and object_ref.font_size:
+            builder._original_font = Font(object_ref.font_name, object_ref.font_size)
 
-        return lines
+        if object_ref.color:
+            builder._original_color = object_ref.color
 
-    def add(self):
-        # noinspection PyProtectedMember
-        return self._client._add_paragraph(self._build())
+        if object_ref.children:
+            for child in object_ref.children:
+                builder.add_text_line(child)
+        elif object_ref.text:
+            for segment in object_ref.text.split('\n'):
+                builder.add_text_line(segment)
+
+        return builder
 
 
 class ParagraphPageBuilder(ParagraphBuilder):

pdfdancer/pdfdancer_v1.py

@@ -7,6 +7,7 @@ Provides session-based PDF manipulation operations with strict validation.
 
 import gzip
 import json
+import logging
 import os
 import time
 from datetime import datetime, timezone
@@ -127,7 +128,8 @@ from .exceptions import (
 from .image_builder import ImageBuilder, ImageOnPageBuilder
 from .models import (
     ObjectRef, Position, ObjectType, Font, Image, Paragraph, FormFieldRef, TextObjectRef, PageRef,
-    FindRequest, DeleteRequest, MoveRequest, PageMoveRequest, AddPageRequest, AddRequest, ModifyRequest, ModifyTextRequest,
+    FindRequest, DeleteRequest, MoveRequest, PageMoveRequest, AddPageRequest, AddRequest, ModifyRequest,
+    ModifyTextRequest,
     ChangeFormFieldRequest, CommandResult,
     ShapeType, PositionMode, PageSize, Orientation,
     PageSnapshot, DocumentSnapshot, FontRecommendation, FontType
@@ -1850,11 +1852,14 @@ class PDFDancer:
             status=status
         )
 
-        if isinstance(obj_data.get('children'), list) and len(obj_data['children']) > 0:
-            text_object.children = [
-                self._parse_text_object_ref(child_data, f"{internal_id or 'child'}-{index}")
-                for index, child_data in enumerate(obj_data['children'])
-            ]
+        try:
+            if isinstance(obj_data.get('children'), list) and len(obj_data['children']) > 0:
+                text_object.children = [
+                    self._parse_text_object_ref(child_data, f"{internal_id or 'child'}-{index}")
+                    for index, child_data in enumerate(obj_data['children'])
+                ]
+        except ValueError as e:
+            logging.exception(f"Failed to parse children of {internal_id}", e)
 
         return text_object
 
@@ -1997,7 +2002,7 @@ class PDFDancer:
             even_odd_fill=even_odd_fill
         )
 
-    def _parse_font_recommendation(self, data: dict) -> FontRecommendation:
+    def _parse_document_font_info(self, data: dict) -> FontRecommendation:
         """Parse JSON data into FontRecommendation instance."""
         font_type_str = data.get('fontType', 'SYSTEM')
         font_type = FontType(font_type_str)
@@ -2054,7 +2059,7 @@ class PDFDancer:
     def _parse_document_snapshot(self, data: dict) -> DocumentSnapshot:
         """Parse JSON data into DocumentSnapshot instance."""
         page_count = data.get('pageCount', 0)
-        fonts = [self._parse_font_recommendation(font_data) for font_data in data.get('fonts', [])]
+        fonts = [self._parse_document_font_info(font_data) for font_data in data.get('fonts', [])]
         pages = [self._parse_page_snapshot(page_data) for page_data in data.get('pages', [])]
 
         return DocumentSnapshot(

pdfdancer/types.py

@@ -1,12 +1,10 @@
 from __future__ import annotations
 
-import statistics
 import sys
 from dataclasses import dataclass
-from typing import Optional, List
+from typing import Optional
 
-from . import ObjectType, Position, ObjectRef, Point, Paragraph, Font, Color, FormFieldRef, TextObjectRef
-from .models import CommandResult
+from . import ObjectType, Position, ObjectRef, Point, FormFieldRef, TextObjectRef
 
 
 @dataclass
@@ -95,41 +93,6 @@ class FormObject(PDFObjectBase):
                 self.position == other.position)
 
 
-def _process_text_lines(text: str) -> List[str]:
-    """
-    Process text into lines for the paragraph.
-    This is a simplified version - the full implementation would handle
-    word wrapping, line breaks, and other text formatting based on the font
-    and paragraph width. TODO
-
-    Args:
-        text: The input text to process
-
-    Returns:
-        List of text lines for the paragraph
-    """
-    # Handle escaped newlines (\\n) as actual newlines
-    processed_text = text.replace('\\n', '\n')
-
-    # Simple implementation - split on newlines
-    # In the full version, this would implement proper text layout
-    lines = processed_text.split('\n')
-
-    # Remove empty lines at the end but preserve intentional line breaks
-    while lines and not lines[-1].strip():
-        lines.pop()
-
-    # Ensure at least one line
-    if not lines:
-        lines = ['']
-
-    return lines
-
-
-DEFAULT_LINE_SPACING = 1.2
-DEFAULT_COLOR = Color(0, 0, 0)
-
-
 class BaseTextEdit:
     """Common base for text-like editable objects (Paragraph, TextLine, etc.)"""
 
@@ -178,68 +141,6 @@ class BaseTextEdit:
         raise NotImplementedError("Subclasses must implement apply()")
 
 
-class ParagraphEdit(BaseTextEdit):
-    def apply(self) -> CommandResult:
-        if (
-                self._position is None
-                and self._line_spacing is None
-                and self._font_size is None
-                and self._font_name is None
-                and self._color is None
-        ):
-            # noinspection PyProtectedMember
-            result = self._target_obj._client._modify_paragraph(self._object_ref, self._new_text)
-            if result.warning:
-                print(f"WARNING: {result.warning}", file=sys.stderr)
-            return result
-        else:
-            new_paragraph = Paragraph(
-                position=self._position if self._position is not None else self._object_ref.position,
-                line_spacing=self._get_line_spacing(),
-                font=self._get_font(),
-                text_lines=self._get_text_lines(),
-                color=self._get_color(),
-            )
-            # noinspection PyProtectedMember
-            result = self._target_obj._client._modify_paragraph(self._object_ref, new_paragraph)
-            if result.warning:
-                print(f"WARNING: {result.warning}", file=sys.stderr)
-            return result
-
-    def _get_line_spacing(self) -> float:
-        if self._line_spacing is not None:
-            return self._line_spacing
-        elif self._object_ref.line_spacings is not None:
-            return statistics.mean(self._object_ref.line_spacings)
-        else:
-            return DEFAULT_LINE_SPACING
-
-    def _get_font(self):
-        if self._font_name is not None and self._font_size is not None:
-            return Font(name=self._font_name, size=self._font_size)
-        elif self._object_ref.font_name is not None and self._object_ref.font_size is not None:
-            return Font(name=self._object_ref.font_name, size=self._object_ref.font_size)
-        else:
-            raise Exception("Font is none")
-
-    def _get_text_lines(self):
-        if self._new_text is not None:
-            return _process_text_lines(self._new_text)
-        elif self._object_ref.text is not None:
-            # TODO this actually messes up existing text line internals
-            return _process_text_lines(self._object_ref.text)
-        else:
-            raise Exception("Paragraph has no text")
-
-    def _get_color(self):
-        if self._color is not None:
-            return self._color
-        elif self._object_ref.color is not None:
-            return self._object_ref.color
-        else:
-            return DEFAULT_COLOR
-
-
 class TextLineEdit(BaseTextEdit):
     def apply(self) -> bool:
         if (
@@ -273,8 +174,8 @@ class ParagraphObject(PDFObjectBase):
         """
         return getattr(self._object_ref, name)
 
-    def edit(self) -> ParagraphEdit:
-        return ParagraphEdit(self, self.object_ref())
+    def edit(self):
+        return ParagraphEditSession(self._client, self.object_ref())
 
     def object_ref(self) -> TextObjectRef:
         return self._object_ref
@@ -320,6 +221,114 @@ class TextLineObject(PDFObjectBase):
                 self._object_ref.children == other._object_ref.children)
 
 
+class ParagraphEditSession:
+    """
+    Fluent editing helper that reuses ParagraphBuilder for modifications while preserving
+    the legacy context-manager workflow (replace/font/color/etc.).
+    """
+
+    def __init__(self, client: 'PDFDancer', object_ref: TextObjectRef):
+        self._client = client
+        self._object_ref = object_ref
+        self._new_text = None
+        self._font_name = None
+        self._font_size = None
+        self._color = None
+        self._line_spacing = None
+        self._new_position = None
+        self._has_changes = False
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_type:
+            return False
+        self.apply()
+        return False
+
+    def replace(self, text: str):
+        self._new_text = text
+        self._has_changes = True
+        return self
+
+    def font(self, font_name, font_size: float):
+        self._font_name = font_name
+        self._font_size = font_size
+        self._has_changes = True
+        return self
+
+    def color(self, color):
+        self._color = color
+        self._has_changes = True
+        return self
+
+    def line_spacing(self, spacing: float):
+        self._line_spacing = spacing
+        self._has_changes = True
+        return self
+
+    def move_to(self, x: float, y: float):
+        self._new_position = (x, y)
+        self._has_changes = True
+        return self
+
+    def apply(self):
+        if not self._has_changes:
+            return self._client._modify_paragraph(self._object_ref, None)
+
+        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._line_spacing is None and
+            self._new_position is None
+        )
+
+        if only_text_changed:
+            result = self._client._modify_paragraph(self._object_ref, self._new_text)
+            self._has_changes = False
+            return result
+
+        only_move = (
+            self._new_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 and
+            self._line_spacing 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("Paragraph position must include a page index to move")
+            position = Position.at_page_coordinates(page_index, *self._new_position)
+            result = self._client._move(self._object_ref, position)
+            self._has_changes = False
+            return result
+
+        from .paragraph_builder import ParagraphBuilder
+
+        builder = ParagraphBuilder.from_object_ref(self._client, self._object_ref)
+
+        if self._new_text is not None:
+            builder.text(self._new_text)
+        if self._font_name is not None and self._font_size is not None:
+            builder.font(self._font_name, self._font_size)
+        if self._color is not None:
+            builder.color(self._color)
+        if self._line_spacing is not None:
+            builder.line_spacing(self._line_spacing)
+        if self._new_position is not None:
+            builder.move_to(*self._new_position)
+
+        result = builder.modify(self._object_ref)
+        self._has_changes = False
+        return result
+
+
 class FormFieldEdit:
     def __init__(self, form_field: 'FormFieldObject', object_ref: FormFieldRef):
         self.form_field = form_field

{pdfdancer_client_python-0.2.20.dist-info → pdfdancer_client_python-0.2.21.dist-info}/METADATA

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

pdfdancer_client_python-0.2.21.dist-info/RECORD

@@ -0,0 +1,16 @@
+pdfdancer/__init__.py,sha256=NKvSJY10p4TCc4uRC9wkDnkYJdvSdm2ry_D-fBgGtX8,2207
+pdfdancer/exceptions.py,sha256=WAcyTacykJwjiaURrQamEgizLxv0vSlSio6NMikg4D0,1558
+pdfdancer/fingerprint.py,sha256=Ue5QzpqsKlbYefvKU0ULV4NgMU3AOTcseeV9HfiPJXI,3093
+pdfdancer/image_builder.py,sha256=ee-y7IzjZqpMN8O8ZzEm8-lOnOnqoQ7LQTzVWg4mHWg,1760
+pdfdancer/models.py,sha256=vxxDiZ7db3NOcYNZCgLJL_N5y_y8Y0mVMZjt9fEuXgs,48204
+pdfdancer/page_builder.py,sha256=HiMEPYWhaIWS9dZ1jxIA-XIeAwgJVXMoEAYsm3TxOt8,2969
+pdfdancer/paragraph_builder.py,sha256=TDBxUd72IVC2uupmOk41nrna_8y5FXzQ2XIjyugAPF0,19634
+pdfdancer/path_builder.py,sha256=G5vpVAH9OB3zV5gaSA0MKWIygmieVhwQ8dxnt_hgF7A,23693
+pdfdancer/pdfdancer_v1.py,sha256=UnSMjQmJ6wGTi_G_E1Jn7f1qdaZb8cPZYCZ4xwdudMw,88861
+pdfdancer/types.py,sha256=wmbmLLioNWwk4vxJc2EWuA16R0pGHlGU07TS-WjViF0,12585
+pdfdancer_client_python-0.2.21.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pdfdancer_client_python-0.2.21.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
+pdfdancer_client_python-0.2.21.dist-info/METADATA,sha256=Jo-0PNQmuLLFD94s-7kVHcp9LxqXmnyrSUjuiQP6sXo,24668
+pdfdancer_client_python-0.2.21.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.21.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.21.dist-info/RECORD,,

pdfdancer_client_python-0.2.20.dist-info/RECORD

@@ -1,16 +0,0 @@
-pdfdancer/__init__.py,sha256=NKvSJY10p4TCc4uRC9wkDnkYJdvSdm2ry_D-fBgGtX8,2207
-pdfdancer/exceptions.py,sha256=WAcyTacykJwjiaURrQamEgizLxv0vSlSio6NMikg4D0,1558
-pdfdancer/fingerprint.py,sha256=Ue5QzpqsKlbYefvKU0ULV4NgMU3AOTcseeV9HfiPJXI,3093
-pdfdancer/image_builder.py,sha256=ee-y7IzjZqpMN8O8ZzEm8-lOnOnqoQ7LQTzVWg4mHWg,1760
-pdfdancer/models.py,sha256=uyVYlswBUcHMSXSRjeQOa9WBc2tJU3-Q6nKquwlbT2c,45712
-pdfdancer/page_builder.py,sha256=HiMEPYWhaIWS9dZ1jxIA-XIeAwgJVXMoEAYsm3TxOt8,2969
-pdfdancer/paragraph_builder.py,sha256=x5XhPo-GUeovQuGbrH7MyyenITcy6in7bz6CD9r-ZqU,9458
-pdfdancer/path_builder.py,sha256=G5vpVAH9OB3zV5gaSA0MKWIygmieVhwQ8dxnt_hgF7A,23693
-pdfdancer/pdfdancer_v1.py,sha256=WMRdxQwpfnOvotsaP6jVcLw1_TYe4XG7M0AAoWeSkdo,88700
-pdfdancer/types.py,sha256=fMYNmT73ism5bN8ij8G8hELKWQA8-8o7AlIX6YFcSEw,12652
-pdfdancer_client_python-0.2.20.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-pdfdancer_client_python-0.2.20.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
-pdfdancer_client_python-0.2.20.dist-info/METADATA,sha256=vup4o7ROABx7YHuxTlA1oSlmg3KYS9Oarl9rOELaj4g,24668
-pdfdancer_client_python-0.2.20.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.20.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.20.dist-info/RECORD,,