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

pdfdancer/__init__.py

@@ -16,12 +16,14 @@ from .models import (
     FontType, PathSegment, Line, Bezier, Path
 )
 from .paragraph_builder import ParagraphBuilder
+from .page_builder import PageBuilder
 from .path_builder import PathBuilder, LineBuilder, BezierBuilder
 
 __version__ = "1.0.0"
 __all__ = [
     "PDFDancer",
     "ParagraphBuilder",
+    "PageBuilder",
     "PathBuilder",
     "LineBuilder",
     "BezierBuilder",

pdfdancer/image_builder.py

@@ -27,4 +27,34 @@ class ImageBuilder:
         return self
 
     def add(self) -> bool:
+        # noinspection PyProtectedMember
+        return self._client._add_image(self._image, self._image.position)
+
+
+class ImageOnPageBuilder:
+
+    def __init__(self, client: 'PDFDancer', page_index: int):
+        """
+        Initialize the image builder with a client reference.
+
+        Args:
+            client: The PDFDancer instance for font registration
+        """
+        if client is None:
+            raise ValidationException("Client cannot be null")
+
+        self._client = client
+        self._image = Image()
+        self._page_index = page_index
+
+    def from_file(self, img_path: Path) -> 'ImageOnPageBuilder':
+        self._image.data = img_path.read_bytes()
+        return self
+
+    def at(self, x, y) -> 'ImageOnPageBuilder':
+        self._image.position = Position.at_page_coordinates(self._page_index, x, y)
+        return self
+
+    def add(self) -> bool:
+        # noinspection PyProtectedMember
         return self._client._add_image(self._image, self._image.position)

pdfdancer/models.py

@@ -9,7 +9,36 @@ from typing import Optional, List, Any, Dict, Mapping, Tuple, ClassVar, Union
 
 @dataclass(frozen=True)
 class PageSize:
-    """Represents a page size specification, covering both standard and custom dimensions."""
+    """Represents a page size specification, covering both standard and custom dimensions.
+
+    Parameters:
+    - name: Optional canonical name of the size (e.g. "A4", "LETTER"). Will be upper‑cased.
+    - width: Page width in PDF points (1/72 inch).
+    - height: Page height in PDF points (1/72 inch).
+
+    Notes:
+    - Use `PageSize.from_name()` or the convenience constants (e.g. `PageSize.A4`) for common sizes.
+    - `width` and `height` must be positive numbers and are validated in `__post_init__`.
+
+    Examples:
+    - From standard name:
+      ```python
+      size = PageSize.from_name("A4")  # or PageSize.A4
+      ```
+    - From custom dimensions:
+      ```python
+      size = PageSize(name=None, width=500.0, height=700.0)
+      ```
+    - From dict (e.g. deserialized JSON):
+      ```python
+      size = PageSize.from_dict({"width": 612, "height": 792, "name": "letter"})
+      ```
+    - Coercion utility:
+      ```python
+      size = PageSize.coerce("A4")
+      size = PageSize.coerce({"width": 300, "height": 300})
+      ```
+    """
 
     name: Optional[str]
     width: float
@@ -154,6 +183,7 @@ class StandardFonts(Enum):
 
 
 class ObjectType(Enum):
+    """Server object type discriminator used in refs, requests, and snapshots."""
     FORM_FIELD = "FORM_FIELD"
     IMAGE = "IMAGE"
     FORM_X_OBJECT = "FORM_X_OBJECT"
@@ -215,7 +245,39 @@ class BoundingRect:
 @dataclass
 class Position:
     """
-    Represents spatial positioning and location information for PDF objects.
+    Spatial locator used to find or place objects on a page.
+
+    Parameters:
+    - page_index: Zero-based page index this position refers to. Required for most operations
+      that place or search on a specific page; use `Position.at_page()` as a shortcut.
+    - shape: Optional geometric shape used when matching by area (`POINT`, `LINE`, `CIRCLE`, `RECT`).
+    - mode: How to match objects relative to the shape (`INTERSECT` or `CONTAINS`).
+    - bounding_rect: Rectangle describing the area or point (for `POINT`, width/height are 0).
+    - text_starts_with: Filter for text objects whose content starts with this string.
+    - text_pattern: Regex pattern to match text content.
+    - name: Named anchor or element name to target (e.g. form field name).
+
+    Builder helpers:
+    - `Position.at_page(page_index)` – target a whole page.
+    - `Position.at_page_coordinates(page_index, x, y)` – target a point on a page.
+    - `Position.by_name(name)` – target object(s) by name.
+    - `pos.at_coordinates(Point(x, y))` – switch to a point on the current page.
+    - `pos.move_x(dx)`, `pos.move_y(dy)` – offset the current coordinates.
+
+    Examples:
+    ```python
+    # A point on page 0
+    pos = Position.at_page_coordinates(0, x=72, y=720)
+
+    # Search by name (e.g. a form field) and then move down 12 points
+    pos = Position.by_name("Email").move_y(-12)
+
+    # Match anything intersecting a rectangular area on page 1
+    pos = Position.at_page(1)
+    pos.shape = ShapeType.RECT
+    pos.mode = PositionMode.INTERSECT
+    pos.bounding_rect = BoundingRect(x=100, y=100, width=200, height=50)
+    ```
     """
     page_index: Optional[int] = None
     shape: Optional[ShapeType] = None
@@ -287,7 +349,24 @@ class Position:
 @dataclass
 class ObjectRef:
     """
-    Lightweight reference to a PDF object providing identity and type information.
+    Reference to an object in a PDF document returned by the server.
+
+    Parameters:
+    - internal_id: Server-side identifier for the object.
+    - position: Position information describing where the object is.
+    - type: Object type (see `ObjectType`).
+
+    Usage:
+    - Instances are typically returned in snapshots or find results.
+    - Pass an `ObjectRef` to request objects such as `MoveRequest`, `DeleteRequest`,
+      `ModifyRequest`, or `ModifyTextRequest`.
+
+    Example:
+    ```python
+    # Move an object to a new position
+    new_pos = Position.at_page_coordinates(0, 120, 500)
+    payload = MoveRequest(object_ref=obj_ref, position=new_pos).to_dict()
+    ```
     """
     internal_id: str
     position: Position
@@ -325,7 +404,23 @@ class ObjectRef:
 
 @dataclass
 class Color:
-    """Represents an RGB color with optional alpha channel, values from 0-255."""
+    """RGB color with optional alpha channel.
+
+    Parameters:
+    - r: Red component (0-255)
+    - g: Green component (0-255)
+    - b: Blue component (0-255)
+    - a: Alpha component (0-255), default 255 (opaque)
+
+    Raises:
+    - ValueError: If any component is outside 0-255.
+
+    Example:
+    ```python
+    red = Color(255, 0, 0)
+    semi_transparent_black = Color(0, 0, 0, a=128)
+    ```
+    """
     r: int
     g: int
     b: int
@@ -339,7 +434,23 @@ class Color:
 
 @dataclass
 class Font:
-    """Represents a font with name and size."""
+    """Font face and size.
+
+    Parameters:
+    - name: Font family name. Can be one of `StandardFonts` values or any embedded font name.
+    - size: Font size in points (> 0).
+
+    Raises:
+    - ValueError: If `size` is not positive.
+
+    Example:
+    ```python
+    from pdfdancer.models import Font, StandardFonts
+
+    title_font = Font(name=StandardFonts.HELVETICA_BOLD.value, size=16)
+    body_font = Font(name="MyEmbeddedFont", size=10.5)
+    ```
+    """
     name: str
     size: float
 
@@ -351,10 +462,18 @@ class Font:
 @dataclass
 class PathSegment:
     """
-    Abstract base class for individual path segments within vector paths.
-    This class provides common properties for path elements including stroke and fill colors,
-    line width, and positioning. Concrete subclasses implement specific geometric shapes
-    like lines, curves, and bezier segments.
+    Base class for vector path segments.
+
+    Parameters:
+    - stroke_color: Outline color for the segment (`Color`).
+    - fill_color: Fill color for closed shapes when applicable (`Color`).
+    - stroke_width: Line width in points.
+    - dash_array: Dash pattern (e.g. `[3, 2]` for 3 on, 2 off). None or empty for solid.
+    - dash_phase: Offset into the dash pattern.
+
+    Notes:
+    - Concrete subclasses are `Line` and `Bezier`.
+    - Used inside `Path.path_segments` and serialized by `AddRequest`.
     """
     stroke_color: Optional[Color] = None
     fill_color: Optional[Color] = None
@@ -386,9 +505,19 @@ class PathSegment:
 @dataclass
 class Line(PathSegment):
     """
-    Represents a straight line path segment between two points.
-    This class defines a linear path element connecting two coordinate points,
-    commonly used in vector graphics and geometric shapes within PDF documents.
+    Straight line segment between two points.
+
+    Parameters:
+    - p0: Start point.
+    - p1: End point.
+
+    Example:
+    ```python
+    from pdfdancer.models import Line, Point, Path
+
+    line = Line(p0=Point(10, 10), p1=Point(100, 10))
+    path = Path(path_segments=[line])
+    ```
     """
     p0: Optional[Point] = None
     p1: Optional[Point] = None
@@ -405,9 +534,20 @@ class Line(PathSegment):
 @dataclass
 class Bezier(PathSegment):
     """
-    Represents a cubic Bezier curve path segment defined by four control points.
-    This class implements a cubic Bezier curve with start point, two control points,
-    and end point, providing smooth curved path segments for complex vector graphics.
+    Cubic Bezier curve segment defined by 4 points.
+
+    Parameters:
+    - p0: Start point.
+    - p1: First control point.
+    - p2: Second control point.
+    - p3: End point.
+
+    Example:
+    ```python
+    curve = Bezier(
+        p0=Point(10, 10), p1=Point(50, 80), p2=Point(80, 50), p3=Point(120, 10)
+    )
+    ```
     """
     p0: Optional[Point] = None
     p1: Optional[Point] = None
@@ -434,9 +574,28 @@ class Bezier(PathSegment):
 @dataclass
 class Path:
     """
-    Represents a complex vector path consisting of multiple path segments.
-    This class encapsulates vector graphics data within PDF documents, composed of
-    various path elements like lines, curves, and shapes.
+    Vector path composed of one or more `PathSegment`s.
+
+    Parameters:
+    - position: Where to place the path on the page.
+    - path_segments: List of `Line` and/or `Bezier` segments.
+    - even_odd_fill: If True, use even-odd rule for fills; otherwise nonzero winding.
+
+    Example (adding a triangle to a page):
+    ```python
+    from pdfdancer.models import Path, Line, Point, Position, AddRequest
+
+    tri = Path(
+        position=Position.at_page_coordinates(0, 100, 100),
+        path_segments=[
+            Line(Point(0, 0), Point(50, 100)),
+            Line(Point(50, 100), Point(100, 0)),
+            Line(Point(100, 0), Point(0, 0)),
+        ],
+        even_odd_fill=True,
+    )
+    payload = AddRequest(tri).to_dict()
+    ```
     """
     position: Optional[Position] = None
     path_segments: Optional[List[PathSegment]] = None
@@ -462,7 +621,28 @@ class Path:
 @dataclass
 class Image:
     """
-    Represents an image object in a PDF document.
+    Raster image to be placed on a page.
+
+    Parameters:
+    - position: Where to place the image. Use `Position.at_page_coordinates(page, x, y)`.
+    - format: Image format hint for the server (e.g. "PNG", "JPEG"). Optional.
+    - width: Target width in points. Optional; server may infer from data.
+    - height: Target height in points. Optional; server may infer from data.
+    - data: Raw image bytes. If provided, it will be base64-encoded in `AddRequest.to_dict()`.
+
+    Example:
+    ```python
+    from pdfdancer.models import Image, Position, AddRequest
+
+    img = Image(
+        position=Position.at_page_coordinates(0, 72, 600),
+        format="PNG",
+        width=128,
+        height=64,
+        data=open("/path/logo.png", "rb").read(),
+    )
+    payload = AddRequest(img).to_dict()
+    ```
     """
     position: Optional[Position] = None
     format: Optional[str] = None
@@ -482,7 +662,29 @@ class Image:
 @dataclass
 class Paragraph:
     """
-    Represents a paragraph of text in a PDF document.
+    Multi-line text paragraph to add to a page.
+
+    Parameters:
+    - position: Anchor position where the first line begins.
+    - text_lines: List of strings, one per line. Use `\n` within a string only if desired; normally
+      provide separate entries for multiple lines.
+    - font: Font to use for all text elements unless overridden later.
+    - color: Text color.
+    - line_spacing: Distance multiplier between lines. Server expects a list, handled for you by `AddRequest`.
+
+    Example:
+    ```python
+    from pdfdancer.models import Paragraph, Position, Font, Color, StandardFonts, AddRequest
+
+    para = Paragraph(
+        position=Position.at_page_coordinates(0, 72, 700),
+        text_lines=["Hello", "PDFDancer!"],
+        font=Font(StandardFonts.HELVETICA.value, 12),
+        color=Color(50, 50, 50),
+        line_spacing=1.4,
+    )
+    payload = AddRequest(para).to_dict()
+    ```
     """
     position: Optional[Position] = None
     text_lines: Optional[List[str]] = None
@@ -502,7 +704,22 @@ class Paragraph:
 # Request classes for API communication
 @dataclass
 class FindRequest:
-    """Request object for find operations."""
+    """Request for locating objects.
+
+    Parameters:
+    - object_type: Filter by `ObjectType` (optional). If None, all types may be returned.
+    - position: `Position` describing where/how to search.
+    - hint: Optional backend hint or free-form note to influence matching.
+
+    Usage:
+    ```python
+    req = FindRequest(
+        object_type=ObjectType.TEXT_LINE,
+        position=Position.at_page_coordinates(0, 72, 700).with_text_starts("Hello"),
+    )
+    payload = req.to_dict()
+    ```
+    """
     object_type: Optional[ObjectType]
     position: Optional[Position]
     hint: Optional[str] = None
@@ -541,7 +758,16 @@ class FindRequest:
 
 @dataclass
 class DeleteRequest:
-    """Request object for delete operations."""
+    """Request to delete an existing object.
+
+    Parameters:
+    - object_ref: The object to delete.
+
+    Example:
+    ```python
+    payload = DeleteRequest(object_ref=obj_ref).to_dict()
+    ```
+    """
     object_ref: ObjectRef
 
     def to_dict(self) -> dict:
@@ -554,7 +780,19 @@ class DeleteRequest:
 
 @dataclass
 class MoveRequest:
-    """Request object for move operations."""
+    """Request to move an existing object to a new position.
+
+    Parameters:
+    - object_ref: The object to move (obtained from a snapshot or find call).
+    - position: The new target `Position` (commonly a point created with `Position.at_page_coordinates`).
+
+    Example:
+    ```python
+    new_pos = Position.at_page_coordinates(0, 200, 500)
+    req = MoveRequest(object_ref=obj_ref, position=new_pos)
+    payload = req.to_dict()
+    ```
+    """
     object_ref: ObjectRef
     position: Position
 
@@ -570,7 +808,19 @@ class MoveRequest:
 
 @dataclass
 class PageMoveRequest:
-    """Request object for moving pages within the document."""
+    """Request to reorder pages.
+
+    Parameters:
+    - from_page_index: Zero-based index of the page to move.
+    - to_page_index: Zero-based destination index.
+
+    Example:
+    ```python
+    # Move first page to the end
+    req = PageMoveRequest(from_page_index=0, to_page_index=doc_page_count - 1)
+    payload = req.to_dict()
+    ```
+    """
     from_page_index: int
     to_page_index: int
 
@@ -581,9 +831,60 @@ class PageMoveRequest:
         }
 
 
