pdfdancer-client-python 0.2.12__py3-none-any.whl → 0.2.14__py3-none-any.whl

pdfdancer/__init__.py

@@ -12,7 +12,7 @@ from .exceptions import (
 )
 from .models import (
     ObjectRef, Position, ObjectType, Font, Color, Image, BoundingRect, Paragraph, FormFieldRef, TextObjectRef,
-    PositionMode, ShapeType, Point, StandardFonts
+    PageRef, PositionMode, ShapeType, Point, StandardFonts, PageSize, Orientation
 )
 from .paragraph_builder import ParagraphBuilder
 
@@ -30,10 +30,13 @@ __all__ = [
     "Paragraph",
     "FormFieldRef",
     "TextObjectRef",
+    "PageRef",
     "PositionMode",
     "ShapeType",
     "Point",
     "StandardFonts",
+    "PageSize",
+    "Orientation",
     "PdfDancerException",
     "FontNotFoundException",
     "ValidationException",

pdfdancer/models.py

@@ -1,11 +1,113 @@
 """
 Model classes for the PDFDancer Python client.
-Closely mirrors the Java model classes with Python conventions.
 """
 
 from dataclasses import dataclass
 from enum import Enum
-from typing import Optional, List, Any
+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."""
+
+    name: Optional[str]
+    width: float
+    height: float
+
+    _STANDARD_SIZES: ClassVar[Dict[str, Tuple[float, float]]] = {
+        "A4": (595.0, 842.0),
+        "LETTER": (612.0, 792.0),
+        "LEGAL": (612.0, 1008.0),
+        "TABLOID": (792.0, 1224.0),
+        "A3": (842.0, 1191.0),
+        "A5": (420.0, 595.0),
+    }
+
+    # Convenience aliases populated after class definition; annotated for type checkers.
+    A4: ClassVar['PageSize']
+    LETTER: ClassVar['PageSize']
+    LEGAL: ClassVar['PageSize']
+    TABLOID: ClassVar['PageSize']
+    A3: ClassVar['PageSize']
+    A5: ClassVar['PageSize']
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.width, (int, float)) or not isinstance(self.height, (int, float)):
+            raise TypeError("Page width and height must be numeric")
+        if self.width <= 0 or self.height <= 0:
+            raise ValueError("Page width and height must be positive values")
+
+        width = float(self.width)
+        height = float(self.height)
+        object.__setattr__(self, 'width', width)
+        object.__setattr__(self, 'height', height)
+
+        if self.name is not None:
+            if not isinstance(self.name, str):
+                raise TypeError("Page size name must be a string when provided")
+            normalized_name = self.name.strip().upper()
+            object.__setattr__(self, 'name', normalized_name if normalized_name else None)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "name": self.name,
+            "width": self.width,
+            "height": self.height,
+        }
+
+    @classmethod
+    def from_name(cls, name: str) -> 'PageSize':
+        """Create a page size from a known standard name."""
+        if not name or not isinstance(name, str):
+            raise ValueError("Page size name must be a non-empty string")
+        normalized = name.strip().upper()
+        if normalized not in cls._STANDARD_SIZES:
+            raise ValueError(f"Unknown page size name: {name}")
+        width, height = cls._STANDARD_SIZES[normalized]
+        return cls(name=normalized, width=width, height=height)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> 'PageSize':
+        """Create a page size from a dictionary-like object."""
+        width = data.get('width') if isinstance(data, Mapping) else None
+        height = data.get('height') if isinstance(data, Mapping) else None
+        if width is None or height is None:
+            raise ValueError("Page size dictionary must contain 'width' and 'height'")
+        name = data.get('name') if isinstance(data, Mapping) else None
+        return cls(name=name, width=width, height=height)
+
+    @classmethod
+    def coerce(cls, value: Union['PageSize', str, Mapping[str, Any]]) -> 'PageSize':
+        """Normalize various page size inputs into a PageSize instance."""
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, str):
+            return cls.from_name(value)
+        if isinstance(value, Mapping):
+            return cls.from_dict(value)
+        raise TypeError(f"Cannot convert type {type(value)} to PageSize")
+
+    @classmethod
+    def standard_names(cls) -> List[str]:
+        """Return a list of supported standard page size names."""
+        return sorted(cls._STANDARD_SIZES.keys())
+
+
+# Populate convenience constants for standard sizes.
+PageSize.A4 = PageSize.from_name("A4")
+PageSize.LETTER = PageSize.from_name("LETTER")
+PageSize.LEGAL = PageSize.from_name("LEGAL")
+PageSize.TABLOID = PageSize.from_name("TABLOID")
+PageSize.A3 = PageSize.from_name("A3")
+PageSize.A5 = PageSize.from_name("A5")
+
+
+class Orientation(Enum):
+    """Page orientation options."""
+    PORTRAIT = "PORTRAIT"
+    LANDSCAPE = "LANDSCAPE"
 
 
 class StandardFonts(Enum):
@@ -365,6 +467,19 @@ class MoveRequest:
         }
 
 
+@dataclass
+class PageMoveRequest:
+    """Request object for moving pages within the document."""
+    from_page_index: int
+    to_page_index: int
+
+    def to_dict(self) -> dict:
+        return {
+            "fromPageIndex": self.from_page_index,
+            "toPageIndex": self.to_page_index
+        }
+
+
 @dataclass
 class AddRequest:
     """Request object for add operations."""
@@ -547,3 +662,21 @@ class TextObjectRef(ObjectRef):
     def get_children(self) -> List['TextObjectRef']:
         """Get the child text objects."""
         return self.children
+
+
+@dataclass
+class PageRef(ObjectRef):
+    """
+    Represents a page reference with additional page-specific properties.
+    Extends ObjectRef to include page size and orientation.
+    """
+    page_size: Optional[PageSize]
+    orientation: Optional[Orientation]
+
+    def get_page_size(self) -> Optional[PageSize]:
+        """Get the page size."""
+        return self.page_size
+
+    def get_orientation(self) -> Optional[Orientation]:
+        """Get the page orientation."""
+        return self.orientation

pdfdancer/paragraph_builder.py

@@ -6,6 +6,7 @@ Closely mirrors the Java ParagraphBuilder class with Python conventions.
 from pathlib import Path
 from typing import Optional, Union
 
+from . import StandardFonts
 from .exceptions import ValidationException
 from .models import Paragraph, Font, Color, Position
 
@@ -60,7 +61,7 @@ class ParagraphBuilder:
 
         return self
 
-    def font(self, font_name: str, font_size: float) -> 'ParagraphBuilder':
+    def font(self, font_name: str | StandardFonts, font_size: float) -> 'ParagraphBuilder':
         """
         Set the font for the paragraph using an existing Font object.
         Equivalent to withFont(Font) in Java ParagraphBuilder.
@@ -75,6 +76,10 @@ class ParagraphBuilder:
         Raises:
             ValidationException: If font is None
         """
+        # If font_name is an enum member, use its value
+        if isinstance(font_name, StandardFonts):
+            font_name = font_name.value
+
         font = Font(font_name, font_size)
         if font is None:
             raise ValidationException("Font cannot be null")
@@ -185,7 +190,7 @@ class ParagraphBuilder:
         self._paragraph.set_position(position)
         return self
 
-    def build(self) -> Paragraph:
+    def _build(self) -> Paragraph:
         """
         Build and return the final Paragraph object.
         Equivalent to build() in Java ParagraphBuilder.
@@ -267,7 +272,7 @@ class ParagraphBuilder:
         return lines
 
     def add(self):
-        self._client._add_paragraph(self.build())
+        self._client._add_paragraph(self._build())
 
 
 class ParagraphPageBuilder(ParagraphBuilder):

pdfdancer/pdfdancer_v1.py

@@ -8,9 +8,12 @@ Provides session-based PDF manipulation operations with strict validation.
 import json
 import os
 from pathlib import Path
-from typing import List, Optional, Union, BinaryIO
+from typing import List, Optional, Union, BinaryIO, Mapping, Any
 
 import requests
+from dotenv import load_dotenv
+
+load_dotenv()
 
 from . import ParagraphBuilder
 from .exceptions import (
@@ -22,21 +25,32 @@ from .exceptions import (
 )
 from .image_builder import ImageBuilder
 from .models import (
-    ObjectRef, Position, ObjectType, Font, Image, Paragraph, FormFieldRef, TextObjectRef,
-    FindRequest, DeleteRequest, MoveRequest, AddRequest, ModifyRequest, ModifyTextRequest, ChangeFormFieldRequest,
-    ShapeType, PositionMode
+    ObjectRef, Position, ObjectType, Font, Image, Paragraph, FormFieldRef, TextObjectRef, PageRef,
+    FindRequest, DeleteRequest, MoveRequest, PageMoveRequest, AddRequest, ModifyRequest, ModifyTextRequest,
+    ChangeFormFieldRequest,
+    ShapeType, PositionMode, PageSize, Orientation
 )
 from .paragraph_builder import ParagraphPageBuilder
 from .types import PathObject, ParagraphObject, TextLineObject, ImageObject, FormObject, FormFieldObject
 
 
 class PageClient:
-    def __init__(self, page_index: int, root: "PDFDancer"):
+    def __init__(self, page_index: int, root: "PDFDancer", page_size: Optional[PageSize] = None,
+                 orientation: Optional[Union[Orientation, str]] = Orientation.PORTRAIT):
         self.page_index = page_index
         self.root = root
         self.object_type = ObjectType.PAGE
         self.position = Position.at_page(page_index)
         self.internal_id = f"PAGE-{page_index}"
+        self.page_size = page_size
+        if isinstance(orientation, str):
+            normalized = orientation.strip().upper()
+            try:
+                self.orientation = Orientation(normalized)
+            except ValueError:
+                self.orientation = normalized
+        else:
+            self.orientation = orientation
 
     def select_paths_at(self, x: float, y: float) -> List[PathObject]:
         # noinspection PyProtectedMember
@@ -121,20 +135,71 @@ class PageClient:
         return self.root._to_form_field_objects(self.root._find_form_fields(position))
 
     @classmethod
-    def from_ref(cls, root: 'PDFDancer', object_ref: ObjectRef) -> 'PageClient':
-        page_client = PageClient(page_index=object_ref.position.page_index, root=root)
+    def from_ref(cls, root: 'PDFDancer', page_ref: PageRef) -> 'PageClient':
+        page_client = PageClient(
+            page_index=page_ref.position.page_index,
+            root=root,
+            page_size=page_ref.page_size,
+            orientation=page_ref.orientation
+        )
+        page_client.internal_id = page_ref.internal_id
+        if page_ref.position is not None:
+            page_client.position = page_ref.position
+            page_client.page_index = page_ref.position.page_index
         return page_client
 
     def delete(self) -> bool:
         # noinspection PyProtectedMember
         return self.root._delete_page(self._ref())
 
+    def move_to(self, target_page_index: int) -> bool:
+        """Move this page to a different index within the document."""
+        if target_page_index is None or target_page_index < 0:
+            raise ValidationException(f"Target page index must be >= 0, got {target_page_index}")
+
+        # noinspection PyProtectedMember
+        moved = self.root._move_page(self.page_index, target_page_index)
+        if moved:
+            self.page_index = target_page_index
+            self.position = Position.at_page(target_page_index)
+        return moved
+
     def _ref(self):
         return ObjectRef(internal_id=self.internal_id, position=self.position, type=self.object_type)
 
     def new_paragraph(self):
         return ParagraphPageBuilder(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)))
