pdfdancer-client-python 0.2.12__tar.gz → 0.2.13__tar.gz

pdfdancer_client_python-0.2.13/.claude/commands/discuss.md

@@ -0,0 +1,4 @@
+We discuss this: $ARGUMENTS.
+You ask everything you need to know to completely understand what I want to know.
+We discuss options, pros and cons and side effects.
+You dont start to code until you have my approval.

pdfdancer_client_python-0.2.13/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, staging, develop, development, dev ]
+  pull_request:
+    branches: [ main, staging, develop, development, dev ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.10', '3.11', '3.12', '3.13' ]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Create virtual environment
+        run: python -m venv venv
+
+      - name: Install dependencies
+        run: |
+          venv/bin/pip install --upgrade pip
+          venv/bin/pip install -e .
+          venv/bin/pip install -r requirements-dev.txt
+
+      - name: Run tests
+        run: PDFDANCER_BASE_URL=https://api.staging.pdfdancer.com venv/bin/python -m pytest tests/ -v --ignore=tests/e2e/
+
+      - name: Build distribution packages
+        run: venv/bin/python -m build
+
+      - name: Validate packages
+        run: venv/bin/python -m twine check dist/*

{pdfdancer_client_python-0.2.12 → pdfdancer_client_python-0.2.13}/.gitignore

@@ -7,3 +7,4 @@ src/pdfdancer_python.egg-info
 .aider*
 src/pdfdancer_client_python.egg-info
 /logs/
+/venv

pdfdancer_client_python-0.2.13/CLAUDE.md

@@ -0,0 +1,206 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with the PDFDancer Python client.
+
+## Project Overview
+
+This is a **Python client library** for the PDFDancer PDF manipulation API. It uses a **100% manual implementation**
+that:
+
+- **Mirrors Java client structure exactly** - Same methods, validation, and patterns
+- **Pure Python implementation** - Uses `requests` for HTTP calls, no code generation
+- **Pythonic conventions** - Snake_case methods, type hints, context managers
+- **Strict validation** - Matches Java client validation exactly
+
+## Essential Commands
+
+### Development
+
+- `python -m venv venv` - Create virtual environment
+- `venv/bin/pip install -e .` - Install in development mode
+- `venv/bin/pip install -r requirements-dev.txt` - Install dev dependencies
+
+### Testing
+
+- `venv/bin/python -m pytest tests/ -v` - Run all tests (123 tests)
+- `venv/bin/python -m pytest tests/e2e/ -v` - Run end-to-end tests
+- `venv/bin/python -m pytest tests/test_models.py -v` - Run model tests
+
+### Building & Publishing
+
+- `venv/bin/python -m build` - Build distribution packages
+- `venv/bin/python -m twine check dist/*` - Validate packages
+- `venv/bin/python -m twine upload dist/*` - Publish to PyPI
+
+## Architecture
+
+### Manual Implementation
+
+The client is a pure manual implementation that closely mirrors the Java client:
+
+```python
+# Open existing PDF
+pdf = PDFDancer.open(pdf_data="document.pdf")
+
+# Create new blank PDF
+pdf = PDFDancer.new(page_size=PageSize.A4, orientation=Orientation.PORTRAIT)
+
+# Select and manipulate objects
+paragraphs = pdf.select_paragraphs()
+paragraphs[0].delete()
+
+images = pdf.select_images()
+images[0].move(Position.at_page_coordinates(0, 100, 200))
+
+# Page-level operations
+page = pdf.page(0)
+page_paragraphs = page.select_paragraphs()
+page.delete()
+
+# Builder pattern for new content
+pdf.new_paragraph()
+    .from_string("Text content")
+    .with_font(Font("Arial", 12))
+    .at_page_coordinates(0, 100, 200)
+    .add()
+
+# Save modified PDF
+pdf.save("output.pdf")
+```
+
+### Package Structure
+
+- `src/pdfdancer/` - Main package
+    - `pdfdancer_v1.py` - Main PDFDancer class and PageClient
+    - `paragraph_builder.py` - ParagraphBuilder and ParagraphPageBuilder for fluent construction
+    - `image_builder.py` - ImageBuilder for fluent image construction
+    - `models.py` - Model classes (ObjectRef, Position, Font, Color, etc.)
+    - `types.py` - Object wrapper types (ParagraphObject, ImageObject, etc.)
+    - `exceptions.py` - Exception hierarchy
+
+### Key Features
+
+- **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
+- **Builder pattern**: `new_paragraph()` and `new_image()` for fluent construction
+- **Strict validation**: All validation matches Java client exactly
+- **Exception handling**: FontNotFoundException, ValidationException, HttpClientException, etc.
+- **Type safety**: Full type hints throughout
+- **E2E testing utilities**: PDFAssertions for comprehensive PDF validation
+
+## API Patterns
+
+### Initialization
+
+```python
+# Open existing PDF with token from env var PDFDANCER_TOKEN
+pdf = PDFDancer.open(pdf_data="document.pdf")
+
+# Open with explicit token
+pdf = PDFDancer.open(pdf_data="document.pdf", token="your-token")
+
+# Create new blank PDF
+pdf = PDFDancer.new(
+    page_size=PageSize.A4,
+    orientation=Orientation.PORTRAIT,
+    initial_page_count=5
+)
+```
+
+### Selection and Manipulation
+
+```python
+# Document-level selections
+paragraphs = pdf.select_paragraphs()
+images = pdf.select_images()
+form_fields = pdf.select_form_fields_by_name("fieldName")
+
+# Page-level selections
+page = pdf.page(0)
+page_paragraphs = page.select_paragraphs_starting_with("Invoice")
+page_images = page.select_images_at(100, 200)
+
+# Object manipulation
+paragraphs[0].delete()
+paragraphs[0].move(Position.at_page_coordinates(1, 50, 50))
+paragraphs[0].modify("New text content")
+
+# Pattern-based selections
+paragraphs = page.select_paragraphs_matching(r"\d{4}-\d{2}-\d{2}")
+text_lines = page.select_text_lines_matching(r"Total: \$\d+")
+```
+
+### Building New Content
+
+```python
+# Add paragraph to document
+pdf.new_paragraph()
+    .from_string("Hello World")
+    .with_font(Font("Helvetica", 12))
+    .with_color(Color(255, 0, 0))
+    .at_page_coordinates(0, 100, 200)
+    .add()
+
+# Add paragraph to specific page
+page.new_paragraph()
+    .from_string("Page-specific text")
+    .with_font(Font("Arial", 14))
+    .at_coordinates(50, 50)
+    .add()
+
+# Add image
+pdf.new_image()
+    .from_file("logo.png")
+    .with_width(100)
+    .at_page_coordinates(0, 50, 50)
+    .add()
+```
+
+### Document Operations
+
+```python
+# Get PDF bytes
+pdf_bytes = pdf.get_bytes()
+
+# Save to file
+pdf.save("output.pdf")
+
+# Page operations
+pages = pdf.pages()
+page = pdf.page(0)
+page.delete()
+```
+
+## Development Notes
+
+- **Python 3.10+ compatibility** (Python 3.9 has SSL issues with large file uploads)
+- **Uses `requests` library** for all HTTP communication
+- **No code generation** - pure manual implementation
+- **Virtual environment auto-setup** via parent Makefile
+- **No code formatter configured** - follow existing style
+- **Comprehensive tests** - 123 tests covering all functionality
+- **E2E test utilities** - `tests/e2e/pdf_assertions.py` provides PDFAssertions class
+
+## Important Instructions
+
+### 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
+- **Support fluent builders**: `new_paragraph()` and `new_image()` return builder instances
+- **Use snake_case for methods**: `select_paragraphs()`, `select_images_at()`, etc.
+
+### Validation and Exceptions
+
+- **Maintain strict validation**: Don't be more lenient than Java client
+- **Preserve exception hierarchy**: ValidationException, FontNotFoundException, HttpClientException, etc.
+- **Validate early**: Check parameters in Python before making API calls
+
+### Testing
+
+- **Follow e2e test patterns**: Use PDFAssertions for comprehensive validation
+- **Test both document and page operations**: Cover both `pdf.select_*()` and `page.select_*()` patterns
+- **Test builder patterns**: Verify fluent interfaces work correctly
+- **Always run tests after changes**: `venv/bin/python -m pytest tests/ -v`

{pdfdancer_client_python-0.2.12/src/pdfdancer_client_python.egg-info → pdfdancer_client_python-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.2.12
+Version: 0.2.13
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: MIT
@@ -9,10 +9,11 @@ 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
@@ -26,11 +27,16 @@ Requires-Dist: mypy>=1.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 +53,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 +73,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 +113,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 +123,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 +148,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()
 ```
 

{pdfdancer_client_python-0.2.12 → pdfdancer_client_python-0.2.13}/README.md

@@ -1,10 +1,15 @@
 # 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
@@ -21,7 +26,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`)
 
@@ -41,21 +46,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
@@ -81,7 +86,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
 
@@ -90,11 +96,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
@@ -115,16 +121,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()
 ```
 

{pdfdancer_client_python-0.2.12 → pdfdancer_client_python-0.2.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pdfdancer-client-python"
-version = "0.2.12"
+version = "0.2.13"
 description = "Python client for PDFDancer API"
 readme = "README.md"
 authors = [
@@ -15,11 +15,12 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]
+requires-python = ">=3.10"
 dependencies = [
     "requests>=2.25.0",
     "pydantic>=1.8.0",
@@ -44,8 +45,8 @@ where = ["src"]
 
 [tool.black]
 line-length = 88
-target-version = ['py39']
+target-version = ['py310']
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.10"
 strict = true

{pdfdancer_client_python-0.2.12 → pdfdancer_client_python-0.2.13}/src/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",