pdfdancer-client-python 0.1.1__tar.gz

pdfdancer_client_python-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+output.pdf
+.idea
+comprehensive_output.pdf
+jwt-token-mlahr-20250829-160417.txt
+dist/
+src/pdfdancer_python.egg-info
+.aider*

pdfdancer_client_python-0.1.1/CLAUDE.md

@@ -0,0 +1,121 @@
+# 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 (77 tests)
+- `venv/bin/python -m pytest tests/test_client_v1.py -v` - Run client tests
+- `venv/bin/python -m pytest tests/test_paragraph_builder.py -v` - Run builder 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
+# Java-like API with Python conventions
+client = ClientV1(token="jwt-token", pdf_data="document.pdf")
+
+# Find operations (mirrors Java findParagraphs, findImages, etc.)
+paragraphs = client.find_paragraphs(position)
+images = client.find_images(position)
+
+# Manipulation operations (mirrors Java delete, move, etc.)
+client.delete(paragraphs[0])
+client.move(images[0], new_position)
+
+# Builder pattern (mirrors Java ParagraphBuilder)
+paragraph = (client.paragraph_builder()
+    .from_string("Text content")
+    .with_font(Font("Arial", 12))
+    .with_position(Position.on_page_coordinates(0, 100, 200))
+    .build())
+
+# Context manager support (Python enhancement)
+with ClientV1(token="jwt-token", pdf_data=pdf_file) as client:
+    client.save_pdf("output.pdf")
+```
+
+### Package Structure
+- `src/pdfdancer/` - Main package
+  - `client_v1.py` - Main ClientV1 class (mirrors Java Client class)
+  - `paragraph_builder.py` - ParagraphBuilder for fluent construction
+  - `models.py` - All model classes (ObjectRef, Position, Font, etc.)
+  - `exceptions.py` - Exception hierarchy matching Java client
+
+### Key Features
+- **Session-based operations**: Constructor creates session automatically
+- **Strict validation**: All validation matches Java client exactly
+- **Builder pattern**: ParagraphBuilder with fluent interface
+- **Exception handling**: FontNotFoundException, ValidationException, etc.
+- **Type safety**: Full type hints throughout
+- **Context manager**: Python enhancement for resource management
+
+## Java Client Mapping
+
+### Constructor Patterns
+```python
+# Java: new Client(token, pdfFile)
+client = ClientV1(token="jwt-token", pdf_data="document.pdf")
+
+# Java: new Client(token, bytesPDF, httpClient)
+client = ClientV1(token="jwt-token", pdf_data=pdf_bytes, base_url="http://api.server")
+```
+
+### Method Mapping
+- `find()` → `find()`
+- `findParagraphs()` → `find_paragraphs()`
+- `findImages()` → `find_images()`
+- `delete()` → `delete()`
+- `move()` → `move()`
+- `addParagraph()` → `add_paragraph()`
+- `getPDFFile()` → `get_pdf_file()`
+- `savePDF()` → `save_pdf()`
+- `paragraphBuilder()` → `paragraph_builder()`
+
+### Validation Matching
+All validation matches Java client exactly:
+- Null checks become None checks
+- IllegalArgumentException becomes ValidationException
+- FontNotFoundException preserved exactly
+- Page number validation (must be positive)
+- File existence and readability checks
+
+## Development Notes
+
+- **Python 3.8+ compatibility**
+- **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** - 77 tests covering all functionality
+
+## Important Instructions
+
+- **ALWAYS mirror Java client behavior exactly** - same validation, same patterns
+- **Use snake_case for method names** but preserve Java logic
+- **Maintain strict validation** - don't be more lenient than Java client
+- **Follow existing test patterns** when adding new functionality
+- **Keep exception hierarchy matching Java client**
+- **Preserve builder pattern fluent interface**

pdfdancer_client_python-0.1.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: pdfdancer-client-python
+Version: 0.1.1
+Summary: Python client for PDFDancer API
+Author-email: TFC <info@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/tfc/pdfdancer-python
+Project-URL: Repository, https://github.com/tfc/pdfdancer-python.git
+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
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pydantic>=1.8.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=22.0; extra == "dev"
+Requires-Dist: flake8>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+
+# PDFDancer Python Client
+
+A Python client library for the PDFDancer PDF manipulation API that closely mirrors the Java client structure and functionality.
+
+## Features
+
+- **100% Manual Implementation** - Pure Python, no code generation
+- **Java Client Compatibility** - Same methods, validation, and patterns
+- **Session-based Operations** - Automatic session management
+- **Builder Pattern** - Fluent ParagraphBuilder interface
+- **Strict Validation** - Matches Java client validation exactly
+- **Python Enhancements** - Type hints, context managers, Pathlib support
+- **Comprehensive Testing** - 77 tests covering all functionality
+
+## Installation
+
+```bash
+pip install pdfdancer-client-python
+# Or for development:
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from pdfdancer import ClientV1, Position, Font, Color
+
+# Create client (mirrors Java: new Client(token, pdfFile))
+client = ClientV1(token="your-jwt-token", pdf_data="document.pdf")
+
+# Find operations (mirrors Java client methods)
+paragraphs = client.find_paragraphs(None)
+images = client.find_images(Position.from_page_index(0))
+
+# Manipulation operations (mirrors Java client methods)
+client.delete(paragraphs[0])
+client.move(images[0], Position.on_page_coordinates(0, 100, 200))
+
+# Builder pattern (mirrors Java ParagraphBuilder)
+paragraph = (client.paragraph_builder()
+             .from_string("Hello World")
+             .with_font(Font("Arial", 12))
+             .with_color(Color(255, 0, 0))
+             .with_position(Position.from_page_index(0))
+             .build())
+
+client.add_paragraph(paragraph)
+
+# Save result (mirrors Java savePDF)
+client.save_pdf("output.pdf")
+```
+
+## Context Manager (Python Enhancement)
+
+```python
+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.save_pdf("output.pdf")
+    # Session automatically cleaned up
+```
+
+## API Methods
+
+### Constructor Patterns
+```python
+# File path (Java: new Client(token, new File("pdf")))
+client = ClientV1(token="jwt-token", pdf_data="document.pdf")
+
+# Bytes (Java: new Client(token, pdfBytes, httpClient))
+client = ClientV1(token="jwt-token", pdf_data=pdf_bytes)
+
+# Custom server
+client = ClientV1(token="jwt-token", pdf_data=pdf_file, base_url="https://api.server")
+```
+
+### Find Operations
+```python
+# Generic find (Java: client.find())
+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)
+
+# Page operations (Java: client.getPages(), client.getPage())
+pages = client.get_pages()
+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)
+
+# Move (Java: client.move())
+result = client.move(object_ref, new_position)
+
+# Add (Java: client.addImage(), client.addParagraph())
+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_text_line(ref, "new text")
+```
+
+### Builder Pattern
+```python
+# Java: client.paragraphBuilder()
+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()
+
+# 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())
+```
+
+### Position API
+
+```python
+from pdfdancer import Position
+
+# Factory methods (Java: Position.fromPageNumber(), Position.onPageCoordinates())
+position = Position.from_page_index(0)
+position = Position.on_page_coordinates(0, 100, 200)
+
+# Coordinate access (Java: position.getX(), position.getY())
+x = position.get_x()
+y = position.get_y()
+
+# Movement (Java: position.moveX(), position.moveY())
+position.move_x(50.0)
+position.move_y(-25.0)
+
+# Copy (Java: position.copy())
+position_copy = position.copy()
+```
+
+### Font Operations
+```python
+# Find fonts (Java: client.findFonts())
+fonts = client.find_fonts("Arial", 12)
+
+# Register custom font (Java: client.registerFont())
+font_name = client.register_font("custom.ttf")
+font_name = client.register_font(Path("font.ttf"))
+font_name = client.register_font(font_bytes)
+```
+
+### Document Operations
+```python
+# Get PDF content (Java: client.getPDFFile())
+pdf_bytes = client.get_pdf_file()
+
+# Save PDF (Java: client.savePDF())
+client.save_pdf("output.pdf")
+client.save_pdf(Path("output.pdf"))
+```
+
+## Exception Handling
+
+```python
+from pdfdancer import (
+    PdfDancerException, ValidationException,
+    FontNotFoundException, HttpClientException
+)
+
+try:
+    client = ClientV1(token="", pdf_data=b"pdf")
+except ValidationException as e:  # Java: IllegalArgumentException
+    print(f"Validation error: {e}")
+
+try:
+    fonts = client.find_fonts("NonExistentFont", 12)
+except FontNotFoundException as e:  # Java: FontNotFoundException
+    print(f"Font not found: {e}")
+```
+
+## Data Models
+
+```python
+from pdfdancer import ObjectRef, Position, Font, Color, ObjectType
+
+# Object reference (Java: ObjectRef)
+obj_ref = ObjectRef(internal_id="obj-123", position=position, type=ObjectType.PARAGRAPH)
+
+# Font (Java: Font)
+font = Font(name="Arial", size=12.0)
+
+# Color (Java: Color) - RGB values 0-255
+color = Color(r=255, g=128, b=0)
+
+# Position with bounding rectangle (Java: Position, BoundingRect)
+position = Position.on_page_coordinates(page=0, x=100.0, y=200.0)
+```
+
+## Development
+
+### Setup
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e .
+pip install -r requirements-dev.txt
+```
+
+### Testing
+```bash
+# Run all tests (77 tests)
+python -m pytest tests/ -v
+
+# Run specific test files
+python -m pytest tests/test_client_v1.py -v
+python -m pytest tests/test_paragraph_builder.py -v
+python -m pytest tests/test_models.py -v
+```
+
+### Run Demo
+```bash
+python demo.py
+```
+
+### Build Package
+```bash
+python -m build
+python -m twine check dist/*
+```
+
+## Java Client Mapping
+
+| Java Method | Python Method | Description |
+|-------------|---------------|-------------|
+| `new Client(token, file)` | `ClientV1(token="", pdf_data="")` | Constructor |
+| `findParagraphs(position)` | `find_paragraphs(position)` | Find paragraphs |
+| `findImages(position)` | `find_images(position)` | Find images |
+| `delete(objectRef)` | `delete(object_ref)` | Delete object |
+| `move(objectRef, position)` | `move(object_ref, position)` | Move object |
+| `addParagraph(paragraph)` | `add_paragraph(paragraph)` | Add paragraph |
+| `getPDFFile()` | `get_pdf_file()` | Get PDF bytes |
+| `savePDF(path)` | `save_pdf(path)` | Save to file |
+| `paragraphBuilder()` | `paragraph_builder()` | Create builder |
+| `findFonts(name, size)` | `find_fonts(name, size)` | Find fonts |
+| `registerFont(ttfFile)` | `register_font(ttf_file)` | Register font |
+
+## Architecture
+
+- **Pure Manual Implementation** - No code generation, uses `requests` for HTTP
+- **Session-based** - Constructor creates session, all operations use session ID
+- **Strict Validation** - Matches Java client validation exactly
+- **Type Safety** - Full type hints throughout
+- **Error Handling** - Complete exception hierarchy
+- **Python Conventions** - snake_case methods, context managers, Pathlib support
+
+## Requirements
+
+- Python 3.8+
+- `requests` library for HTTP communication
+- `pathlib` for file handling (built-in)
+
+## License
+
+[Add your license information here]