+
+    def select_elements(self):
+        """
+        Select all elements (paragraphs, images, paths, forms) on this page.
+
+        Returns:
+            List of all PDF objects on this page
+        """
+        result = []
+        result.extend(self.select_paragraphs())
+        result.extend(self.select_text_lines())
+        result.extend(self.select_images())
+        result.extend(self.select_paths())
+        result.extend(self.select_forms())
+        result.extend(self.select_form_fields())
+        return result
+
+    @property
+    def size(self):
+        """Property alias for page size."""
+        return self.page_size
+
+    @property
+    def page_orientation(self):
+        """Property alias for orientation."""
+        return self.orientation
+
 
 class PDFDancer:
     """
@@ -197,12 +262,57 @@ class PDFDancer:
     def new(cls,
             token: Optional[str] = None,
             base_url: Optional[str] = None,
-            timeout: float = 30.0) -> "PDFDancer":
+            timeout: float = 30.0,
+            page_size: Optional[Union[PageSize, str, Mapping[str, Any]]] = None,
+            orientation: Optional[Union[Orientation, str]] = None,
+            initial_page_count: int = 1) -> "PDFDancer":
+        """
+        Create a new blank PDF document with optional configuration.
+
+        Args:
+            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environment 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.
+            page_size: Page size for the PDF (default: A4). Accepts `PageSize`, a standard name string, or a
+                mapping with `width`/`height` values.
+            orientation: Page orientation (default: PORTRAIT). Can be Orientation enum or string.
+            initial_page_count: Number of initial blank pages (default: 1).
 