+@dataclass
+class AddPageRequest:
+    """Request to add a new page to the document.
+
+    Parameters:
+    - page_index: Optional zero-based index where the new page should be inserted.
+    - orientation: Optional page orientation (portrait or landscape).
+    - page_size: Optional size of the page.
+
+    Only populated fields are sent to the server to maintain backward compatibility
+    with default server behavior.
+    """
+    page_index: Optional[int] = None
+    orientation: Optional[Orientation] = None
+    page_size: Optional[PageSize] = None
+
+    def to_dict(self) -> dict:
+        payload: Dict[str, Any] = {}
+        if self.page_index is not None:
+            payload["pageIndex"] = int(self.page_index)
+        if self.orientation is not None:
+            orientation_value: Orientation
+            if isinstance(self.orientation, Orientation):
+                orientation_value = self.orientation
+            elif isinstance(self.orientation, str):
+                normalized = self.orientation.strip().upper()
+                orientation_value = Orientation(normalized)
+            else:
+                raise TypeError("Orientation must be an Orientation enum or string value")
+            payload["orientation"] = orientation_value.value
+        if self.page_size is not None:
+            page_size = PageSize.coerce(self.page_size)
+            payload["pageSize"] = page_size.to_dict()
+        return payload
+
+
 @dataclass
 class AddRequest:
