pdfdancer-client-python 0.2.28__tar.gz → 0.3.1__tar.gz

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/.github/workflows/ci.yml

@@ -2,9 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [ main, staging, develop, development, dev ]
+    branches: [ '**' ]
   pull_request:
-    branches: [ main, staging, develop, development, dev ]
+    branches: [ '**' ]
   workflow_dispatch:
 
 jobs:
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
-      max-parallel: 4
+      max-parallel: 2
       matrix:
         python-version: [ '3.12' ]
 
@@ -57,6 +57,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
+      max-parallel: 2
       matrix:
         os: [ ubuntu-latest, windows-latest ]
         python-version: [ '3.10', '3.11', '3.12', '3.13' ]

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/.gitignore

@@ -17,3 +17,4 @@ __pycache__/
 *.so
 .Python
 /.run/
+/build

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/CLAUDE.md

@@ -83,7 +83,7 @@ pdf.save("output.pdf")
 - **Dual initialization**: `PDFDancer.open()` for existing PDFs, `PDFDancer.new()` for blank PDFs
 - **Session-based operations**: All constructors create server session automatically
 - **Object-oriented API**: Selected objects (paragraphs, images, etc.) have methods like `.delete()`, `.move()`
-- **Page-level operations**: `pdf.page(index)` provides page-scoped selections and operations
+- **Page-level operations**: `pdf.page(number)` provides page-scoped selections and operations
 - **Builder pattern**: `new_paragraph()` and `new_image()` for fluent construction
 - **Strict validation**: All validation matches Java client exactly
 - **Exception handling**: FontNotFoundException, ValidationException, HttpClientException, etc.
@@ -188,7 +188,7 @@ page.delete()
 ### API Design
 
 - **Use object-oriented patterns**: Selected objects should have methods (`.delete()`, `.move()`, etc.)
-- **Provide page-level operations**: `pdf.page(index)` for page-scoped selections
+- **Provide page-level operations**: `pdf.page(number)` for page-scoped selections
 - **Support fluent builders**: `new_paragraph()` and `new_image()` return builder instances
 - **Use snake_case for methods**: `select_paragraphs()`, `select_images_at()`, etc.
 

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.2.28
+Version: 0.3.1
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 
@@ -251,7 +251,7 @@ pixel-perfect control from Python. The same API is also available for TypeScript
 
 ## Highlights
 
-- Locate paragraphs, text lines, images, vector paths, form fields, and pages by index, coordinates, or text prefixes.
+- Locate paragraphs, text lines, images, vector paths, form fields, and pages by page number, coordinates, or text prefixes.
 - Edit existing content in place with fluent editors and context managers that apply changes safely.
 - Programmatically control third-party PDFs—modify invoices, contracts, and reports you did not author.
 - Add content with precise XY positioning using paragraph and image builders, custom fonts, and color helpers.
