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

pdfdancer/path_builder.py

@@ -154,6 +154,38 @@ class PathBuilder:
         self._segments.append(bezier)
         return self
 
+    def add_rectangle(self, x: float, y: float, width: float, height: float) -> 'PathBuilder':
+        """
+        Convenient method to add a rectangle as four line segments to the path.
+
+        Args:
+            x: X coordinate of bottom-left corner
+            y: Y coordinate of bottom-left corner
+            width: Rectangle width
+            height: Rectangle height
+
+        Returns:
+            Self for method chaining
+        """
+        if width <= 0:
+            raise ValidationException("Rectangle width must be positive")
+        if height <= 0:
+            raise ValidationException("Rectangle height must be positive")
+
+        # Create rectangle as 4 line segments (clockwise from bottom-left)
+        bottom_left = Point(x, y)
+        bottom_right = Point(x + width, y)
+        top_right = Point(x + width, y + height)
+        top_left = Point(x, y + height)
+
+        # Add four lines forming the rectangle
+        self.add_line(bottom_left, bottom_right)
+        self.add_line(bottom_right, top_right)
+        self.add_line(top_right, top_left)
+        self.add_line(top_left, bottom_left)
+
+        return self
+
     def even_odd_fill(self, enabled: bool = True) -> 'PathBuilder':
         """
         Set the fill rule to even-odd (vs nonzero winding).
@@ -555,3 +587,223 @@ class BezierBuilder:
         # Add it using the client's internal method
         # noinspection PyProtectedMember
         return self._client._add_path(path)
+
+
+class RectangleBuilder:
+    """
+    Builder class for constructing Rectangle objects with fluent interface.
+    Provides a convenient way to create a rectangle path with a single builder.
+    """
+
+    def __init__(self, client: 'PDFDancer', page_index: int):
+        """
+        Initialize the rectangle builder.
+
+        Args:
+            client: The PDFDancer instance for adding the rectangle
+            page_index: The page number (0-indexed)
+        """
+        if client is None:
+            raise ValidationException("Client cannot be null")
+
+        self._client = client
+        self._page_index = page_index
+        self._x: Optional[float] = None
+        self._y: Optional[float] = None
+        self._width: Optional[float] = None
+        self._height: Optional[float] = None
+        self._stroke_color: Optional[Color] = Color(0, 0, 0)  # Black default
+        self._fill_color: Optional[Color] = None
+        self._stroke_width: float = 1.0
+        self._dash_array: Optional[List[float]] = None
+        self._dash_phase: Optional[float] = None
+        self._even_odd_fill: bool = False
+
+    def at_coordinates(self, x: float, y: float) -> 'RectangleBuilder':
+        """
+        Set the bottom-left corner position of the rectangle.
+
+        Args:
+            x: X coordinate on the page
+            y: Y coordinate on the page
+
+        Returns:
+            Self for method chaining
+        """
+        self._x = x
+        self._y = y
+        return self
+
+    def with_size(self, width: float, height: float) -> 'RectangleBuilder':
+        """
+        Set the dimensions of the rectangle.
+
+        Args:
+            width: Rectangle width
+            height: Rectangle height
+
+        Returns:
+            Self for method chaining
+        """
+        self._width = width
+        self._height = height
+        return self
+
+    def stroke_color(self, color: Color) -> 'RectangleBuilder':
+        """
+        Set the stroke color.
+
+        Args:
+            color: The stroke color
+
+        Returns:
+            Self for method chaining
+        """
+        self._stroke_color = color
+        return self
+
+    def fill_color(self, color: Color) -> 'RectangleBuilder':
+        """
+        Set the fill color.
+
+        Args:
+            color: The fill color
+
+        Returns:
+            Self for method chaining
+        """
+        self._fill_color = color
+        return self
+
+    def stroke_width(self, width: float) -> 'RectangleBuilder':
+        """
+        Set the stroke width.
+
+        Args:
+            width: The stroke width in points
+
+        Returns:
+            Self for method chaining
+        """
+        if width <= 0:
+            raise ValidationException("Stroke width must be positive")
+        self._stroke_width = width
+        return self
+
+    def dash_pattern(self, dash_array: List[float], dash_phase: float = 0.0) -> 'RectangleBuilder':
+        """
+        Set a dash pattern.
+
+        Args:
+            dash_array: List of on/off lengths (e.g., [10, 5] = 10pt on, 5pt off)
+            dash_phase: Offset into the pattern
+
+        Returns:
+            Self for method chaining
+        """
+        self._dash_array = dash_array
+        self._dash_phase = dash_phase
+        return self
+
+    def solid(self) -> 'RectangleBuilder':
+        """
+        Set rectangle to solid (no dash pattern).
+
+        Returns:
+            Self for method chaining
+        """
+        self._dash_array = None
+        self._dash_phase = None
+        return self
+
+    def even_odd_fill(self, enabled: bool = True) -> 'RectangleBuilder':
+        """
+        Set the fill rule to even-odd (vs nonzero winding).
+
+        Args:
+            enabled: True for even-odd, False for nonzero winding
+
+        Returns:
+            Self for method chaining
+        """
+        self._even_odd_fill = enabled
+        return self
+
+    def add(self) -> bool:
+        """
+        Build the rectangle and add it to the PDF document.
+
+        Returns:
+            True if successful
+
+        Raises:
+            ValidationException: If required properties are missing
+        """
+        if self._x is None or self._y is None:
+            raise ValidationException("Rectangle position must be set using at_coordinates()")
+        if self._width is None or self._height is None:
+            raise ValidationException("Rectangle dimensions must be set using with_size()")
+        if self._width <= 0:
+            raise ValidationException("Rectangle width must be positive")
+        if self._height <= 0:
+            raise ValidationException("Rectangle height must be positive")
+
+        # Create rectangle as 4 line segments
+        bottom_left = Point(self._x, self._y)
+        bottom_right = Point(self._x + self._width, self._y)
+        top_right = Point(self._x + self._width, self._y + self._height)
+        top_left = Point(self._x, self._y + self._height)
+
+        # Create four lines forming the rectangle
+        lines = [
+            Line(
+                p0=bottom_left,
+                p1=bottom_right,
+                stroke_color=self._stroke_color,
+                fill_color=self._fill_color,
+                stroke_width=self._stroke_width,
+                dash_array=self._dash_array,
+                dash_phase=self._dash_phase
+            ),
+            Line(
+                p0=bottom_right,
+                p1=top_right,
+                stroke_color=self._stroke_color,
+                fill_color=self._fill_color,
+                stroke_width=self._stroke_width,
+                dash_array=self._dash_array,
+                dash_phase=self._dash_phase
+            ),
+            Line(
+                p0=top_right,
+                p1=top_left,
+                stroke_color=self._stroke_color,
+                fill_color=self._fill_color,
+                stroke_width=self._stroke_width,
+                dash_array=self._dash_array,
+                dash_phase=self._dash_phase
+            ),
+            Line(
+                p0=top_left,
+                p1=bottom_left,
+                stroke_color=self._stroke_color,
+                fill_color=self._fill_color,
+                stroke_width=self._stroke_width,
+                dash_array=self._dash_array,
+                dash_phase=self._dash_phase
+            )
+        ]
+
+        # Create position with only page index set
+        position = Position.at_page_coordinates(self._page_index, 0, 0)
+
+        # Wrap in Path with four line segments
+        path = Path(
+            position=position,
+            path_segments=lines,
+            even_odd_fill=self._even_odd_fill
+        )
+
+        # Add it using the client's internal method
+        # noinspection PyProtectedMember
+        return self._client._add_path(path)

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
@@ -116,7 +117,7 @@ def _log_generated_at_header(response: httpx.Response, method: str, path: str) -
             print(f"{time.time()}|{method} {path} - Header parse error: {e}")
 
 
-from . import ParagraphBuilder
+from . import ParagraphBuilder, BezierBuilder, PathBuilder, LineBuilder
 from .exceptions import (
     PdfDancerException,
     FontNotFoundException,
@@ -124,15 +125,17 @@ from .exceptions import (
     SessionException,
     ValidationException
 )
-from .image_builder import ImageBuilder
+from .image_builder import ImageBuilder, ImageOnPageBuilder
 from .models import (
     ObjectRef, Position, ObjectType, Font, Image, Paragraph, FormFieldRef, TextObjectRef, PageRef,
-    FindRequest, DeleteRequest, MoveRequest, PageMoveRequest, AddRequest, ModifyRequest, ModifyTextRequest,
+    FindRequest, DeleteRequest, MoveRequest, PageMoveRequest, AddPageRequest, AddRequest, ModifyRequest,
+    ModifyTextRequest,
     ChangeFormFieldRequest, CommandResult,
     ShapeType, PositionMode, PageSize, Orientation,
     PageSnapshot, DocumentSnapshot, FontRecommendation, FontType
 )
 from .paragraph_builder import ParagraphPageBuilder
+from .page_builder import PageBuilder
 from .types import PathObject, ParagraphObject, TextLineObject, ImageObject, FormObject, FormFieldObject
 
 
@@ -270,21 +273,25 @@ class PageClient:
     def _ref(self):
         return ObjectRef(internal_id=self.internal_id, position=self.position, type=self.object_type)
 
-    def new_paragraph(self):
+    def new_paragraph(self) -> ParagraphBuilder:
         return ParagraphPageBuilder(self.root, self.page_index)
 
-    def new_path(self):
-        from .path_builder import PathBuilder
+    def new_path(self) -> PathBuilder:
         return PathBuilder(self.root, self.page_index)
 
-    def new_line(self):
-        from .path_builder import LineBuilder
+    def new_image(self) -> ImageOnPageBuilder:
+        return ImageOnPageBuilder(self.root, self.page_index)
+
+    def new_line(self) -> LineBuilder:
         return LineBuilder(self.root, self.page_index)
 
-    def new_bezier(self):
-        from .path_builder import BezierBuilder
+    def new_bezier(self) -> BezierBuilder:
         return BezierBuilder(self.root, self.page_index)
 
+    def new_rectangle(self) -> 'RectangleBuilder':
+        from .path_builder import RectangleBuilder
+        return RectangleBuilder(self.root, self.page_index)
+
     def select_paths(self):
         # noinspection PyProtectedMember
         return self.root._to_path_objects(self.root._find_paths(Position.at_page(self.page_index)))
@@ -906,6 +913,20 @@ class PDFDancer:
         """
         return self._to_paragraph_objects(self._find_paragraphs(None))
 
