pdfdancer-client-python 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

pdfdancer_client_python-0.2.6.dist-info/METADATA

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: pdfdancer-client-python
+Version: 0.2.6
+Summary: Python client for PDFDancer API
+Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
+License: MIT
+Project-URL: Homepage, https://www.pdfdancer.com/
+Project-URL: Repository, https://github.com/MenschMachine/pdfdancer-client-python
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: pydantic>=1.8.0
+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
+
+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.
+
+## Highlights
+
+- 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
+- Download results as bytes for downstream processing or save directly to disk with one method call
+
+## Core Capabilities
+
+- Clean up layout by moving or deleting paragraphs, text lines, or shapes on specific pages
+- Search and filter content (e.g., paragraphs starting with "Invoice") to drive custom workflows
+- Redact or replace text in bulk with chained editor operations
+- Populate AcroForms for contract generation or onboarding flows
+- Insert logos, signatures, and generated paragraphs at deterministic coordinates
+- Export modified PDFs as bytes for APIs, S3 uploads, or direct file saves
+
+## Requirements
+
+- Python 3.9 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`)
+
+## Installation
+
+```bash
+pip install pdfdancer-client-python
+
+# Editable install for local development
+pip install -e .
+```
+
+## Getting Started
+
+```python
+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",
+) 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) \
+        .add()
+
+    # Persist the modified document
+    pdf.save("output.pdf")
+```
+
+### Authentication Tips
+
+- Prefer setting `PDFDANCER_TOKEN` in your environment for local development.
+- Override the API host by setting `PDFDANCER_BASE_URL` or passing `base_url="https://sandbox.pdfdancer.com"`.
+- Use the `timeout` parameter on `PDFDancer.open()` to adjust HTTP read timeouts.
+
+## Selecting PDF Content
+
+```python
+with PDFDancer.open("report.pdf") as pdf:  # environment variables provide token/URL
+    all_paragraphs = pdf.select_paragraphs()
+    page_zero_images = pdf.page(0).select_images()
+    form_fields = pdf.page(2).select_form_fields()
+    paths_at_cursor = pdf.page(3).select_paths_at(x=150, y=320)
+
+    page = pdf.page(0).get()
+    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.
+
+## Editing Text and Forms
+
+```python
+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) \
+        .apply()
+
+    # …or use the context manager to auto-apply on success
+    with paragraph.edit() as edit:
+        edit.replace("Context-managed update").color(Color(120, 0, 0))
+
+    # Update an AcroForm field
+    field = pdf.page(1).select_form_fields_by_name("signature")[0]
+    field.edit().value("Signed by Jane Doe").apply()
+```
+
+## Adding New Content
+
+```python
+with PDFDancer.open("report.pdf") as pdf:
+    # Register fonts from the service
+    fonts = pdf.find_fonts("Roboto", 12)
+    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) \
+        .add()
+
+    # Raster images
+    pdf.new_image() \
+        .from_file(Path("logo.png")) \
+        .at(page=0, x=48, y=700) \
+        .add()
+```
+
+## Downloading Results
+
+- `pdf.get_pdf_file()` returns the modified PDF as `bytes` (ideal for storage services or HTTP responses).
+- `pdf.save("output.pdf")` writes directly to disk, creating directories when needed.
+
+## Error Handling
+
+Most operations raise subclasses of `PdfDancerException`:
+
+- `ValidationException` for client-side validation issues (missing token, invalid coordinates, etc.).
+- `FontNotFoundException` when the service cannot locate a requested font.
+- `HttpClientException` for transport or server errors with detailed messages.
+- `SessionException` when session creation fails.
+
+Wrap complex workflows in `try/except` blocks to surface actionable errors to your users.
+
+## Local Development
+
+```bash
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -e .
+pip install -r requirements-dev.txt
+
+pytest -q          # run the fast unit suite
+pytest tests/e2e   # integration tests (requires live API + fixtures)
+```
+
+Package builds are handled by `python -m build`, and release artifacts are published via `python release.py`.
+
+## License
+
+MIT © The Famous Cat Ltd.

{pdfdancer_client_python-0.2.5.dist-info → pdfdancer_client_python-0.2.6.dist-info}/RECORD

@@ -5,7 +5,7 @@ pdfdancer/models.py,sha256=SmkKScr47uVs6FCWUAVIg6rucYrYHvbIxZngyA50XyI,15498
 pdfdancer/paragraph_builder.py,sha256=bAfwX9U2YT1UGX9EKkPnGYvGK3SQP3X1ocxlgyLE_rU,8872
 pdfdancer/pdfdancer_v1.py,sha256=Pgv-2L0pYQdOUVK2nUntrGB6hCDKUOMWHYuN8loBM3Q,35540
 pdfdancer/types.py,sha256=05zvjA6MEQomNucUUKf5Z33dA7NVFCRu_6LR3Yom1yo,7633
-pdfdancer_client_python-0.2.5.dist-info/METADATA,sha256=YqAuXltFAL3ypn0x7r72dxhJDYMwArPUMzOLCFxNt7A,9253
-pdfdancer_client_python-0.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pdfdancer_client_python-0.2.5.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
-pdfdancer_client_python-0.2.5.dist-info/RECORD,,
+pdfdancer_client_python-0.2.6.dist-info/METADATA,sha256=mQUfTZ7xhjoCWdo6g_5sAerVGtq-tBdaV93Nesj5CcI,6769
+pdfdancer_client_python-0.2.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pdfdancer_client_python-0.2.6.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-0.2.6.dist-info/RECORD,,

pdfdancer_client_python-0.2.5.dist-info/METADATA

@@ -1,305 +0,0 @@
-Metadata-Version: 2.4
-Name: pdfdancer-client-python
-Version: 0.2.5
-Summary: Python client for PDFDancer API
-Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
-License: MIT
-Project-URL: Homepage, https://www.pdfdancer.com/
-Project-URL: Repository, https://github.com/MenschMachine/pdfdancer-client-python
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.25.0
-Requires-Dist: pydantic>=1.8.0
-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.at_page(0))
-
-# Manipulation operations (mirrors Java client methods)
-client._delete(paragraphs[0])
-client._move(images[0], Position.at_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.at_page(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_form_x_objects(position)
-paths = client._find_paths(position)
-text_lines = client._find_text_lines(position)
-
-# Page operations (Java: client.getPages(), client.getPage())
-pages = client.get_pages()
-page = client._get_page(1)  # 1-based indexing
-```
-
-### 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.at_page(0)
-position = Position.at_page_coordinates(0, 100, 200)
-
-# Coordinate access (Java: position.getX(), position.getY())
-x = position.x()
-y = position.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.at_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
-```
-
-### 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]