@@ -300,7 +300,7 @@ with PDFDancer.open(
         .font(StandardFonts.HELVETICA, 12) \
         .color(Color(70, 70, 70)) \
         .line_spacing(1.4) \
-        .at(page_index=0, x=72, y=520) \
+        .at(page_number=0, x=72, y=520) \
         .add()
 
     # Persist the modified document
@@ -321,7 +321,7 @@ with PDFDancer.new(token="your-api-token") as pdf:
         .font(StandardFonts.TIMES_BOLD, 18) \
         .color(Color(10, 10, 80)) \
         .line_spacing(1.2) \
-        .at(page_index=0, x=72, y=730) \
+        .at(page_number=0, x=72, y=730) \
         .add()
 
     pdf.new_image() \

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/README.md

@@ -12,7 +12,7 @@ pixel-perfect control from Python. The same API is also available for TypeScript
 
 ## Highlights
 
-- Locate paragraphs, text lines, images, vector paths, form fields, and pages by index, coordinates, or text prefixes.
+- Locate paragraphs, text lines, images, vector paths, form fields, and pages by page number, coordinates, or text prefixes.
 - Edit existing content in place with fluent editors and context managers that apply changes safely.
 - Programmatically control third-party PDFs—modify invoices, contracts, and reports you did not author.
 - Add content with precise XY positioning using paragraph and image builders, custom fonts, and color helpers.
@@ -61,7 +61,7 @@ with PDFDancer.open(
         .font(StandardFonts.HELVETICA, 12) \
         .color(Color(70, 70, 70)) \
         .line_spacing(1.4) \
-        .at(page_index=0, x=72, y=520) \
+        .at(page_number=0, x=72, y=520) \
         .add()
 
     # Persist the modified document
@@ -82,7 +82,7 @@ with PDFDancer.new(token="your-api-token") as pdf:
         .font(StandardFonts.TIMES_BOLD, 18) \
         .color(Color(10, 10, 80)) \
         .line_spacing(1.2) \
-        .at(page_index=0, x=72, y=730) \
+        .at(page_number=0, x=72, y=730) \
         .add()
 
     pdf.new_image() \

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pdfdancer-client-python"
-version = "0.2.28"
+version = "0.3.1"
 description = "Python client for PDFDancer API"
 readme = "README.md"
 authors = [

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/src/pdfdancer/image_builder.py

@@ -39,7 +39,7 @@ class ImageBuilder:
 
 class ImageOnPageBuilder:
 
-    def __init__(self, client: "PDFDancer", page_index: int):
+    def __init__(self, client: "PDFDancer", page_number: int):
         """
         Initialize the image builder with a client reference.
 
@@ -51,14 +51,14 @@ class ImageOnPageBuilder:
 
         self._client = client
         self._image = Image()
-        self._page_index = page_index
+        self._page_number = page_number
 
     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)
+        self._image.position = Position.at_page_coordinates(self._page_number, x, y)
         return self
 
     def add(self) -> bool:

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/src/pdfdancer/models.py

@@ -262,7 +262,7 @@ class Position:
     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
+    - page_number: One-based page number 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`).
@@ -272,8 +272,8 @@ class Position:
     - 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.at_page(page_number)` – target a whole page.
+    - `Position.at_page_coordinates(page_number, 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.
@@ -294,7 +294,7 @@ class Position:
     ```
     """
 
-    page_index: Optional[int] = None
+    page_number: Optional[int] = None
     shape: Optional[ShapeType] = None
     mode: Optional[PositionMode] = None
     bounding_rect: Optional[BoundingRect] = None
@@ -303,18 +303,18 @@ class Position:
     name: Optional[str] = None
 
     @staticmethod
-    def at_page(page_index: int) -> "Position":
+    def at_page(page_number: int) -> "Position":
         """
         Creates a position specification for an entire page.
         """
-        return Position(page_index=page_index, mode=PositionMode.CONTAINS)
+        return Position(page_number=page_number, mode=PositionMode.CONTAINS)
 
     @staticmethod
-    def at_page_coordinates(page_index: int, x: float, y: float) -> "Position":
+    def at_page_coordinates(page_number: int, x: float, y: float) -> "Position":
         """
         Creates a position specification for specific coordinates on a page.
         """
-        position = Position.at_page(page_index)
+        position = Position.at_page(page_number)
         position.at_coordinates(Point(x, y))
         return position
 
@@ -823,7 +823,7 @@ class FindRequest:
     def _position_to_dict(position: Position) -> dict:
         """Convert Position to dictionary for JSON serialization."""
         result = {
-            "pageIndex": position.page_index,
+            "pageNumber": position.page_number,
             "textStartsWith": position.text_starts_with,
             "textPattern": position.text_pattern,
         }
@@ -898,24 +898,24 @@ class PageMoveRequest:
     """Request to reorder pages.
 
     Parameters:
-    - from_page_index: Zero-based index of the page to move.
-    - to_page_index: Zero-based destination index.
+    - from_page: 1-based page number of the page to move.
+    - to_page: 1-based destination page number.
 
     Example:
     ```python
     # Move first page to the end
-    req = PageMoveRequest(from_page_index=0, to_page_index=doc_page_count - 1)
+    req = PageMoveRequest(from_page=1, to_page=doc_page_count)
     payload = req.to_dict()
     ```
     """
 
-    from_page_index: int
-    to_page_index: int
+    from_page: int
+    to_page: int
 
     def to_dict(self) -> dict:
         return {
-            "fromPageIndex": self.from_page_index,
-            "toPageIndex": self.to_page_index,
+            "fromPage": self.from_page,
+            "toPage": self.to_page,
         }
 
 
@@ -924,7 +924,7 @@ 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.
+    - page_number: Optional 1-based page number where the new page should be inserted.
     - orientation: Optional page orientation (portrait or landscape).
     - page_size: Optional size of the page.
 
@@ -932,14 +932,14 @@ class AddPageRequest:
     with default server behavior.
     """
 
-    page_index: Optional[int] = None
+    page_number: 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.page_number is not None:
+            payload["pageNumber"] = int(self.page_number)
         if self.orientation is not None:
             orientation_value: Orientation
             if isinstance(self.orientation, Orientation):
@@ -1449,14 +1449,14 @@ class PageRef(ObjectRef):
 
     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)`).
+    - position: Position referencing the page (often via `Position.at_page(page_number)`).
     - 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.
+      and use the page number for subsequent operations.
     """
 
     page_size: Optional[PageSize]
@@ -1531,7 +1531,7 @@ class PageSnapshot:
 
     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.
+    - Use `page_ref.position.page_number` as the page number for follow-up operations.
     """
 
     page_ref: PageRef

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/src/pdfdancer/page_builder.py

@@ -11,10 +11,10 @@ if TYPE_CHECKING:
 
 class PageBuilder:
     """
-    Fluent builder for adding pages with optional orientation, size, and index.
+    Fluent builder for adding pages with optional orientation, size, and page number.
 
     Usage:
-        pdf.new_page().at_index(1).landscape().a4().add()
+        pdf.new_page().at_page(1).landscape().a4().add()
     """
 
     def __init__(self, client: "PDFDancer") -> None:
@@ -22,18 +22,44 @@ class PageBuilder:
             raise ValidationException("Client cannot be null")
 
         self._client = client
-        self._page_index: Optional[int] = None
+        self._page_number: 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)
+    def at_page(self, page_number: int) -> "PageBuilder":
+        """
+        Sets the page number where the new page should be inserted (1-based).
+        Page 1 is the first page.
+
+        Args:
+            page_number: The 1-based page number (must be >= 1)
+
+        Returns:
+            This builder
+
+        Raises:
+            ValidationException: If page_number is None or less than 1
+        """
+        if page_number is None:
+            raise ValidationException("Page number cannot be null")
+        if page_number < 1:
+            raise ValidationException("Page number must be >= 1 (1-based indexing)")
+        self._page_number = int(page_number)
         return self
 
+    def at_index(self, page_number: int) -> "PageBuilder":
+        """
+        Deprecated: Use at_page() instead. This method will be removed in a future release.
+        """
+        import warnings
+
+        warnings.warn(
+            "at_index() is deprecated, use at_page() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.at_page(page_number + 1)
+
     def orientation(self, orientation: Orientation) -> "PageBuilder":
         if orientation is None:
             raise ValidationException("Orientation cannot be null")
@@ -87,13 +113,13 @@ class PageBuilder:
 
     def _build_request(self) -> Optional[AddPageRequest]:
         if (
-            self._page_index is None
+            self._page_number is None
             and self._orientation is None
             and self._page_size is None
         ):
             return None
         return AddPageRequest(
-            page_index=self._page_index,
+            page_number=self._page_number,
             orientation=self._orientation,
             page_size=self._page_size,
         )

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/src/pdfdancer/paragraph_builder.py

@@ -169,14 +169,14 @@ class ParagraphBuilder:
                 "Cannot move paragraph without an existing position"
             )
 
-        page_index = position.page_index
-        if page_index is None:
+        page_number = position.page_number
+        if page_number is None:
             raise ValidationException(
-                "Paragraph position must include a page index to move"
+                "Paragraph position must include a page number to move"
             )
 
         self._position_changed = True
-        return self.at(page_index, x, y)
+        return self.at(page_number, x, y)
 
     def at_position(self, position: Position) -> "ParagraphBuilder":
         if position is None:
@@ -186,8 +186,8 @@ class ParagraphBuilder:
         self._position_changed = True
         return self
 
-    def at(self, page_index: int, x: float, y: float) -> "ParagraphBuilder":
-        return self.at_position(Position.at_page_coordinates(page_index, x, y))
+    def at(self, page_number: int, x: float, y: float) -> "ParagraphBuilder":
+        return self.at_position(Position.at_page_coordinates(page_number, x, y))
 
     def add_text_line(
         self, text_line: Union[TextLine, TextObjectRef, str]
@@ -470,14 +470,14 @@ class ParagraphBuilder:
         if paragraph_position is None:
             return None
 
-        page_index = paragraph_position.page_index
+        page_number = paragraph_position.page_number
         base_x = paragraph_position.x()
         base_y = paragraph_position.y()
-        if page_index is None or base_x is None or base_y is None:
+        if page_number is None or base_x is None or base_y is None:
             return None
 
         offset = line_index * self._calculate_baseline_distance(spacing_factor)
-        return Position.at_page_coordinates(page_index, base_x, base_y + offset)
+        return Position.at_page_coordinates(page_number, base_x, base_y + offset)
 
     def _calculate_baseline_distance(self, spacing_factor: float) -> float:
         factor = spacing_factor if spacing_factor > 0 else DEFAULT_LINE_SPACING_FACTOR
@@ -545,10 +545,10 @@ class ParagraphBuilder:
 
 class ParagraphPageBuilder(ParagraphBuilder):
 
-    def __init__(self, client: "PDFDancer", page_index: int):
+    def __init__(self, client: "PDFDancer", page_number: int):
         super().__init__(client)
-        self._page_index: Optional[int] = page_index
+        self._page_number: Optional[int] = page_number
 
     # noinspection PyMethodOverriding
     def at(self, x: float, y: float) -> "ParagraphBuilder":
-        return super().at(self._page_index, x, y)
+        return super().at(self._page_number, x, y)

{pdfdancer_client_python-0.2.28 → pdfdancer_client_python-0.3.1}/src/pdfdancer/path_builder.py

@@ -21,19 +21,19 @@ class PathBuilder:
     All coordinates are absolute page coordinates.
     """
 
-    def __init__(self, client: "PDFDancer", page_index: int):
+    def __init__(self, client: "PDFDancer", page_number: int):
         """
-        Initialize the path builder with a client reference and page index.
+        Initialize the path builder with a client reference and page number.
 
         Args:
             client: The PDFDancer instance for adding the path
-            page_index: The page number (0-indexed)
+            page_number: The page number (1-indexed)
         """
         if client is None:
             raise ValidationException("Client cannot be null")
 
         self._client = client
-        self._page_index = page_index
+        self._page_number = page_number
         self._segments: List[PathSegment] = []
         self._even_odd_fill: bool = False
         self._current_stroke_color: Optional[Color] = Color(0, 0, 0)  # Black default
@@ -222,7 +222,7 @@ class PathBuilder:
             raise ValidationException("Path must have at least one segment")
 
         # Create position with only page index set
-        position = Position.at_page_coordinates(self._page_index, 0, 0)
+        position = Position.at_page_coordinates(self._page_number, 0, 0)
 
         # Build the Path object
         path = Path(
@@ -242,19 +242,19 @@ class LineBuilder:
     Mirrors the Java client LineBuilder API.
     """
 
-    def __init__(self, client: "PDFDancer", page_index: int):
+    def __init__(self, client: "PDFDancer", page_number: int):
         """
         Initialize the line builder.
 
         Args:
             client: The PDFDancer instance for adding the line
-            page_index: The page number (0-indexed)
+            page_number: The page number (1-indexed)
         """
         if client is None:
             raise ValidationException("Client cannot be null")
 
         self._client = client
-        self._page_index = page_index
+        self._page_number = page_number
         self._p0: Optional[Point] = None
         self._p1: Optional[Point] = None
         self._stroke_color: Optional[Color] = Color(0, 0, 0)  # Black default
@@ -387,7 +387,7 @@ class LineBuilder:
         )
 
         # Create position with only page index set
-        position = Position.at_page_coordinates(self._page_index, 0, 0)
+        position = Position.at_page_coordinates(self._page_number, 0, 0)
 
         # Wrap in Path with single segment
         path = Path(position=position, path_segments=[line], even_odd_fill=False)
@@ -403,19 +403,19 @@ class BezierBuilder:
     Mirrors the Java client BezierBuilder API.
     """
 
-    def __init__(self, client: "PDFDancer", page_index: int):
+    def __init__(self, client: "PDFDancer", page_number: int):
         """
         Initialize the bezier builder.
 
         Args:
             client: The PDFDancer instance for adding the bezier
-            page_index: The page number (0-indexed)
+            page_number: The page number (1-indexed)
         """
         if client is None:
             raise ValidationException("Client cannot be null")
 
         self._client = client
-        self._page_index = page_index
+        self._page_number = page_number
         self._p0: Optional[Point] = None
         self._p1: Optional[Point] = None
         self._p2: Optional[Point] = None
@@ -590,7 +590,7 @@ class BezierBuilder:
         )
 
         # Create position with only page index set
-        position = Position.at_page_coordinates(self._page_index, 0, 0)
+        position = Position.at_page_coordinates(self._page_number, 0, 0)
 
         # Wrap in Path with single segment
         path = Path(position=position, path_segments=[bezier], even_odd_fill=False)
@@ -606,19 +606,19 @@ class RectangleBuilder:
     Provides a convenient way to create a rectangle path with a single builder.
     """
 
-    def __init__(self, client: "PDFDancer", page_index: int):
+    def __init__(self, client: "PDFDancer", page_number: int):
         """
         Initialize the rectangle builder.
 
         Args:
             client: The PDFDancer instance for adding the rectangle
-            page_index: The page number (0-indexed)
+            page_number: The page number (1-indexed)
         """
         if client is None:
             raise ValidationException("Client cannot be null")
 
         self._client = client
-        self._page_index = page_index
+        self._page_number = page_number
         self._x: Optional[float] = None
         self._y: Optional[float] = None
         self._width: Optional[float] = None
@@ -812,7 +812,7 @@ class RectangleBuilder:
         ]
 
         # Create position with only page index set
-        position = Position.at_page_coordinates(self._page_index, 0, 0)
+        position = Position.at_page_coordinates(self._page_number, 0, 0)
 
         # Wrap in Path with four line segments
         path = Path(