+        Returns:
+            A ready-to-use `PDFDancer` client instance with a blank PDF.
+        """
         resolved_token = cls._resolve_token(token)
         resolved_base_url = cls._resolve_base_url(base_url)
 
-        raise Exception("Unsupported Operation Exception: TODO")
+        # Create a new instance that will call _create_blank_pdf_session
+        instance = object.__new__(cls)
+
+        # Initialize instance variables
+        if not resolved_token or not resolved_token.strip():
+            raise ValidationException("Authentication token cannot be null or empty")
+
+        instance._token = resolved_token.strip()
+        instance._base_url = resolved_base_url.rstrip('/')
+        instance._read_timeout = timeout
+
+        # Create HTTP session for connection reuse
+        instance._session = requests.Session()
+        instance._session.headers.update({
+            'Authorization': f'Bearer {instance._token}'
+        })
+
+        # Create blank PDF session
+        instance._session_id = instance._create_blank_pdf_session(
+            page_size=page_size,
+            orientation=orientation,
+            initial_page_count=initial_page_count
+        )
+
+        # Set pdf_bytes to None since we don't have the PDF bytes yet
+        instance._pdf_bytes = None
+
+        return instance
 
     def __init__(self, token: str, pdf_data: Union[bytes, Path, str, BinaryIO],
                  base_url: str, read_timeout: float = 0):
@@ -335,6 +445,22 @@ class PDFDancer:
                 f"Server response: {details}"
             )
 
+    @staticmethod
+    def _cleanup_url_path(base_url: str, path: str) -> str:
+        """
+        Combine base_url and path, ensuring no double slashes.
+
+        Args:
+            base_url: Base URL (may or may not have trailing slash)
+            path: Path segment (may or may not have leading slash)
+
+        Returns:
+            Combined URL with no double slashes
+        """
+        base = base_url.rstrip('/')
+        path = path.lstrip('/')
+        return f"{base}/{path}"
+
     def _create_session(self) -> str:
         """
         Creates a new PDF processing session by uploading the PDF data.
@@ -345,7 +471,7 @@ class PDFDancer:
             }
 
             response = self._session.post(
-                f"{self._base_url}/session/create",
+                self._cleanup_url_path(self._base_url, "/session/create"),
                 files=files,
                 timeout=self._read_timeout if self._read_timeout > 0 else None
             )
@@ -365,6 +491,76 @@ class PDFDancer:
             raise HttpClientException(f"Failed to create session: {error_message}",
                                       response=getattr(e, 'response', None), cause=e) from None
 
+    def _create_blank_pdf_session(self,
+                                  page_size: Optional[Union[PageSize, str, Mapping[str, Any]]] = None,
+                                  orientation: Optional[Union[Orientation, str]] = None,
+                                  initial_page_count: int = 1) -> str:
+        """
+        Creates a new PDF processing session with a blank PDF document.
+
+        Args:
+            page_size: Page size (default: A4). Accepts `PageSize`, a standard name string, or a
+                mapping with `width`/`height` values.
+            orientation: Page orientation (default: PORTRAIT). Can be Orientation enum or string.
+            initial_page_count: Number of initial pages (default: 1)
+
+        Returns:
+            Session ID for the newly created blank PDF
+
+        Raises:
+            SessionException: If session creation fails
+            HttpClientException: If HTTP communication fails
+        """
+        try:
+            # Build request payload
+            request_data = {}
+
+            # Handle page_size - convert to type-safe object with dimensions
+            if page_size is not None:
+                try:
+                    request_data['pageSize'] = PageSize.coerce(page_size).to_dict()
+                except ValueError as exc:
+                    raise ValidationException(str(exc)) from exc
+                except TypeError:
+                    raise ValidationException(f"Invalid page_size type: {type(page_size)}")
+
+            # Handle orientation
+            if orientation is not None:
+                if isinstance(orientation, Orientation):
+                    request_data['orientation'] = orientation.value
+                elif isinstance(orientation, str):
+                    request_data['orientation'] = orientation
+                else:
+                    raise ValidationException(f"Invalid orientation type: {type(orientation)}")
+
+            # Handle initial_page_count with validation
+            if initial_page_count < 1:
+                raise ValidationException(f"Initial page count must be at least 1, got {initial_page_count}")
+            request_data['initialPageCount'] = initial_page_count
+
+            headers = {'Content-Type': 'application/json'}
+            response = self._session.post(
+                self._cleanup_url_path(self._base_url, "/session/new"),
+                json=request_data,
+                headers=headers,
+                timeout=self._read_timeout if self._read_timeout > 0 else None
+            )
+
+            self._handle_authentication_error(response)
+            response.raise_for_status()
+            session_id = response.text.strip()
+
+            if not session_id:
+                raise SessionException("Server returned empty session ID")
+
+            return session_id
+
+        except requests.exceptions.RequestException as e:
+            self._handle_authentication_error(getattr(e, 'response', None))
+            error_message = self._extract_error_message(getattr(e, 'response', None))
+            raise HttpClientException(f"Failed to create blank PDF session: {error_message}",
+                                      response=getattr(e, 'response', None), cause=e) from None
+
     def _make_request(self, method: str, path: str, data: Optional[dict] = None,
                       params: Optional[dict] = None) -> requests.Response:
         """
@@ -378,7 +574,7 @@ class PDFDancer:
         try:
             response = self._session.request(
                 method=method,
-                url=f"{self._base_url}{path}",
+                url=self._cleanup_url_path(self._base_url, path),
                 json=data,
                 params=params,
                 headers=headers,
@@ -528,22 +724,36 @@ class PDFDancer:
         return self._to_textline_objects(self._find_text_lines(None))
 
     def page(self, page_index: int) -> PageClient:
-        return PageClient(page_index, self)
+        """
+        Get a specific page by index, fetching page properties from the server.
+
+        Args:
+            page_index: The 0-based page index
+
+        Returns:
+            PageClient with page properties populated
+        """
+        page_ref = self._get_page(page_index)
+        if page_ref:
+            return PageClient.from_ref(self, page_ref)
+        else:
+            # Fallback to basic PageClient if page not found
+            return PageClient(page_index, self)
 
     # Page Operations
 
     def pages(self) -> List[PageClient]:
         return self._to_page_objects(self._get_pages())
 
-    def _get_pages(self) -> List[ObjectRef]:
+    def _get_pages(self) -> List[PageRef]:
         """
         Retrieves references to all pages in the PDF document.
         """
         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]
+        return [self._parse_page_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[PageRef]:
         """
         Retrieves a reference to a specific page by its page index.
 
@@ -551,7 +761,7 @@ class PDFDancer:
             page_index: The page index to retrieve (1-based indexing)
 
         Returns:
-            Object reference for the specified page, or None if not found
+            Page reference for the specified page, or None if not found
         """
         if page_index < 0:
             raise ValidationException(f"Page index must be >= 0, got {page_index}")
@@ -563,7 +773,7 @@ class PDFDancer:
         if not pages_data:
             return None
 
-        return self._parse_object_ref(pages_data[0])
+        return self._parse_page_ref(pages_data[0])
 
     def _delete_page(self, page_ref: ObjectRef) -> bool:
         """
@@ -583,6 +793,25 @@ class PDFDancer:
         response = self._make_request('DELETE', '/pdf/page/delete', data=request_data)
         return response.json()
 
+    def move_page(self, from_page_index: int, to_page_index: int) -> bool:
+        """Move a page to a different index within the document."""
+        return self._move_page(from_page_index, to_page_index)
+
+    def _move_page(self, from_page_index: int, to_page_index: int) -> bool:
+        """Internal helper to perform the page move operation."""
+        for value, label in ((from_page_index, "from_page_index"), (to_page_index, "to_page_index")):
+            if value is None:
+                raise ValidationException(f"{label} cannot be null")
+            if not isinstance(value, int):
+                raise ValidationException(f"{label} must be an integer, got {type(value)}")
+            if value < 0:
+                raise ValidationException(f"{label} must be >= 0, got {value}")
+
+        request_data = PageMoveRequest(from_page_index, to_page_index).to_dict()
+        response = self._make_request('PUT', '/pdf/page/move', data=request_data)
+        result = response.json()
+        return bool(result)
+
     # Manipulation Operations
 
     def _delete(self, object_ref: ObjectRef) -> bool:
@@ -678,6 +907,10 @@ class PDFDancer:
     def new_paragraph(self) -> ParagraphBuilder:
         return ParagraphBuilder(self)
 
+    def new_page(self):
+        response = self._make_request('POST', '/pdf/page/add', data=None)
+        return self._parse_page_ref(response.json())
+
     def new_image(self) -> ImageBuilder:
         return ImageBuilder(self)
 