+    def select_paragraphs_matching(self, pattern: str) -> List[ParagraphObject]:
+        """
+        Searches for paragraph objects matching a regex pattern.
+
+        Args:
+            pattern: Regex pattern to match against paragraph text
+
+        Returns:
+            List of ParagraphObject instances matching the pattern
+        """
+        position = Position()
+        position.text_pattern = pattern
+        return self._to_paragraph_objects(self._find_paragraphs(position))
+
     def _find_paragraphs(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[
         TextObjectRef]:
         """
@@ -1270,7 +1291,6 @@ class PDFDancer:
         """
         Internal method to add a path to the document after validation.
         """
-        from .models import Path as PathModel
 
         if path is None:
             raise ValidationException("Path cannot be null")
@@ -1299,11 +1319,16 @@ class PDFDancer:
 
         return result
 
-    def new_paragraph(self) -> ParagraphBuilder:
-        return ParagraphBuilder(self)
+    def _add_page(self, request: Optional[AddPageRequest]) -> PageRef:
+        """
+        Internal helper to add a page with optional parameters.
+        """
+        request_data = None
+        if request is not None:
+            payload = request.to_dict()
+            request_data = payload or None
 
-    def new_page(self):
-        response = self._make_request('POST', '/pdf/page/add', data=None)
+        response = self._make_request('POST', '/pdf/page/add', data=request_data)
         result = self._parse_page_ref(response.json())
 
         # Invalidate snapshot caches after adding page
@@ -1311,6 +1336,17 @@ class PDFDancer:
 
         return result
 
+    def new_paragraph(self) -> ParagraphBuilder:
+        return ParagraphBuilder(self)
+
+    def new_page(self, orientation=Orientation.PORTRAIT, size=PageSize.A4) -> PageBuilder:
+        builder = PageBuilder(self)
+        if orientation is not None:
+            builder.orientation(orientation)
+        if size is not None:
+            builder.page_size(size)
+        return builder
+
     def new_image(self) -> ImageBuilder:
         return ImageBuilder(self)
 
@@ -1816,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
 
@@ -1963,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)
@@ -2020,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.19.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.19
+Version: 0.2.21
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: