pdfdancer-client-python 0.1.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

pdfdancer/__init__.py

@@ -6,20 +6,19 @@ Provides a clean, Pythonic interface for PDF operations that closely
 mirrors the Java client structure and functionality.
 """
 
-from .client_v1 import ClientV1
 from .exceptions import (
     PdfDancerException, FontNotFoundException, ValidationException,
     HttpClientException, SessionException
 )
 from .models import (
-    ObjectRef, Position, ObjectType, Font, Color, Image, BoundingRect, Paragraph,
+    ObjectRef, Position, ObjectType, Font, Color, Image, BoundingRect, Paragraph, FormFieldRef,
     PositionMode, ShapeType, Point
 )
 from .paragraph_builder import ParagraphBuilder
 
 __version__ = "1.0.0"
 __all__ = [
-    "ClientV1",
+    "PDFDancer",
     "ParagraphBuilder",
     "ObjectRef",
     "Position",
@@ -29,6 +28,7 @@ __all__ = [
     "Image",
     "BoundingRect",
     "Paragraph",
+    "FormFieldRef",
     "PositionMode",
     "ShapeType",
     "Point",
@@ -38,3 +38,5 @@ __all__ = [
     "HttpClientException",
     "SessionException"
 ]
+
+from .pdfdancer_v1 import PDFDancer

pdfdancer/image_builder.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from pdfdancer import ValidationException, Image, Position
+
+
+class ImageBuilder:
+
+    def __init__(self, client: 'PDFDancer'):
+        """
+        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()
+
+    def from_file(self, img_path: Path) -> 'ImageBuilder':
+        self._image.data = img_path.read_bytes()
+        return self
+
+    def at(self, page, x, y) -> 'ImageBuilder':
+        self._image.position = Position.at_page_coordinates(page, x, y)
+        return self
+
+    def add(self) -> bool:
+        return self._client._add_image(self._image, self._image.position)

pdfdancer/models.py

@@ -10,12 +10,16 @@ from typing import Optional, List, Any
 
 class ObjectType(Enum):
     """Object type enumeration matching the Java ObjectType."""
+    FORM_FIELD = "FORM_FIELD"
     IMAGE = "IMAGE"
     FORM_X_OBJECT = "FORM_X_OBJECT"
     PATH = "PATH"
     PARAGRAPH = "PARAGRAPH"
     TEXT_LINE = "TEXT_LINE"
     PAGE = "PAGE"
+    TEXT_FIELD = "TEXT_FIELD"
+    CHECK_BOX = "CHECK_BOX"
+    RADIO_BUTTON = "RADIO_BUTTON"
 
 
 class PositionMode(Enum):
@@ -74,6 +78,7 @@ class Position:
     mode: Optional[PositionMode] = None
     bounding_rect: Optional[BoundingRect] = None
     text_starts_with: Optional[str] = None
+    name: Optional[str] = None
 
     @staticmethod
     def at_page(page_index: int) -> 'Position':
@@ -93,7 +98,17 @@ class Position:
         position.at_coordinates(Point(x, y))
         return position
 
-    def at_coordinates(self, point: Point) -> None:
+    @staticmethod
+    def by_name(name: str) -> 'Position':
+        """
+        Creates a position specification for finding objects by name.
+        Equivalent to Position.byName() in Java.
+        """
+        position = Position()
+        position.name = name
+        return position
+
+    def at_coordinates(self, point: Point) -> 'Position':
         """
         Sets the position to a specific point location.
         Equivalent to Position.set() in Java.
@@ -101,7 +116,7 @@ class Position:
         self.mode = PositionMode.CONTAINS
         self.shape = ShapeType.POINT
         self.bounding_rect = BoundingRect(point.x, point.y, 0, 0)
-        return self;
+        return self
 
     def with_text_starts(self, text: str) -> 'Position':
         self.text_starts_with = text
@@ -110,20 +125,20 @@ class Position:
     def move_x(self, x_offset: float) -> 'Position':
         """Move the position horizontally by the specified offset."""
         if self.bounding_rect:
-            self.at_coordinates(Point(self.get_x() + x_offset, self.get_y()))
+            self.at_coordinates(Point(self.x() + x_offset, self.y()))
         return self
 
     def move_y(self, y_offset: float) -> 'Position':
         """Move the position vertically by the specified offset."""
         if self.bounding_rect:
-            self.at_coordinates(Point(self.get_x(), self.get_y() + y_offset))
+            self.at_coordinates(Point(self.x(), self.y() + y_offset))
         return self
 
-    def get_x(self) -> Optional[float]:
+    def x(self) -> Optional[float]:
         """Returns the X coordinate of this position."""
         return self.bounding_rect.get_x() if self.bounding_rect else None
 
-    def get_y(self) -> Optional[float]:
+    def y(self) -> Optional[float]:
         """Returns the Y coordinate of this position."""
         return self.bounding_rect.get_y() if self.bounding_rect else None
 
@@ -269,6 +284,8 @@ class FindRequest:
             "pageIndex": position.page_index,
             "textStartsWith": position.text_starts_with
         }
+        if position.name:
+            result["name"] = position.name
         if position.shape:
             result["shape"] = position.shape.value
         if position.mode:
@@ -420,3 +437,38 @@ class ModifyTextRequest:
             },
             "newTextLine": self.new_text
         }
+
+
+@dataclass
+class ChangeFormFieldRequest:
+    object_ref: ObjectRef
+    value: str
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "ref": {
+                "internalId": self.object_ref.internal_id,
+                "position": FindRequest._position_to_dict(self.object_ref.position),
+                "type": self.object_ref.type.value
+            },
+            "value": self.value
+        }
+
+
+@dataclass
+class FormFieldRef(ObjectRef):
+    """
+    Represents a form field reference with additional form-specific properties.
+    Extends ObjectRef to include form field name and value.
+    """
+    name: Optional[str] = None
+    value: Optional[str] = None
+
+    def get_name(self) -> Optional[str]:
+        """Get the form field name."""
+        return self.name
+
+    def get_value(self) -> Optional[str]:
+        """Get the form field value."""
+        return self.value

pdfdancer/paragraph_builder.py

@@ -4,14 +4,11 @@ Closely mirrors the Java ParagraphBuilder class with Python conventions.
 """
 
 from pathlib import Path
-from typing import Optional, Union, TYPE_CHECKING
+from typing import Optional, Union
 
 from .exceptions import ValidationException
 from .models import Paragraph, Font, Color, Position
 
-if TYPE_CHECKING:
-    from .client_v1 import ClientV1
-
 
 class ParagraphBuilder:
     """
@@ -19,7 +16,7 @@ class ParagraphBuilder:
     Mirrors the Java ParagraphBuilder class exactly.
     """
 
-    def __init__(self, client: 'ClientV1'):
+    def __init__(self, client: 'PDFDancer'):
         """
         Initialize the paragraph builder with a client reference.
 
@@ -37,7 +34,7 @@ class ParagraphBuilder:
         self._ttf_file: Optional[Path] = None
         self._font: Optional[Font] = None
 
-    def from_string(self, text: str, color: Optional[Color] = None) -> 'ParagraphBuilder':
+    def text(self, text: str, color: Optional[Color] = None) -> 'ParagraphBuilder':
         """
         Set the text content for the paragraph.
         Equivalent to fromString() methods in Java ParagraphBuilder.
@@ -63,13 +60,14 @@ class ParagraphBuilder:
 
         return self
 
-    def with_font(self, font: Font) -> 'ParagraphBuilder':
+    def font(self, font_name: str, font_size: float) -> 'ParagraphBuilder':
         """
         Set the font for the paragraph using an existing Font object.
         Equivalent to withFont(Font) in Java ParagraphBuilder.
 
         Args:
-            font: The Font object to use
+            font_name: The Font to use
+            font_size: The font size
 
         Returns:
             Self for method chaining
@@ -77,6 +75,7 @@ class ParagraphBuilder:
         Raises:
             ValidationException: If font is None
         """
+        font = Font(font_name, font_size)
         if font is None:
             raise ValidationException("Font cannot be null")
 
@@ -84,7 +83,7 @@ class ParagraphBuilder:
         self._ttf_file = None  # Clear TTF file when using existing font
         return self
 
-    def with_font_file(self, ttf_file: Union[Path, str], font_size: float) -> 'ParagraphBuilder':
+    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.
@@ -125,7 +124,7 @@ class ParagraphBuilder:
         self._font = self._register_ttf(ttf_path, font_size)
         return self
 
-    def with_line_spacing(self, spacing: float) -> 'ParagraphBuilder':
+    def line_spacing(self, spacing: float) -> 'ParagraphBuilder':
         """
         Set the line spacing for the paragraph.
         Equivalent to withLineSpacing() in Java ParagraphBuilder.
@@ -145,7 +144,7 @@ class ParagraphBuilder:
         self._line_spacing = spacing
         return self
 
-    def with_color(self, color: Color) -> 'ParagraphBuilder':
+    def color(self, color: Color) -> 'ParagraphBuilder':
         """
         Set the text color for the paragraph.
         Equivalent to withColor() in Java ParagraphBuilder.
@@ -165,7 +164,7 @@ class ParagraphBuilder:
         self._text_color = color
         return self
 
-    def with_position(self, position: Position) -> 'ParagraphBuilder':
+    def at(self, page_index: int, x: float, y: float) -> 'ParagraphBuilder':
         """
         Set the position for the paragraph.
         Equivalent to withPosition() in Java ParagraphBuilder.
@@ -179,6 +178,7 @@ class ParagraphBuilder:
         Raises:
             ValidationException: If position is None
         """
+        position = Position.at_page_coordinates(page_index, x, y)
         if position is None:
             raise ValidationException("Position cannot be null")
 
@@ -265,3 +265,6 @@ class ParagraphBuilder:
             lines = ['']
 
         return lines
+
+    def add(self):
+        self._client._add_paragraph(self.build())

pdfdancer/{client_v1.py → pdfdancer_v1.py}

@@ -6,11 +6,13 @@ Provides session-based PDF manipulation operations with strict validation.
 """
 
 import json
+import os
 from pathlib import Path
 from typing import List, Optional, Union, BinaryIO
 
 import requests
 
+from . import ParagraphBuilder
 from .exceptions import (
     PdfDancerException,
     FontNotFoundException,
@@ -18,24 +20,133 @@ from .exceptions import (
     SessionException,
     ValidationException
 )
+from .image_builder import ImageBuilder
 from .models import (
-    ObjectRef, Position, ObjectType, Font, Image, Paragraph,
-    FindRequest, DeleteRequest, MoveRequest, AddRequest, ModifyRequest, ModifyTextRequest, ShapeType, PositionMode
+    ObjectRef, Position, ObjectType, Font, Image, Paragraph, FormFieldRef,
+    FindRequest, DeleteRequest, MoveRequest, AddRequest, ModifyRequest, ModifyTextRequest, ChangeFormFieldRequest,
+    ShapeType, PositionMode
 )
-
-
-class ClientV1:
+from .types import PathObject, ParagraphObject, TextLineObject, ImageObject, FormObject, FormFieldObject, PageObject
+
+
+class PageClient:
+    def __init__(self, page_index: int, root: "PDFDancer"):
+        self.page_index = page_index
+        self.root = root
+
+    def select_paths_at(self, x: float, y: float) -> List[PathObject]:
+        # noinspection PyProtectedMember
+        return self.root._to_path_objects(self.root._find_paths(Position.at_page_coordinates(self.page_index, x, y)))
+
+    def select_paragraphs(self) -> List[ParagraphObject]:
+        # noinspection PyProtectedMember
+        return self.root._to_paragraph_objects(self.root._find_paragraphs(Position.at_page(self.page_index)))
+
+    def select_paragraphs_starting_with(self, text: str) -> List[ParagraphObject]:
+        position = Position.at_page(self.page_index)
+        position.with_text_starts(text)
+        # noinspection PyProtectedMember
+        return self.root._to_paragraph_objects(self.root._find_paragraphs(position))
+
+    def select_paragraphs_at(self, x: float, y: float) -> List[ParagraphObject]:
+        position = Position.at_page_coordinates(self.page_index, x, y)
+        # noinspection PyProtectedMember
+        return self.root._to_paragraph_objects(self.root._find_paragraphs(position))
+
+    def select_text_lines(self) -> List[TextLineObject]:
+        position = Position.at_page(self.page_index)
+        # noinspection PyProtectedMember
+        return self.root._to_textline_objects(self.root._find_text_lines(position))
+
+    def select_text_lines_starting_with(self, text: str) -> List[TextLineObject]:
+        position = Position.at_page(self.page_index)
+        position.with_text_starts(text)
+        # noinspection PyProtectedMember
+        return self.root._to_textline_objects(self.root._find_text_lines(position))
+
+    def select_images(self) -> List[ImageObject]:
+        # noinspection PyProtectedMember
+        return self.root._to_image_objects(self.root._find_images(Position.at_page(self.page_index)))
+
+    def select_images_at(self, x: float, y: float) -> List[ImageObject]:
+        position = Position.at_page_coordinates(self.page_index, x, y)
+        # noinspection PyProtectedMember
+        return self.root._to_image_objects(self.root._find_images(position))
+
+    def select_forms(self) -> List[FormObject]:
+        position = Position.at_page(self.page_index)
+        # noinspection PyProtectedMember
+        return self.root._to_form_objects(self.root._find_form_x_objects(position))
+
+    def select_forms_at(self, x: float, y: float) -> List[FormObject]:
+        position = Position.at_page_coordinates(self.page_index, x, y)
+        # noinspection PyProtectedMember
+        return self.root._to_form_objects(self.root._find_form_x_objects(position))
+
+    def select_form_fields(self) -> List[FormFieldObject]:
+        position = Position.at_page(self.page_index)
+        # noinspection PyProtectedMember
+        return self.root._to_form_field_objects(self.root._find_form_fields(position))
+
+    def select_form_fields_by_name(self, field_name: str) -> List[FormFieldObject]:
+        pos = Position.by_name(field_name)
+        pos.page_index = self.page_index
+        # noinspection PyProtectedMember
+        return self.root._to_form_field_objects(self.root._find_form_fields(pos))
+
+    def select_form_fields_at(self, x: float, y: float) -> List[FormFieldObject]:
+        position = Position.at_page_coordinates(self.page_index, x, y)
+        # noinspection PyProtectedMember
+        return self.root._to_form_field_objects(self.root._find_form_fields(position))
+
+    def get(self) -> PageObject:
+        return self.root._to_page_object(self.root._get_page(self.page_index))
+
+
+class PDFDancer:
     """
     REST API client for interacting with the PDFDancer PDF manipulation service.
     This client provides a convenient Python interface for performing PDF operations
     including session management, object searching, manipulation, and retrieval.
     Handles authentication, session lifecycle, and HTTP communication transparently.
-
-    Mirrors the Java Client class functionality exactly.
     """
 
+    # --------------------------------------------------------------
+    # CLASS METHOD ENTRY POINT
+    # --------------------------------------------------------------
+    @classmethod
+    def open(cls,
+             pdf_data: Union[bytes, Path, str, BinaryIO],
+             token: Optional[str] = None,
+             base_url: Optional[str] = None,
+             timeout: float = 30.0) -> "PDFDancer":
+        """
+        Create a client session, falling back to environment variables when needed.
+
+        Args:
+            pdf_data: PDF payload supplied directly or via filesystem handles.
+            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environement variable.
+            base_url: Override for the API base URL; falls back to `PDFDANCER_BASE_URL`
+                or defaults to `https://api.pdfdancer.com`.
+            timeout: HTTP read timeout in seconds.
+
+        Returns:
+            A ready-to-use `PDFDancer` client instance.
+        """
+        resolved_token = token.strip() if token and token.strip() else None
+        if resolved_token is None:
+            env_token = os.getenv("PDFDANCER_TOKEN")
+            resolved_token = env_token.strip() if env_token and env_token.strip() else None
+
+        env_base_url = os.getenv("PDFDANCER_BASE_URL")
+        resolved_base_url = base_url or (env_base_url.strip() if env_base_url and env_base_url.strip() else None)
+        if resolved_base_url is None:
+            resolved_base_url = "https://api.pdfdancer.com"
+
+        return PDFDancer(resolved_token, pdf_data, resolved_base_url, timeout)
+
     def __init__(self, token: str, pdf_data: Union[bytes, Path, str, BinaryIO],
-                 base_url: str = "http://localhost:8080", read_timeout: float = 0):
+                 base_url: str, read_timeout: float = 0):
         """
         Creates a new client with PDF data.
         This constructor initializes the client, uploads the PDF data to create
@@ -75,7 +186,6 @@ class ClientV1:
     def _process_pdf_data(self, pdf_data: Union[bytes, Path, str, BinaryIO]) -> bytes:
         """
         Process PDF data from various input types with strict validation.
-        Equivalent to readFile() method in Java client.
         """
         if pdf_data is None:
             raise ValidationException("PDF data cannot be null")
@@ -152,7 +262,6 @@ class ClientV1:
     def _create_session(self) -> str:
         """
         Creates a new PDF processing session by uploading the PDF data.
-        Equivalent to createSession() method in Java client.
         """
         try:
             files = {
@@ -182,7 +291,6 @@ class ClientV1:
                       params: Optional[dict] = None) -> requests.Response:
         """
         Make HTTP request with session headers and error handling.
-        Equivalent to retrieve() method pattern in Java client.
         """
         headers = {
             'X-Session-Id': self._session_id,
@@ -218,7 +326,7 @@ class ClientV1:
 
     # Search Operations - matching Java client exactly
 
-    def find(self, object_type: Optional[ObjectType] = None, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find(self, object_type: Optional[ObjectType] = None, position: Optional[Position] = None) -> List[ObjectRef]:
         """
         Searches for PDF objects matching the specified criteria.
         This method provides flexible search capabilities across all PDF content,
@@ -238,56 +346,120 @@ class ClientV1:
         objects_data = response.json()
         return [self._parse_object_ref(obj_data) for obj_data in objects_data]
 
-    def find_paragraphs(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def select_paragraphs(self) -> List[ParagraphObject]:
         """
         Searches for paragraph objects at the specified position.
-        Equivalent to findParagraphs() in Java client.
         """
-        return self.find(ObjectType.PARAGRAPH, position)
+        return self._to_paragraph_objects(self._find(ObjectType.PARAGRAPH, None))
 
-    def find_images(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find_paragraphs(self, position: Optional[Position] = None) -> List[ObjectRef]:
+        """
+        Searches for paragraph objects at the specified position.
+        """
+        return self._find(ObjectType.PARAGRAPH, position)
+
+    def _find_images(self, position: Optional[Position] = None) -> List[ObjectRef]:
         """
         Searches for image objects at the specified position.
-        Equivalent to findImages() in Java client.
         """
-        return self.find(ObjectType.IMAGE, position)
+        return self._find(ObjectType.IMAGE, position)
+
+    def select_images(self) -> List[ImageObject]:
+        """
+        Searches for image objects in the whole document
+        """
+        return self._to_image_objects(self._find(ObjectType.IMAGE, None))
 
-    def find_forms(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def select_forms(self) -> List[FormObject]:
+        """
+        Searches for form field objects in the whole document.
+        """
+        return self._to_form_objects(self._find(ObjectType.FORM_X_OBJECT, None))
+
+    def _find_form_x_objects(self, position: Optional[Position] = None) -> List[ObjectRef]:
         """
         Searches for form field objects at the specified position.
-        Equivalent to findForms() in Java client.
         """
-        return self.find(ObjectType.FORM_X_OBJECT, position)
+        return self._find(ObjectType.FORM_X_OBJECT, position)
+
+    def select_form_fields(self) -> List[FormFieldObject]:
+        """
+        Searches for form field objects in the whole document.
+        """
+        return self._to_form_field_objects(self._find_form_fields(None))
+
+    def select_form_fields_by_name(self, field_name: str) -> List[FormFieldObject]:
+        """
+        Searches for form field objects in the whole document.
+        """
+        return self._to_form_field_objects(self._find_form_fields(Position.by_name(field_name)))
 
-    def find_paths(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find_form_fields(self, position: Optional[Position] = None) -> List[FormFieldRef]:
+        """
+        Searches for form fields at the specified position.
+        Returns FormFieldRef objects with name and value properties.
+        """
+        request_data = FindRequest(ObjectType.FORM_FIELD, position).to_dict()
+        response = self._make_request('POST', '/pdf/find', data=request_data)
+
+        # Parse response into ObjectRef objects
+        objects_data = response.json()
+        return [self._parse_form_field_ref(obj_data) for obj_data in objects_data]
+
+    def _change_form_field(self, form_field_ref: FormFieldRef, new_value: str) -> bool:
+        """
+        Changes the value of a form field.
+        """
+        if form_field_ref is None:
+            raise ValidationException("Form field reference cannot be null")
+
+        request_data = ChangeFormFieldRequest(form_field_ref, new_value).to_dict()
+        response = self._make_request('PUT', '/pdf/modify/formField', data=request_data)
+        return response.json()
+
+    def select_paths(self) -> List[ObjectRef]:
         """
         Searches for vector path objects at the specified position.
-        Equivalent to findPaths() in Java client.
         """
-        return self.find(ObjectType.PATH, position)
+        return self._find(ObjectType.PATH, None)
+
+    def _find_paths(self, position: Optional[Position] = None) -> List[ObjectRef]:
+        """
+        Searches for vector path objects at the specified position.
+        """
+        return self._find(ObjectType.PATH, position)
+
+    def _find_text_lines(self, position: Optional[Position] = None) -> List[ObjectRef]:
+        """
+        Searches for text line objects at the specified position.
+        """
+        return self._find(ObjectType.TEXT_LINE, position)
 
-    def find_text_lines(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def select_text_lines(self) -> List[TextLineObject]:
         """
         Searches for text line objects at the specified position.
-        Equivalent to findTextLines() in Java client.
         """
-        return self.find(ObjectType.TEXT_LINE, position)
+        return self._to_textline_objects(self._find(ObjectType.TEXT_LINE, None))
+
+    def page(self, page_index: int) -> PageClient:
+        return PageClient(page_index, self)
 
     # Page Operations
 
-    def get_pages(self) -> List[ObjectRef]:
+    def pages(self) -> List[PageObject]:
+        return self._to_page_objects(self._get_pages())
+
+    def _get_pages(self) -> List[ObjectRef]:
         """
         Retrieves references to all pages in the PDF document.
-        Equivalent to getPages() in Java client.
         """
         response = self._make_request('POST', '/pdf/page/find')
         pages_data = response.json()
         return [self._parse_object_ref(page_data) for page_data in pages_data]
 
-    def get_page(self, page_index: int) -> Optional[ObjectRef]:
+    def _get_page(self, page_index: int) -> Optional[ObjectRef]:
         """
         Retrieves a reference to a specific page by its page index.
-        Equivalent to getPage() in Java client.
 
         Args:
             page_index: The page index to retrieve (1-based indexing)
@@ -307,10 +479,9 @@ class ClientV1:
 
         return self._parse_object_ref(pages_data[0])
 
-    def delete_page(self, page_ref: ObjectRef) -> bool:
+    def _delete_page(self, page_ref: ObjectRef) -> bool:
         """
         Deletes a page from the PDF document.
-        Equivalent to deletePage() in Java client.
 
         Args:
             page_ref: Reference to the page to be deleted
@@ -328,10 +499,9 @@ class ClientV1:
 
     # Manipulation Operations
 
-    def delete(self, object_ref: ObjectRef) -> bool:
+    def _delete(self, object_ref: ObjectRef) -> bool:
         """
         Deletes the specified PDF object from the document.
-        Equivalent to delete() in Java client.
 
         Args:
             object_ref: Reference to the object to be deleted
@@ -346,10 +516,9 @@ class ClientV1:
         response = self._make_request('DELETE', '/pdf/delete', data=request_data)
         return response.json()
 
-    def move(self, object_ref: ObjectRef, position: Position) -> bool:
+    def _move(self, object_ref: ObjectRef, position: Position) -> bool:
         """
         Moves a PDF object to a new position within the document.
-        Equivalent to move() in Java client.
 
         Args:
             object_ref: Reference to the object to be moved
@@ -369,10 +538,9 @@ class ClientV1:
 
     # Add Operations
 
-    def add_image(self, image: Image, position: Optional[Position] = None) -> bool:
+    def _add_image(self, image: Image, position: Optional[Position] = None) -> bool:
         """
         Adds an image to the PDF document.
-        Equivalent to addImage() methods in Java client.
 
         Args:
             image: The image object to add
@@ -392,10 +560,9 @@ class ClientV1:
 
         return self._add_object(image)
 
-    def add_paragraph(self, paragraph: Paragraph) -> bool:
+    def _add_paragraph(self, paragraph: Paragraph) -> bool:
         """
         Adds a paragraph to the PDF document.
-        Equivalent to addParagraph() in Java client with validation.
 
         Args:
             paragraph: The paragraph object to add
@@ -417,18 +584,21 @@ class ClientV1:
     def _add_object(self, pdf_object) -> bool:
         """
         Internal method to add any PDF object.
-        Equivalent to addObject() in Java client.
         """
         request_data = AddRequest(pdf_object).to_dict()
         response = self._make_request('POST', '/pdf/add', data=request_data)
         return response.json()
 
-    # Modify Operations
+    def new_paragraph(self) -> ParagraphBuilder:
+        return ParagraphBuilder(self)
+
+    def new_image(self) -> ImageBuilder:
+        return ImageBuilder(self)
 
-    def modify_paragraph(self, object_ref: ObjectRef, new_paragraph: Union[Paragraph, str]) -> bool:
+    # Modify Operations
+    def _modify_paragraph(self, object_ref: ObjectRef, new_paragraph: Union[Paragraph, str]) -> bool:
         """
         Modifies a paragraph object or its text content.
-        Equivalent to modifyParagraph() methods in Java client.
 
         Args:
             object_ref: Reference to the paragraph to modify
@@ -453,10 +623,9 @@ class ClientV1:
 
         return response.json()
 
-    def modify_text_line(self, object_ref: ObjectRef, new_text: str) -> bool:
+    def _modify_text_line(self, object_ref: ObjectRef, new_text: str) -> bool:
         """
         Modifies a text line object.
-        Equivalent to modifyTextLine() in Java client.
 
         Args:
             object_ref: Reference to the text line to modify
@@ -479,7 +648,6 @@ class ClientV1:
     def find_fonts(self, font_name: str, font_size: int) -> List[Font]:
         """
         Finds available fonts matching the specified name and size.
-        Equivalent to findFonts() in Java client.
 
         Args:
             font_name: Name of the font to search for
@@ -502,7 +670,6 @@ class ClientV1:
     def register_font(self, ttf_file: Union[Path, str, bytes, BinaryIO]) -> str:
         """
         Registers a custom font for use in PDF operations.
-        Equivalent to registerFont() in Java client.
 
         Args:
             ttf_file: TTF font file as Path, filename, bytes, or file-like object
@@ -577,7 +744,6 @@ class ClientV1:
     def get_pdf_file(self) -> bytes:
         """
         Downloads the current state of the PDF document with all modifications applied.
-        Equivalent to getPDFFile() in Java client.
 
         Returns:
             PDF file data as bytes with all session modifications applied
@@ -585,10 +751,9 @@ class ClientV1:
         response = self._make_request('GET', f'/session/{self._session_id}/pdf')
         return response.content
 
-    def save_pdf(self, file_path: Union[str, Path]) -> None:
+    def save(self, file_path: Union[str, Path]) -> None:
         """
         Saves the current PDF to a file.
-        Equivalent to savePDF() in Java client.
 
         Args:
             file_path: Path where to save the PDF file
@@ -628,7 +793,23 @@ class ClientV1:
             type=object_type
         )
 
-    def _parse_position(self, pos_data: dict) -> Position:
+    def _parse_form_field_ref(self, obj_data: dict) -> ObjectRef:
+        """Parse JSON object data into ObjectRef instance."""
+        position_data = obj_data.get('position', {})
+        position = self._parse_position(position_data) if position_data else None
+
+        object_type = ObjectType(obj_data['type'])
+
+        return FormFieldRef(
+            internal_id=obj_data['internalId'] if 'internalId' in obj_data else None,
+            position=position,
+            type=object_type,
+            name=obj_data['name'] if 'name' in obj_data else None,
+            value=obj_data['value'] if 'value' in obj_data else None,
+        )
+
+    @staticmethod
+    def _parse_position(pos_data: dict) -> Position:
         """Parse JSON position data into Position instance."""
         position = Position()
         position.page_index = pos_data.get('pageIndex')
@@ -653,11 +834,9 @@ class ClientV1:
 
     # Builder Pattern Support
 
-    def paragraph_builder(self) -> 'ParagraphBuilder':
+    def _paragraph_builder(self) -> 'ParagraphBuilder':
         """
         Creates a new ParagraphBuilder for fluent paragraph construction.
-        Equivalent to paragraphBuilder() in Java client.
-
         Returns:
             A new ParagraphBuilder instance
         """
@@ -673,3 +852,28 @@ class ClientV1:
         """Context manager exit - cleanup if needed."""
         # Could add session cleanup here if API supports it
         pass
+
+    def _to_path_objects(self, path_refs: List[ObjectRef]) -> List[PathObject]:
+        return [PathObject(self, ref.internal_id, ref.type, ref.position) for ref in path_refs]
+
+    def _to_paragraph_objects(self, path_refs: List[ObjectRef]) -> List[ParagraphObject]:
+        return [ParagraphObject(self, ref.internal_id, ref.type, ref.position) for ref in path_refs]
+
+    def _to_textline_objects(self, path_refs: List[ObjectRef]) -> List[TextLineObject]:
+        return [TextLineObject(self, ref.internal_id, ref.type, ref.position) for ref in path_refs]
+
+    def _to_image_objects(self, path_refs: List[ObjectRef]) -> List[ImageObject]:
+        return [ImageObject(self, ref.internal_id, ref.type, ref.position) for ref in path_refs]
+
+    def _to_form_objects(self, path_refs: List[ObjectRef]) -> List[FormObject]:
+        return [FormObject(self, ref.internal_id, ref.type, ref.position) for ref in path_refs]
+
+    def _to_form_field_objects(self, path_refs: List[FormFieldRef]) -> List[FormFieldObject]:
+        return [FormFieldObject(self, ref.internal_id, ref.type, ref.position, ref.name, ref.value) for ref in
+                path_refs]
+
+    def _to_page_objects(self, path_refs: List[ObjectRef]) -> List[PageObject]:
+        return [PageObject(self, ref.internal_id, ref.type, ref.position) for ref in path_refs]
+
+    def _to_page_object(self, ref: ObjectRef) -> PageObject:
+        return PageObject(self, ref.internal_id, ref.type, ref.position)

pdfdancer/types.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from . import ObjectType, Position, ObjectRef, Point, Paragraph, Font, Color, FormFieldRef
+
+
+@dataclass
+class BoundingRect:
+    x: float
+    y: float
+    width: Optional[float] = None
+    height: Optional[float] = None
+
+
+class UnsupportedOperation(Exception):
+    def __init__(self, msg: str):
+        super().__init__(msg)
+
+
+class PDFObjectBase:
+    """
+    Base class for all PDF objects (paths, paragraphs, text lines, etc.)
+    providing shared behavior such as position, deletion, and movement.
+    """
+
+    def __init__(self, client: 'PDFDancer', internal_id: str, object_type: ObjectType, position: Position):
+        self._client = client
+        self.position = position
+        self.internal_id = internal_id
+        self.object_type = object_type
+
+    # --------------------------------------------------------------
+    # Core properties
+    # --------------------------------------------------------------
+    def internal_id(self) -> str:
+        """Internal PDFDancer object identifier, e.g. 'PATH_000023'."""
+        return self.internal_id
+
+    def type(self) -> ObjectType:
+        """Enum value representing the PDF object type."""
+        return self.object_type
+
+    def position(self) -> Position:
+        """The geometric position of the object on its page."""
+        return self.position
+
+    @property
+    def page_index(self) -> int:
+        """Page index where this object resides."""
+        return self.position.page_index
+
+    def object_ref(self) -> ObjectRef:
+        return ObjectRef(self.internal_id, self.position, self.object_type)
+
+    # --------------------------------------------------------------
+    # Common actions
+    # --------------------------------------------------------------
+    def delete(self) -> bool:
+        """Delete this object from the PDF document."""
+        return self._client._delete(self.object_ref())
+
+    def move_to(self, x: float, y: float) -> bool:
+        """Move this object to a new position."""
+        return self._client._move(
+            self.object_ref(),
+            Position.at_page_coordinates(self.position.page_index, x, y)
+        )
+
+
+# -------------------------------------------------------------------
+# Subclasses
+# -------------------------------------------------------------------
+
+class PathObject(PDFObjectBase):
+    """Represents a vector path object inside a PDF page."""
+
+    @property
+    def bounding_box(self) -> Optional[BoundingRect]:
+        """Optional bounding rectangle (if available)."""
+        return self.position.bounding_rect
+
+
+class ImageObject(PDFObjectBase):
+    pass
+
+
+class FormObject(PDFObjectBase):
+    pass
+
+
+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.)"""
+
+    def __init__(self, target_obj, object_ref):
+        self._color = None
+        self._position = None
+        self._line_spacing = None
+        self._font_size = None
+        self._font_name = None
+        self._new_text = None
+        self._target_obj = target_obj
+        self._object_ref = object_ref
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if not exc_type:
+            self.apply()
+
+    # --- Common fluent configuration methods ---
+
+    def replace(self, text: str):
+        self._new_text = text
+        return self
+
+    def font(self, font_name: str, font_size: float):
+        self._font_name = font_name
+        self._font_size = font_size
+        return self
+
+    def color(self, color):
+        self._color = color
+        return self
+
+    def line_spacing(self, line_spacing: float):
+        self._line_spacing = line_spacing
+        return self
+
+    def move_to(self, x: float, y: float):
+        self._position = Position().at_coordinates(Point(x, y))
+        return self
+
+    # --- Abstract method: implemented by subclass ---
+    def apply(self):
+        raise NotImplementedError("Subclasses must implement apply()")
+
+
+class ParagraphEdit(BaseTextEdit):
+    def apply(self) -> bool:
+        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
+            return self._target_obj._client._modify_paragraph(self._object_ref, self._new_text)
+        else:
+            new_paragraph = Paragraph(
+                position=self._position,
+                line_spacing=self._line_spacing if self._line_spacing is not None else DEFAULT_LINE_SPACING,
+                font=Font(name=self._font_name, size=self._font_size),
+                text_lines=_process_text_lines(self._new_text),
+                color=self._color if self._color is not None else DEFAULT_COLOR,
+            )
+            # noinspection PyProtectedMember
+            return self._target_obj._client._modify_paragraph(self._object_ref, new_paragraph)
+
+
+class TextLineEdit(BaseTextEdit):
+    def apply(self) -> bool:
+        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
+            return self._target_obj._client._modify_text_line(self._object_ref, self._new_text)
+        else:
+            raise UnsupportedOperation("TextLineEdit cannot be applied to text lines")
+
+
+class ParagraphObject(PDFObjectBase):
+    """Represents a paragraph text block inside a PDF page."""
+
+    def edit(self) -> ParagraphEdit:
+        return ParagraphEdit(self, self.object_ref())
+
+
+class TextLineObject(PDFObjectBase):
+    """Represents a single line of text inside a PDF page."""
+
+    def edit(self) -> TextLineEdit:
+        return TextLineEdit(self, self.object_ref())
+
+
+class FormFieldEdit:
+    def __init__(self, form_field: 'FormFieldObject', object_ref: FormFieldRef):
+        self.form_field = form_field
+        self.object_ref = object_ref
+
+    def value(self, new_value: str) -> 'FormFieldEdit':
+        self.form_field.value = new_value
+        return self
+
+    def apply(self) -> bool:
+        # noinspection PyProtectedMember
+        return self.form_field._client._change_form_field(self.object_ref, self.form_field.value)
+
+
+class FormFieldObject(PDFObjectBase):
+    def __init__(self, client: 'PDFDancer', internal_id: str, object_type: ObjectType, position: Position,
+                 field_name: str, field_value: str):
+        super().__init__(client, internal_id, object_type, position)
+        self.name = field_name
+        self.value = field_value
+
+    def edit(self) -> FormFieldEdit:
+        return FormFieldEdit(self, self.object_ref())
+
+    def object_ref(self) -> FormFieldRef:
+        ref = FormFieldRef(self.internal_id, self.position, self.object_type)
+        ref.name = self.name
+        ref.value = self.value
+        return ref
+
+
+class PageObject(PDFObjectBase):
+
+    def delete(self) -> bool:
+        # noinspection PyProtectedMember
+        return self._client._delete_page(self.object_ref())

{pdfdancer_client_python-0.1.2.dist-info → pdfdancer_client_python-0.2.3.dist-info}/METADATA

@@ -1,19 +1,18 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.1.2
+Version: 0.2.3
 Summary: Python client for PDFDancer API
-Author-email: TFC <info@example.com>
+Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: MIT
-Project-URL: Homepage, https://github.com/tfc/pdfdancer-python
-Project-URL: Repository, https://github.com/tfc/pdfdancer-python.git
+Project-URL: Homepage, https://www.pdfdancer.com/
+Project-URL: Repository, https://github.com/MenschMachine/pdfdancer-client-python
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.25.0
 Requires-Dist: pydantic>=1.8.0
@@ -60,18 +59,18 @@ paragraphs = client.find_paragraphs(None)
 images = client.find_images(Position.at_page(0))
 
 # Manipulation operations (mirrors Java client methods)
-client.delete(paragraphs[0])
-client.move(images[0], Position.at_page_coordinates(0, 100, 200))
+client._delete(paragraphs[0])
+client._move(images[0], Position.at_page_coordinates(0, 100, 200))
 
 # Builder pattern (mirrors Java ParagraphBuilder)
-paragraph = (client.paragraph_builder()
+paragraph = (client._paragraph_builder()
              .from_string("Hello World")
              .with_font(Font("Arial", 12))
              .with_color(Color(255, 0, 0))
              .with_position(Position.at_page(0))
              .build())
 
-client.add_paragraph(paragraph)
+client._add_paragraph(paragraph)
 
 # Save result (mirrors Java savePDF)
 client.save_pdf("output.pdf")
@@ -85,7 +84,7 @@ from pdfdancer import ClientV1
 # Automatic resource management
 with ClientV1(token="jwt-token", pdf_data="input.pdf") as client:
     paragraphs = client.find_paragraphs(None)
-    client.delete(paragraphs[0])
+    client._delete(paragraphs[0])
     client.save_pdf("output.pdf")
     # Session automatically cleaned up
 ```
@@ -105,60 +104,63 @@ client = ClientV1(token="jwt-token", pdf_data=pdf_file, base_url="https://api.se
 ```
 
 ### Find Operations
+
 ```python
 # Generic find (Java: client.find())
-objects = client.find(ObjectType.PARAGRAPH, position)
+objects = client._find(ObjectType.PARAGRAPH, position)
 
 # Specific finders (Java: client.findParagraphs(), etc.)
-paragraphs = client.find_paragraphs(position)
-images = client.find_images(position)
-forms = client.find_forms(position)
-paths = client.find_paths(position)
-text_lines = client.find_text_lines(position)
+paragraphs = client._find_paragraphs(position)
+images = client._find_images(position)
+forms = client._find_form_x_objects(position)
+paths = client._find_paths(position)
+text_lines = client._find_text_lines(position)
 
 # Page operations (Java: client.getPages(), client.getPage())
 pages = client.get_pages()
-page = client.get_page(1)  # 1-based indexing
+page = client._get_page(1)  # 1-based indexing
 ```
 
 ### Manipulation Operations
+
 ```python
 # Delete (Java: client.delete(), client.deletePage())
-result = client.delete(object_ref)
-result = client.delete_page(page_ref)
+result = client._delete(object_ref)
+result = client._delete_page(page_ref)
 
 # Move (Java: client.move())
-result = client.move(object_ref, new_position)
+result = client._move(object_ref, new_position)
 
 # Add (Java: client.addImage(), client.addParagraph())
-result = client.add_image(image, position)
-result = client.add_paragraph(paragraph)
+result = client._add_image(image, position)
+result = client._add_paragraph(paragraph)
 
 # Modify (Java: client.modifyParagraph(), client.modifyTextLine())
-result = client.modify_paragraph(ref, new_paragraph)
+result = client._modify_paragraph(ref, new_paragraph)
 result = client.modify_text_line(ref, "new text")
 ```
 
 ### Builder Pattern
+
 ```python
 # Java: client.paragraphBuilder()
-builder = client.paragraph_builder()
+builder = client._paragraph_builder()
 
 # Fluent interface (mirrors Java ParagraphBuilder)
 paragraph = (builder
-    .from_string("Text content")           # Java: fromString()
-    .with_font(Font("Arial", 12))          # Java: withFont()
-    .with_color(Color(255, 0, 0))          # Java: withColor()
-    .with_line_spacing(1.5)                # Java: withLineSpacing()
-    .with_position(position)               # Java: withPosition()
-    .build())                              # Java: build()
+             .from_string("Text content")  # Java: fromString()
+             .with_font(Font("Arial", 12))  # Java: withFont()
+             .with_color(Color(255, 0, 0))  # Java: withColor()
+             .with_line_spacing(1.5)  # Java: withLineSpacing()
+             .with_position(position)  # Java: withPosition()
+             .build())  # Java: build()
 
 # Font file registration (Java: withFont(File, double))
 paragraph = (builder
-    .with_font_file("custom.ttf", 14.0)    # Java: withFont(File, double)
-    .from_string("Custom font text")
-    .with_position(position)
-    .build())
+             .with_font_file("custom.ttf", 14.0)  # Java: withFont(File, double)
+             .from_string("Custom font text")
+             .with_position(position)
+             .build())
 ```
 
 ### Position API
@@ -171,8 +173,8 @@ position = Position.at_page(0)
 position = Position.at_page_coordinates(0, 100, 200)
 
 # Coordinate access (Java: position.getX(), position.getY())
-x = position.get_x()
-y = position.get_y()
+x = position.x()
+y = position.y()
 
 # Movement (Java: position.moveX(), position.moveY())
 position.move_x(50.0)

pdfdancer_client_python-0.2.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+pdfdancer/__init__.py,sha256=5HVIUIEESA_GQHKJhItdperrx079oFZM028ciSt2Z9o,1004
+pdfdancer/exceptions.py,sha256=Y5zwNVZprsv2hvKX304cXWobJt11nrEhCzLklu2wiO8,1567
+pdfdancer/image_builder.py,sha256=Omxc2LcieJ1MbvWBXR5_sfia--eAucTUe0KWgr22HYo,842
+pdfdancer/models.py,sha256=SmkKScr47uVs6FCWUAVIg6rucYrYHvbIxZngyA50XyI,15498
+pdfdancer/paragraph_builder.py,sha256=bAfwX9U2YT1UGX9EKkPnGYvGK3SQP3X1ocxlgyLE_rU,8872
+pdfdancer/pdfdancer_v1.py,sha256=pDRrUfbUpk7Ho2d57ouOPOd-nCwlcCUQWfsObfXgMGA,34334
+pdfdancer/types.py,sha256=lcYnqCFgnrGpplSPCxKh3X9AZ3-9t-lJqMH5ZLew_I4,8188
+pdfdancer_client_python-0.2.3.dist-info/METADATA,sha256=vULfZlPY62-n4THslmEZma4DSkZ1SszgFf6pWN8n8sc,9253
+pdfdancer_client_python-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.3.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.3.dist-info/RECORD,,

pdfdancer_client_python-0.1.2.dist-info/RECORD

@@ -1,9 +0,0 @@
-pdfdancer/__init__.py,sha256=uSIbj9rI81_o_asKd6Er15rI_Fa-TcMl1N7BEq7P_Gc,964
-pdfdancer/client_v1.py,sha256=M4A_q8iZ2d9uUrmDSRrVRw1LADpM-MInti_FKsBRAnM,25147
-pdfdancer/exceptions.py,sha256=Y5zwNVZprsv2hvKX304cXWobJt11nrEhCzLklu2wiO8,1567
-pdfdancer/models.py,sha256=MHp5_iFpvHhJC7-kN71D5xc2NHhFj0PMSF9afmxdjL8,14064
-pdfdancer/paragraph_builder.py,sha256=uBMSNhL3b5DgbCJWf5VFWxgm3RpsQyQukk67FDd86Bs,8727
-pdfdancer_client_python-0.1.2.dist-info/METADATA,sha256=nv1xrRZG_kIIL1-2iFSX8N5l0UKiIITqUZsmBnlPOWo,9248
-pdfdancer_client_python-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.1.2.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.1.2.dist-info/RECORD,,