-    """Request object for add operations."""
+    """Request to add a new object to the document.
+
+    Parameters:
+    - pdf_object: The object to add (e.g. `Image`, `Paragraph`, or `Path`).
+
+    Usage:
+    ```python
+    para = Paragraph(position=Position.at_page_coordinates(0, 72, 700), text_lines=["Hello"]) 
+    req = AddRequest(para)
+    payload = req.to_dict()  # ready to send to the server API
+    ```
+
+    Notes:
+    - Serialization details (like base64 for image `data`, or per-segment position for paths)
+      are handled for you in `to_dict()`.
+    """
     pdf_object: Any  # Can be Image, Paragraph, etc.
 
     def to_dict(self) -> dict:
@@ -727,7 +1028,19 @@ class AddRequest:
 
 @dataclass
 class ModifyRequest:
-    """Request object for modify operations."""
+    """Request to replace an object with a new one of possibly different type.
+
+    Parameters:
+    - object_ref: The existing object to replace.
+    - new_object: The replacement object (e.g. `Paragraph`, `Image`, or `Path`).
+
+    Example:
+    ```python
+    new_para = Paragraph(position=old.position, text_lines=["Updated text"]) 
+    req = ModifyRequest(object_ref=old, new_object=new_para)
+    payload = req.to_dict()
+    ```
+    """
     object_ref: ObjectRef
     new_object: Any
 
@@ -742,7 +1055,18 @@ class ModifyRequest:
 
 @dataclass
 class ModifyTextRequest:
-    """Request object for text modification operations."""
+    """Request to change the text content of a text object.
+
+    Parameters:
+    - object_ref: The text object to modify (e.g. a `TextObjectRef`).
+    - new_text: Replacement text content.
+
+    Example:
+    ```python
+    req = ModifyTextRequest(object_ref=text_ref, new_text="Hello world")
+    payload = req.to_dict()
+    ```
+    """
     object_ref: ObjectRef
     new_text: str
 
@@ -757,6 +1081,19 @@ class ModifyTextRequest:
 
 @dataclass
 class ChangeFormFieldRequest:
+    """Request to set a form field's value.
+
+    Parameters:
+    - object_ref: A `FormFieldRef` (or generic `ObjectRef`) identifying the field.
+    - value: The new value as a string. For checkboxes/radio buttons, use the
+      appropriate on/off/selection string per the document's field options.
+
+    Example:
+    ```python
+    req = ChangeFormFieldRequest(object_ref=field_ref, value="Jane Doe")
+    payload = req.to_dict()
+    ```
+    """
     object_ref: ObjectRef
     value: str
 
@@ -772,8 +1109,20 @@ class ChangeFormFieldRequest:
 @dataclass
 class FormFieldRef(ObjectRef):
     """
-    Represents a form field reference with additional form-specific properties.
-    Extends ObjectRef to include form field name and value.
+    Reference to a form field object with name and value.
+
+    Parameters (usually provided by the server):
+    - internal_id: Identifier of the form field object.
+    - position: Position of the field.
+    - type: One of `ObjectType.TEXT_FIELD`, `ObjectType.CHECK_BOX`, etc.
+    - name: Field name (as defined inside the PDF).
+    - value: Current field value (string representation).
+
+    Usage:
+    - You can pass a `FormFieldRef` to `ChangeFormFieldRequest` to update its value.
+    ```python
+    payload = ChangeFormFieldRequest(object_ref=field_ref, value="john@doe.com").to_dict()
+    ```
     """
     name: Optional[str] = None
     value: Optional[str] = None
@@ -841,8 +1190,23 @@ class TextStatus:
 
 class TextObjectRef(ObjectRef):
     """
-    Represents a text object reference with additional text-specific properties.
-    Extends ObjectRef to include text content, font information, and hierarchical structure.
+    Represents a text object with additional properties and optional hierarchy.
+
+    Parameters (typically provided by the server):
+    - internal_id: Identifier of the text object.
+    - position: Position of the text object.
+    - object_type: `ObjectType.TEXT_LINE` or another text-related type.
+    - text: Text content, when available.
+    - font_name: Name of the font used for the text.
+    - font_size: Size of the font in points.
+    - line_spacings: Optional list of line spacing values for multi-line objects.
+    - color: Text color.
+    - status: `TextStatus` providing modification/encoding info.
+
+    Usage:
+    - Instances are returned by find/snapshot APIs. You generally should not instantiate
+      them manually, but you may read their properties or pass their `ObjectRef`-like
+      identity to modification requests (e.g., `ModifyTextRequest`).
     """
 
     def __init__(self, internal_id: str, position: Position, object_type: ObjectType,
@@ -890,8 +1254,18 @@ class TextObjectRef(ObjectRef):
 @dataclass
 class PageRef(ObjectRef):
     """
-    Represents a page reference with additional page-specific properties.
-    Extends ObjectRef to include page size and orientation.
+    Reference to a page with size and orientation metadata.
+
+    Parameters (usually provided by the server):
+    - internal_id: Identifier of the page object.
+    - position: Position referencing the page (often via `Position.at_page(page_index)`).
+    - type: Should be `ObjectType.PAGE`.
+    - page_size: `PageSize` of the page.
+    - orientation: `Orientation.PORTRAIT` or `Orientation.LANDSCAPE`.
+
+    Usage:
+    - Returned inside `PageSnapshot` objects. You can inspect page size/orientation
+      and use the page index for subsequent operations.
     """
     page_size: Optional[PageSize]
     orientation: Optional[Orientation]
@@ -908,7 +1282,22 @@ class PageRef(ObjectRef):
 @dataclass
 class CommandResult:
     """
-    Result object returned by certain API endpoints indicating the outcome of an operation.
+    Outcome returned by certain API endpoints.
+
+    Parameters:
+    - command_name: Name of the executed command on the server.
+    - element_id: Optional related element ID (when applicable).
+    - message: Informational message or error description.
+    - success: Whether the command succeeded.
+    - warning: Optional warning details.
+
+    Example:
+    ```python
+    # Parse from a server JSON response dict
+    result = CommandResult.from_dict(resp_json)
+    if not result.success:
+        print("Operation failed:", result.message)
+    ```
     """
     command_name: str
     element_id: str | None
@@ -936,6 +1325,14 @@ class CommandResult:
 class PageSnapshot:
     """
     Snapshot of a single page containing all elements and page metadata.
+
+    Parameters (provided by the server):
+    - page_ref: `PageRef` describing the page (size, orientation, etc.).
+    - elements: List of `ObjectRef` (and subclasses) present on the page.
+
+    Usage:
+    - Iterate over `elements` to find items to modify or move.
+    - Use `page_ref.position.page_index` as the page index for follow-up operations.
     """
     page_ref: PageRef
     elements: List[ObjectRef]
@@ -952,7 +1349,21 @@ class PageSnapshot:
 @dataclass
 class DocumentSnapshot:
     """
-    Snapshot of the entire document containing all pages and font information.
+    Snapshot of a document including pages and fonts used.
+
+    Parameters (provided by the server):
+    - page_count: Number of pages in the document.
+    - fonts: List of `FontRecommendation` entries summarizing fonts in the document.
+    - pages: Ordered list of `PageSnapshot` objects, one per page.
+
+    Usage:
+    ```python
+    # Iterate pages and elements
+    for page in snapshot.pages:
+        for el in page.elements:
+            if isinstance(el, TextObjectRef) and el.get_text():
+                print(el.get_text())
+    ```
     """
     page_count: int
     fonts: List[FontRecommendation]

pdfdancer/page_builder.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from .exceptions import ValidationException
+from .models import Orientation, PageRef, PageSize, AddPageRequest
+
+
+class PageBuilder:
+    """
+    Fluent builder for adding pages with optional orientation, size, and index.
+
+    Usage:
+        pdf.new_page().at_index(1).landscape().a4().add()
+    """
+
+    def __init__(self, client: 'PDFDancer') -> None:
+        if client is None:
+            raise ValidationException("Client cannot be null")
+
+        self._client = client
+        self._page_index: Optional[int] = None
+        self._orientation: Optional[Orientation] = None
+        self._page_size: Optional[PageSize] = None
+
+    def at_index(self, page_index: int) -> 'PageBuilder':
+        if page_index is None:
+            raise ValidationException("Page index cannot be null")
+        if page_index < 0:
+            raise ValidationException("Page index must be greater than or equal to 0")
+        self._page_index = int(page_index)
+        return self
+
+    def orientation(self, orientation: Orientation) -> 'PageBuilder':
+        if orientation is None:
+            raise ValidationException("Orientation cannot be null")
+        if isinstance(orientation, str):
+            normalized = orientation.strip().upper()
+            orientation = Orientation(normalized)
+        self._orientation = orientation
+        return self
+
+    def portrait(self) -> 'PageBuilder':
+        self._orientation = Orientation.PORTRAIT
+        return self
+
+    def landscape(self) -> 'PageBuilder':
+        self._orientation = Orientation.LANDSCAPE
+        return self
+
+    def page_size(self, page_size: PageSize) -> 'PageBuilder':
+        if page_size is None:
+            raise ValidationException("Page size cannot be null")
+        self._page_size = PageSize.coerce(page_size)
+        return self
+
+    def a4(self) -> 'PageBuilder':
+        self._page_size = PageSize.A4
+        return self
+
+    def letter(self) -> 'PageBuilder':
+        self._page_size = PageSize.LETTER
+        return self
+
+    def a3(self) -> 'PageBuilder':
+        self._page_size = PageSize.A3
+        return self
+
+    def a5(self) -> 'PageBuilder':
+        self._page_size = PageSize.A5
+        return self
+
+    def legal(self) -> 'PageBuilder':
+        self._page_size = PageSize.LEGAL
+        return self
+
+    def custom_size(self, width: float, height: float) -> 'PageBuilder':
+        self._page_size = PageSize(name=None, width=width, height=height)
+        return self
+
+    def add(self) -> PageRef:
+        request = self._build_request()
+        return self._client._add_page(request)
+
+    def _build_request(self) -> Optional[AddPageRequest]:
+        if self._page_index is None and self._orientation is None and self._page_size is None:
+            return None
+        return AddPageRequest(
+            page_index=self._page_index,
+            orientation=self._orientation,
+            page_size=self._page_size
+        )

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

@@ -116,7 +116,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 +124,16 @@ 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 +271,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)))
@@ -900,11 +905,25 @@ class PDFDancer:
                 all_elements.extend(page_snap.elements)
             return self._filter_snapshot_elements(all_elements, object_type, position, tolerance)
 