@@ -809,7 +1042,7 @@ class PDFDancer:
 
             headers = {'X-Session-Id': self._session_id}
             response = self._session.post(
-                f"{self._base_url}/font/register",
+                self._cleanup_url_path(self._base_url, "/font/register"),
                 files=files,
                 headers=headers,
                 timeout=30
@@ -957,6 +1190,42 @@ class PDFDancer:
 
         return text_object
 
+    def _parse_page_ref(self, obj_data: dict) -> PageRef:
+        """Parse JSON object data into PageRef instance with page-specific properties."""
+        position_data = obj_data.get('position', {})
+        position = self._parse_position(position_data) if position_data else None
+
+        object_type = ObjectType(obj_data['type'])
+
+        # Parse page size if present
+        page_size = None
+        if 'pageSize' in obj_data and isinstance(obj_data['pageSize'], dict):
+            page_size_data = obj_data['pageSize']
+            try:
+                page_size = PageSize.from_dict(page_size_data)
+            except ValueError:
+                page_size = None
+
+        # Parse orientation if present
+        orientation_value = obj_data.get('orientation')
+        orientation = None
+        if isinstance(orientation_value, str):
+            normalized = orientation_value.strip().upper()
+            try:
+                orientation = Orientation(normalized)
+            except ValueError:
+                orientation = None
+        elif isinstance(orientation_value, Orientation):
+            orientation = orientation_value
+
+        return PageRef(
+            internal_id=obj_data.get('internalId'),
+            position=position,
+            type=object_type,
+            page_size=page_size,
+            orientation=orientation
+        )
+
     # Builder Pattern Support
 
     def _paragraph_builder(self) -> 'ParagraphBuilder':
@@ -997,8 +1266,59 @@ class PDFDancer:
         return [FormFieldObject(self, ref.internal_id, ref.type, ref.position, ref.name, ref.value) for ref in
                 refs]
 
-    def _to_page_objects(self, refs: List[ObjectRef]) -> List[PageClient]:
+    def _to_page_objects(self, refs: List[PageRef]) -> List[PageClient]:
         return [PageClient.from_ref(self, ref) for ref in refs]
 
-    def _to_page_object(self, ref: ObjectRef) -> PageClient:
+    def _to_page_object(self, ref: PageRef) -> PageClient:
         return PageClient.from_ref(self, ref)
+
+    def _to_mixed_objects(self, refs: List[ObjectRef]) -> List:
+        """
+        Convert a list of ObjectRefs to their appropriate object types.
+        Handles mixed object types by checking the type of each ref.
+        """
+        result = []
+        for ref in refs:
+            if ref.type == ObjectType.PARAGRAPH:
+                # Need to convert to TextObjectRef first
+                if isinstance(ref, TextObjectRef):
+                    result.append(ParagraphObject(self, ref))
+                else:
+                    # Re-fetch with proper type
+                    text_refs = self._find_paragraphs(ref.position)
+                    result.extend(self._to_paragraph_objects(text_refs))
+            elif ref.type == ObjectType.TEXT_LINE:
+                if isinstance(ref, TextObjectRef):
+                    result.append(TextLineObject(self, ref))
+                else:
+                    text_refs = self._find_text_lines(ref.position)
+                    result.extend(self._to_textline_objects(text_refs))
+            elif ref.type == ObjectType.IMAGE:
+                result.append(ImageObject(self, ref.internal_id, ref.type, ref.position))
+            elif ref.type == ObjectType.PATH:
+                result.append(PathObject(self, ref.internal_id, ref.type, ref.position))
+            elif ref.type == ObjectType.FORM_X_OBJECT:
+                result.append(FormObject(self, ref.internal_id, ref.type, ref.position))
+            elif ref.type == ObjectType.FORM_FIELD:
+                if isinstance(ref, FormFieldRef):
+                    result.append(FormFieldObject(self, ref.internal_id, ref.type, ref.position, ref.name, ref.value))
+                else:
+                    form_refs = self._find_form_fields(ref.position)
+                    result.extend(self._to_form_field_objects(form_refs))
+        return result
+
+    def select_elements(self):
+        """
+        Select all elements (paragraphs, images, paths, forms) in the document.
+
+        Returns:
+            List of all PDF objects in the document
+        """
+        result = []
+        result.extend(self.select_paragraphs())
+        result.extend(self.select_text_lines())
+        result.extend(self.select_images())
+        result.extend(self.select_paths())
+        result.extend(self.select_forms())
+        result.extend(self.select_form_fields())
+        return result

{pdfdancer_client_python-0.2.12.dist-info → pdfdancer_client_python-0.2.14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.2.12
+Version: 0.2.14
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: MIT
@@ -9,28 +9,39 @@ Project-URL: Repository, https://github.com/MenschMachine/pdfdancer-client-pytho
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.25.0
 Requires-Dist: pydantic>=1.8.0
 Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: python-dotenv>=0.19.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
 Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: flake8>=5.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: isort>=5.10.0; extra == "dev"
+Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
 
 # PDFDancer Python Client
 
-Automate PDF clean-up, redaction, form filling, and content injection against the PDFDancer API from Python. The client gives you page-scoped selectors, fluent editors, and builders so you can read, modify, and export PDFs programmatically in just a few lines.
+Automate PDF clean-up, redaction, form filling, and content injection against the PDFDancer API from Python. The client
+gives you page-scoped selectors, fluent editors, and builders so you can read, modify, and export PDFs programmatically
+in just a few lines.
+
+Latest schema version available at https://bucket.pdfdancer.com/api-doc/development-0.0.yml.
 
 ## Highlights
 
-- Locate anything inside a PDF—paragraphs, text lines, images, vector paths, pages, AcroForm fields—by page, coordinates, or text prefixes
+- Locate anything inside a PDF—paragraphs, text lines, images, vector paths, pages, AcroForm fields—by page,
+  coordinates, or text prefixes
 - Edit or delete existing content with fluent paragraph/text editors and safe apply-on-exit context managers
 - Fill or update form fields and propagate the changes back to the document instantly
 - Add brand-new content with paragraph/image builders, custom fonts, and precise page positioning
@@ -47,7 +58,7 @@ Automate PDF clean-up, redaction, form filling, and content injection against th
 
 ## Requirements
 
-- Python 3.9 or newer
+- Python 3.10 or newer
 - A PDFDancer API token (set `PDFDANCER_TOKEN` or pass `token=...`)
 - Network access to a PDFDancer service (defaults to `https://api.pdfdancer.com`; override with `PDFDANCER_BASE_URL`)
 
@@ -67,21 +78,21 @@ from pathlib import Path
 from pdfdancer import Color, PDFDancer
 
 with PDFDancer.open(
-    pdf_data=Path("input.pdf"),
-    token="your-api-token",  # optional when PDFDANCER_TOKEN is set
-    base_url="https://api.pdfdancer.com",
+        pdf_data=Path("input.pdf"),
+        token="your-api-token",  # optional when PDFDANCER_TOKEN is set
+        base_url="https://api.pdfdancer.com",
 ) as pdf:
     # Locate existing content
     heading = pdf.page(0).select_paragraphs_starting_with("Executive Summary")[0]
     heading.edit().replace("Overview").apply()
 
     # Add a new paragraph using the fluent builder
-    pdf.new_paragraph() \
-        .text("Generated with PDFDancer") \
-        .font("Helvetica", 12) \
-        .color(Color(70, 70, 70)) \
-        .line_spacing(1.4) \
-        .at(page_index=0, x=72, y=520) \
+    pdf.new_paragraph()
+        .text("Generated with PDFDancer")
+        .font("Helvetica", 12)
+        .color(Color(70, 70, 70))
+        .line_spacing(1.4)
+        .at(page_index=0, x=72, y=520)
         .add()
 
     # Persist the modified document
@@ -107,7 +118,8 @@ with PDFDancer.open("report.pdf") as pdf:  # environment variables provide token
     print(page.internal_id, page.position.bounding_rect)
 ```
 
-Selectors return rich objects (`ParagraphObject`, `TextLineObject`, `ImageObject`, `FormFieldObject`, etc.) with helpers such as `delete()`, `move_to(x, y)`, or `edit()` depending on the object type.
+Selectors return rich objects (`ParagraphObject`, `TextLineObject`, `ImageObject`, `FormFieldObject`, etc.) with helpers
+such as `delete()`, `move_to(x, y)`, or `edit()` depending on the object type.
 
 ## Editing Text and Forms
 
@@ -116,11 +128,11 @@ with PDFDancer.open("report.pdf") as pdf:
     paragraph = pdf.page(0).select_paragraphs_starting_with("Disclaimer")[0]
 
     # Chain updates explicitly…
-    paragraph.edit() \
-        .replace("Updated disclaimer text") \
-        .font("Roboto-Regular", 11) \
-        .line_spacing(1.1) \
-        .move_to(72, 140) \
+    paragraph.edit()
+        .replace("Updated disclaimer text")
+        .font("Roboto-Regular", 11)
+        .line_spacing(1.1)
+        .move_to(72, 140)
         .apply()
 
     # …or use the context manager to auto-apply on success
@@ -141,16 +153,16 @@ with PDFDancer.open("report.pdf") as pdf:
     pdf.register_font("/path/to/custom.ttf")
 
     # Paragraphs
-    pdf.new_paragraph() \
-        .text("Greetings from PDFDancer!") \
-        .font(fonts[0].name, fonts[0].size) \
-        .at(page_index=0, x=220, y=480) \
+    pdf.new_paragraph()
+        .text("Greetings from PDFDancer!")
+        .font(fonts[0].name, fonts[0].size)
+        .at(page_index=0, x=220, y=480)
         .add()
 
     # Raster images
-    pdf.new_image() \
-        .from_file(Path("logo.png")) \
-        .at(page=0, x=48, y=700) \
+    pdf.new_image()
+        .from_file(Path("logo.png"))
+        .at(page=0, x=48, y=700)
         .add()
 ```
 
@@ -175,8 +187,7 @@ Wrap complex workflows in `try/except` blocks to surface actionable errors to yo
 ```bash
 python -m venv venv
 source venv/bin/activate  # Windows: venv\Scripts\activate
-pip install -e .
-pip install -r requirements-dev.txt
+pip install -e ".[dev]"
 
 pytest -q          # run the fast unit suite
 pytest tests/e2e   # integration tests (requires live API + fixtures)

pdfdancer_client_python-0.2.14.dist-info/RECORD

@@ -0,0 +1,11 @@
+pdfdancer/__init__.py,sha256=STOBUkVrBG7SbgoT6wM6tfwBVbjUiQ9JTpmznJwBF94,1158
+pdfdancer/exceptions.py,sha256=Y5zwNVZprsv2hvKX304cXWobJt11nrEhCzLklu2wiO8,1567
+pdfdancer/image_builder.py,sha256=Omxc2LcieJ1MbvWBXR5_sfia--eAucTUe0KWgr22HYo,842
+pdfdancer/models.py,sha256=yhatfgMWxYareL7J20Wz_6-V7oCzrqX35oZdNJ8UFJM,22984
+pdfdancer/paragraph_builder.py,sha256=pgFTkyhYrx4VQDKy4Vhp-042OMlJOD8D0MW9flkvC7Y,9410
+pdfdancer/pdfdancer_v1.py,sha256=uHcn-Thh5dQA8FnC-YojwkfzdGokYeQEUyiz41lut2c,53296
+pdfdancer/types.py,sha256=SOmYP49XPVy6DZ4JXSJrfy0Aww-Tv7QjZCDnOB8VTT4,11860
+pdfdancer_client_python-0.2.14.dist-info/METADATA,sha256=Pqhnjgfz_SoLD0zOJNAGg-otbszgdc4HG39v1iRGgf4,7060
+pdfdancer_client_python-0.2.14.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.14.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.14.dist-info/RECORD,,

pdfdancer_client_python-0.2.12.dist-info/RECORD

@@ -1,11 +0,0 @@
-pdfdancer/__init__.py,sha256=71HwLjHHPsCQMTUtLHYAwzslhF3PqN5g1QwMr4HbKSQ,1076
-pdfdancer/exceptions.py,sha256=Y5zwNVZprsv2hvKX304cXWobJt11nrEhCzLklu2wiO8,1567
-pdfdancer/image_builder.py,sha256=Omxc2LcieJ1MbvWBXR5_sfia--eAucTUe0KWgr22HYo,842
-pdfdancer/models.py,sha256=ZoB5ZP1jaZsubqzhMr9W9nsIUirVUty_FkRiPZWq8vY,18276
-pdfdancer/paragraph_builder.py,sha256=mjV36-XOqcYATfIjSOy7_SBO0EKXjsAtMqYL8IaowGU,9218
-pdfdancer/pdfdancer_v1.py,sha256=XgcyKHPOBMI5vNM86ZRhRvJFA3wB7DTcWwDt6tHQxpI,39851
-pdfdancer/types.py,sha256=SOmYP49XPVy6DZ4JXSJrfy0Aww-Tv7QjZCDnOB8VTT4,11860
-pdfdancer_client_python-0.2.12.dist-info/METADATA,sha256=XHEG0LuL-bi7MQyYVUX2RWrq6mutyVlLcYSlqiUzMAg,6770
-pdfdancer_client_python-0.2.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.12.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.12.dist-info/RECORD,,