-    def select_paragraphs(self) -> List[TextObjectRef]:
+    def select_paragraphs(self) -> List[ParagraphObject]:
         """
-        Searches for paragraph objects returning TextObjectRef with hierarchical structure.
+        Searches for paragraph objects returning ParagraphObject instances.
         """
-        return self._find_paragraphs(None)
+        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 +1289,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 +1317,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 +1334,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)
 

pdfdancer/types.py

@@ -266,6 +266,13 @@ class ParagraphObject(PDFObjectBase):
         super().__init__(client, object_ref.internal_id, object_ref.type, object_ref.position)
         self._object_ref = object_ref
 
+    def __getattr__(self, name):
+        """
+        Automatically delegate attribute/method lookup to _object_ref
+        if it's not found on this object.
+        """
+        return getattr(self._object_ref, name)
+
     def edit(self) -> ParagraphEdit:
         return ParagraphEdit(self, self.object_ref())
 

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

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

pdfdancer_client_python-0.2.20.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=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,,

pdfdancer_client_python-0.2.18.dist-info/RECORD

@@ -1,15 +0,0 @@
-pdfdancer/__init__.py,sha256=ZZOarTVp9OJQUYA8PsBn8FWNCEHIaCcSHitd4dpBR5w,2150
-pdfdancer/exceptions.py,sha256=WAcyTacykJwjiaURrQamEgizLxv0vSlSio6NMikg4D0,1558
-pdfdancer/fingerprint.py,sha256=Ue5QzpqsKlbYefvKU0ULV4NgMU3AOTcseeV9HfiPJXI,3093
-pdfdancer/image_builder.py,sha256=Omxc2LcieJ1MbvWBXR5_sfia--eAucTUe0KWgr22HYo,842
-pdfdancer/models.py,sha256=kK2tIRwJ8XQJZZ__uSgvU6E0NRtj11Jzwwhy-d8EKSQ,32210
-pdfdancer/paragraph_builder.py,sha256=x5XhPo-GUeovQuGbrH7MyyenITcy6in7bz6CD9r-ZqU,9458
-pdfdancer/path_builder.py,sha256=KJC8toLhbCbtnxz8pphtpzgoBemGHlrcC1s02RAvCJ8,15862
-pdfdancer/pdfdancer_v1.py,sha256=pR2TnA57l2tXzVZHaBz_QFvZcVAdeWgwUXtO5OhPOPc,87350
-pdfdancer/types.py,sha256=SYbyzFJu1nDartalqgrceSTiLtsqZgIFQndvHz5Tnxw,12435
-pdfdancer_client_python-0.2.18.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-pdfdancer_client_python-0.2.18.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
-pdfdancer_client_python-0.2.18.dist-info/METADATA,sha256=37zeBth-hMmDWCMBdqShEsC8neWz8kqFOZIC-ALm4RA,24668
-pdfdancer_client_python-0.2.18.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.18.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.18.dist-info/RECORD,,