pdfdancer-client-python 0.3.14__py3-none-any.whl → 3.0.1__py3-none-any.whl

{pdfdancer_client_python-0.3.14.dist-info → pdfdancer_client_python-3.0.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.14
+Version: 3.0.1
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License-Expression: Apache-2.0
@@ -21,11 +21,11 @@ License-File: NOTICE
 Requires-Dist: httpx[http2]>=0.27.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: pypdf>=5.0.0; extra == "dev"
 Requires-Dist: black>=22.0; extra == "dev"
 Requires-Dist: flake8>=5.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
@@ -36,73 +36,74 @@ Dynamic: license-file
 
 # PDFDancer Python Client
 
+This README documents `pdfdancer-client-python` version `3.0.0`.
+
 ![PDFDancer logo](media/logo-silver-60h.webp)
 
-## PDF used to be read-only. We fixed that.
+## Overview
+
+### PDF used to be read-only. We fixed that.
 
 Edit text in real-world PDFs—even ones you didn't create. Move images, reposition headers, and change fonts with
 pixel-perfect control from Python. The same API is also available for TypeScript and Java.
 
-> Need the raw API schema? The latest OpenAPI description lives in `docs/openapi.yml` and is published at
-> https://bucket.pdfdancer.com/api-doc/development-0.0.yml.
-
-## Highlights
-
-- Locate paragraphs, text lines, images, vector paths, form fields, and pages by page number, coordinates, or text patterns.
-- 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, image, and vector path builders with custom fonts and colors.
-- Draw lines, rectangles, and Bezier curves with configurable stroke width, dash patterns, and fill colors.
-- Redact sensitive content—replace text, images, or form fields with customizable placeholders.
-- Export results as bytes for downstream processing or save directly to disk with one call.
-
-## What Makes PDFDancer Different
+### What Makes PDFDancer Different
 
 - **Edit text in real-world PDFs**: Work with documents from customers, governments, or vendors—even ones you didn't create.
 - **Pixel-perfect positioning**: Move or add elements at exact coordinates and keep the original layout intact.
-- **Surgical text replacement**: Swap or rewrite paragraphs without reflowing the rest of the page.
+- **Selector-based text editing**: Apply literal or regular-expression replacements with page scoping and explicit layout policy.
 - **Form manipulation**: Inspect, fill, and update AcroForm fields programmatically.
 - **Coordinate-based selection**: Select objects by position, bounding box, or text patterns.
 - **Vector graphics**: Draw lines, rectangles, and Bezier curves with full control over stroke and fill properties.
-- **Secure redaction**: Permanently remove sensitive content and replace with customizable markers.
 - **Real PDF editing**: Modify the underlying PDF structure instead of merely stamping overlays.
 
+## Highlights
+
+- Replace, insert, delete, and style text with selector-based v2 operations.
+- Locate images, vector paths, form fields, and pages by page number or coordinates; inspect text-line data through snapshots.
+- Programmatically control third-party PDFs—modify invoices, contracts, and reports you did not author.
+- Add images and vector paths with precise XY positioning.
+- Draw lines, rectangles, and Bezier curves with configurable stroke width, dash patterns, and fill colors.
+- Export results as bytes for downstream processing or save directly to disk with one call.
+
 ## Installation
 
 ```bash
-pip install pdfdancer-client-python
+pip install pdfdancer-client-python==3.0.0
 
 # Editable install for local development
 pip install -e .
 ```
 
-Requires Python 3.10+ and a PDFDancer API token.
+## Requirements
+
+- Python 3.10 or newer.
+- A PDFDancer API token, supplied explicitly or through `PDFDANCER_API_TOKEN` or `PDFDANCER_TOKEN`.
+- Access to the PDFDancer API host. The default is `https://api.pdfdancer.com`.
 
-## Quick Start — Edit an Existing PDF
+## Quick Start
+
+### Edit an Existing PDF
 
 ```python
 from pathlib import Path
-from pdfdancer import Color, PDFDancer, StandardFonts
+from pdfdancer import PDFDancer, PdfColorRequest, TextReplaceRequest, TextStyleRequest
 
 with PDFDancer.open(
     pdf_data=Path("input.pdf"),
     token="your-api-token",             # optional when PDFDANCER_API_TOKEN is set
     base_url="https://api.pdfdancer.com",
 ) as pdf:
-    # Locate and update an existing paragraph
-    heading = pdf.page(0).select_paragraphs_starting_with("Executive Summary")[0]
-    heading.move_to(72, 680)
-    with heading.edit() as editor:
-        editor.replace("Overview")
-
-    # Add a new paragraph with precise placement
-    pdf.new_paragraph() \
-        .text("Generated with PDFDancer") \
-        .font(StandardFonts.HELVETICA, 12) \
-        .color(Color(70, 70, 70)) \
-        .line_spacing(1.4) \
-        .at(page_number=1, x=72, y=520) \
-        .add()
+    result = pdf.page(1).text().replace(
+        TextReplaceRequest.literal("Executive Summary", "Overview").build()
+    )
+    assert result.changed == 1
+
+    pdf.text().style(
+        TextStyleRequest.literal("Overview")
+        .fill_color(PdfColorRequest.rgb(0.2, 0.2, 0.6))
+        .build()
+    )
 
     # Persist the modified document
     pdf.save("output.pdf")
@@ -114,68 +115,54 @@ with PDFDancer.open(
 
 ```python
 from pathlib import Path
-from pdfdancer import Color, PDFDancer, StandardFonts
+from pdfdancer import PDFDancer
 
 with PDFDancer.new(token="your-api-token") as pdf:
-    pdf.new_paragraph() \
-        .text("Quarterly Summary") \
-        .font(StandardFonts.TIMES_BOLD, 18) \
-        .color(Color(10, 10, 80)) \
-        .line_spacing(1.2) \
-        .at(page_number=1, x=72, y=730) \
-        .add()
-
     pdf.new_image() \
         .from_file(Path("logo.png")) \
-        .at(page=0, x=420, y=710) \
+        .at(page=1, x=420, y=710) \
         .add()
 
     pdf.save("summary.pdf")
 ```
 
-## Work with Forms and Layout
+## Page API
 
-```python
-from pdfdancer import PDFDancer
+Page numbers are 1-based. `pdf.page(1)` returns a page-scoped client, while `pdf.pages()` returns page clients for the
+document. Use `get_snapshot()` on a page client for a read-only page snapshot.
 
-with PDFDancer.open("contract.pdf") as pdf:
-    # Inspect global document structure
-    pages = pdf.pages()
-    print("Total pages:", len(pages))
-
-    # Update form fields
-    signature = pdf.select_form_fields_by_name("signature")[0]
-    signature.edit().value("Signed by Jane Doe").apply()
-
-    # Trim or move content at specific coordinates
-    images = pdf.page(1).select_images()
-    for image in images:
-        x = image.position.x()
-        if x is not None and x < 100:
-            image.delete()
+```python
+first_page = pdf.page(1)
+pages = pdf.pages()
+snapshot = first_page.get_snapshot()
 ```
 
-Selectors return typed objects (`ParagraphObject`, `TextLineObject`, `ImageObject`, `FormFieldObject`, `PageClient`, …)
-with helpers such as `delete()`, `move_to(x, y)`, `clear_clipping()`, `redact()`, or `edit()` depending on the object type.
+Page-scoped selectors, text editing, and builders automatically restrict the operation to that page.
+
+## Selection
 
-**Singular selection methods** return the first match (or `None`) for convenience:
+Document- and page-scoped selectors return typed objects for images, paths, form XObjects, and form fields. Position
+selectors use PDF coordinates and a default tolerance of `0.01` point. Singular selectors return the first match or
+`None`; plural selectors return lists.
 
 ```python
-# Instead of: paragraphs = page.select_paragraphs_starting_with("Invoice")[0]
-paragraph = page.select_paragraph_starting_with("Invoice")  # Returns first match or None
-image = page.select_image_at(100, 200)                      # Returns first match or None
-field = pdf.select_form_field_by_name("email")              # Returns first match or None
+document_images = pdf.select_images()
+logo = pdf.page(1).select_image_at(72, 680)
+page_paths = pdf.page(1).select_paths()
 ```
 
-## Draw Vector Paths
+Document and page snapshots provide read-only text-line data. Use the selector-based text API for mutations.
 
-Add lines, curves, and shapes to your PDFs with fluent builders:
+## Builders and Vector Paths
+
+All five dedicated builders are available at document and page scope: image, path, line, Bezier, and rectangle. Add
+lines, curves, and shapes with fluent builders:
 
 ```python
 from pdfdancer import PDFDancer, Color, Point
 
 with PDFDancer.open("document.pdf") as pdf:
-    page = pdf.page(0)
+    page = pdf.page(1)
 
     # Draw a simple line
     page.new_line() \
@@ -213,39 +200,95 @@ with PDFDancer.open("document.pdf") as pdf:
     pdf.save("annotated.pdf")
 ```
 
-## Redact Sensitive Content
+`PathBuilder` also provides cursor-based `move_to(...)`, `line_to(...)`, and `bezier_to(...)` operations plus
+`close_path()`, `rectangle(...)`, `circle(...)`, and `solid()` conveniences. A circle is a `PathBuilder` convenience,
+not a separate builder type.
+
+## Images
 
-Remove text, images, or form fields and replace them with redaction markers:
+Create images at document scope with an explicit page or directly from a page client:
 
 ```python
-from pdfdancer import PDFDancer, Color
+from pathlib import Path
+
+pdf.new_image().from_file(Path("logo.png")).at(page=1, x=72, y=700).add()
+pdf.page(1).new_image().from_file(Path("stamp.png")).at(x=300, y=700).add()
+```
 
-with PDFDancer.open("confidential.pdf") as pdf:
-    # Redact paragraphs containing sensitive patterns
-    for para in pdf.select_paragraphs():
-        if "SSN:" in para.text or "Password:" in para.text:
-            para.redact("[REDACTED]")
+`ImageObject` exposes `width`, `height`, and `aspect_ratio`. It supports replacement from a filesystem path or `Image`,
+proportional or explicit scaling, cropping, opacity, horizontal and vertical flips, region filling, and rotation.
+Positive rotation angles are clockwise. Image transformations return `CommandResult`, which exposes `success`,
+`message`, `warning`, and `element_id`.
 
-    # Redact all images on a specific page
-    for image in pdf.page(0).select_images():
-        image.redact()
+## Form Fields
 
-    # Bulk redact multiple objects with custom placeholder color
-    form_fields = pdf.select_form_fields_by_name("credit_card")
-    result = pdf.redact(form_fields, replacement="[REMOVED]", placeholder_color=Color(0, 0, 0))
-    print(f"Redacted {result.count} items")
+Form-field selection uses the same names at document and page scope. Mutate a selected field directly with
+`set_value(...)`:
 
-    pdf.save("redacted.pdf")
+```python
+signature = pdf.select_form_fields_by_name("signature")[0]
+changed = signature.set_value("Signed by Jane Doe")
+```
+
+Selectors return typed objects (`ImageObject`, `FormFieldObject`, `PathObject`, `PageClient`, …) with generic helpers
+such as `delete()`, `move_to(x, y)`, and `clear_clipping()` where supported by the selected object type.
+
+## Text Editing
+
+Text editing is selector-based and is available through `pdf.text()` and `pdf.page(page_number).text()`. It supports
+replace, delete, insert, and style operations:
+
+```python
+from pdfdancer import TextDeleteRequest, TextInsertRequest, TextReplaceRequest
+
+pdf.text().replace(
+    TextReplaceRequest.literal("Old product", "New product")
+    .whole_words(True)
+    .max_matches(5)
+    .build()
+)
+
+pdf.page(2).text().delete(
+    TextDeleteRequest.regex(r"Confidential\s+draft")
+    .case_sensitive(False)
+    .build()
+)
+
+pdf.text().insert(
+    TextInsertRequest.before("Terms", "Updated ").whole_words(True).build()
+)
 ```
 
+Each mutation returns `TextEditResponse`, including match and change counts, changed page numbers, per-change
+diagnostics, warnings, and errors.
+
+## Shared Models
+
+`Color` requires integral RGBA components in the inclusive range 0–255. Alpha defaults to 255; `BLACK`, `WHITE`, and
+`RED` are provided as constants.
+
+`PageSize` provides A0–A6, B4–B5, Letter, Legal, Tabloid, Executive, Postcard, and 3×5 Index sizes.
+`PageSize.from_dimensions(...)` recognizes both portrait and rotated standard dimensions; custom dimensions must be
+finite and positive.
+
+The exported `ObjectType` enum covers every object type returned by the v2 snapshot and selection APIs.
+
 ## Configuration
 
+- The SDK reads the process environment but does not load `.env` files. Applications that use `.env` files must load
+  them before calling the SDK.
 - Set `PDFDANCER_API_TOKEN` for authentication (preferred). `PDFDANCER_TOKEN` is also supported for backwards compatibility.
 - Override the API host with `PDFDANCER_BASE_URL` (e.g., sandbox or local environments). Defaults to `https://api.pdfdancer.com`.
 - Tune HTTP read timeouts via the `timeout` argument on `PDFDancer.open()` and `PDFDancer.new()` (default: 30 seconds).
+- Configure total request attempts with `max_attempts` or `PDFDANCER_MAX_ATTEMPTS`; the initial request counts as one attempt.
 - For testing against self-signed certificates, call `pdfdancer.set_ssl_verify(False)` to temporarily disable TLS verification.
 
-## Error Handling
+## Retry and Error Handling
+
+The default HTTP policy makes three total attempts, including the initial request. It uses exponential backoff starting
+at one second, a multiplier of two, and a five-second delay cap. Statuses 408, 429, 500, 502, 503, 504, and 520 are
+retryable, as are timeout and connection failures. `Retry-After` is honored only for HTTP 429; retry delays do not use
+jitter. Configure the total attempt count with `max_attempts` and the multiplier with `retry_backoff_factor`.
 
 Operations raise subclasses of `PdfDancerException`:
 
@@ -257,7 +300,7 @@ Operations raise subclasses of `PdfDancerException`:
 
 Wrap automated workflows in `try/except` blocks to surface actionable errors to your users.
 
-## Development Setup
+## Development and Testing
 
 ### Prerequisites
 
@@ -274,37 +317,31 @@ git clone https://github.com/MenschMachine/pdfdancer-client-python.git
 cd pdfdancer-client-python
 ```
 
-#### 2. Create a Virtual Environment
+#### 2. Create a Virtual Environment and Install Dependencies
 
 ```bash
-# Create virtual environment
-python -m venv venv
-
-# Activate the virtual environment
-# On macOS/Linux:
-source venv/bin/activate
-
-# On Windows:
-venv\Scripts\activate
+# Create `venv` and install the package with development dependencies
+make install-dev
 ```
 
-You should see `(venv)` in your terminal prompt indicating the virtual environment is active.
-
-#### 3. Install Dependencies
+The Makefile creates the local `venv` when needed and runs all developer targets with its Python interpreter. Activating
+the environment is optional; activate it if you also want to run commands directly:
 
 ```bash
-# Install the package in editable mode with development dependencies
-pip install -e ".[dev]"
+# macOS/Linux
+source venv/bin/activate
 
-# Alternatively, install runtime dependencies only:
-# pip install -e .
+# Windows
+venv\Scripts\activate
 ```
 
 This installs:
 - The `pdfdancer` package in editable mode (changes reflect immediately)
 - Development tooling including `pytest`, `pytest-cov`, `pytest-mock`, `black`, `isort`, `flake8`, `mypy`, `build`, and `twine`.
 
-#### 4. Configure API Token
+To install runtime dependencies without development tools, use `make install`.
+
+#### 3. Configure API Token
 
 Set your PDFDancer API token as an environment variable:
 
@@ -321,7 +358,7 @@ $env:PDFDANCER_API_TOKEN="your-api-token-here"
 
 For permanent configuration, add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).
 
-#### 5. Verify Installation
+#### 4. Verify Installation
 
 ```bash
 # Run the test suite
@@ -338,30 +375,33 @@ All tests should pass if everything is set up correctly.
 
 ### Common Development Tasks
 
+Run `make help` to list all developer targets and their configurable variables.
+
 #### Running Tests
 
 ```bash
 # Run all tests with verbose output
-pytest tests/ -v
+make test
 
-# Run specific test file
-pytest tests/test_models.py -v
+# Run tests that do not require API access
+make test-unit
 
 # Run end-to-end tests only
-pytest tests/e2e/ -v
+make test-e2e
+
+# Run a specific test file or pass additional pytest arguments
+make test TEST_PATH=tests/test_models.py
+make test PYTEST_ARGS="-v -x"
 
-# Run with coverage report
-pytest tests/ --cov=pdfdancer --cov-report=term-missing
+# Run all tests with a coverage report
+make coverage
 ```
 
 #### Building Distribution Packages
 
 ```bash
-# Build wheel and source distribution
-python -m build
-
-# Verify the built packages
-python -m twine check dist/*
+# Clean, build, and verify the wheel and source distribution
+make package
 ```
 
 Artifacts will be created in the `dist/` directory. Package versions are derived from Git tags via `setuptools-scm`.
@@ -372,22 +412,27 @@ Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub
 
 ```bash
 # Create and push a release tag — GitHub Actions handles the rest
-git tag v1.1.0
-git push origin v1.1.0
+git tag v2.0.0
+git push origin v2.0.0
 ```
 
 #### Code Quality
 
 ```bash
 # Format code
-black src tests
-isort src tests
+make format
+
+# Check formatting without changing files
+make format-check
 
 # Lint
-flake8 src tests
+make lint
+
+# Type-check
+make typecheck
 
-# Type checking
-mypy src/pdfdancer/
+# Run formatting checks, linting, type checking, and non-E2E tests
+make check
 ```
 
 ### Project Structure
@@ -396,14 +441,13 @@ mypy src/pdfdancer/
 pdfdancer-client-python/
 ├── src/pdfdancer/           # Main package source
 │   ├── __init__.py          # Package exports
-│   ├── pdfdancer_v1.py      # Core PDFDancer and PageClient classes
-│   ├── paragraph_builder.py # Fluent paragraph builders
-│   ├── text_line_builder.py # Fluent text line builders
+│   ├── pdfdancer_v2.py      # Core PDFDancer and PageClient classes
+│   ├── text_editing.py      # Selector-based v2 text request builders
 │   ├── image_builder.py     # Fluent image builders
 │   ├── path_builder.py      # Vector path builders (lines, beziers, rectangles)
 │   ├── page_builder.py      # Page creation builder
 │   ├── models.py            # Data models (Position, Font, Color, etc.)
-│   ├── types.py             # Object wrappers (ParagraphObject, etc.)
+│   ├── types.py             # Live object-reference wrappers
 │   └── exceptions.py        # Exception hierarchy
 ├── tests/                   # Test suite
 │   ├── test_models.py       # Model unit tests
@@ -415,7 +459,7 @@ pdfdancer-client-python/
 └── README.md                # This file
 ```
 
-### Troubleshooting
+## Troubleshooting
 
 #### Virtual Environment Issues
 
@@ -448,7 +492,7 @@ pip install -e .
 - Check network connectivity to the PDFDancer API
 - Verify you're using Python 3.10 or higher
 
-### Contributing
+## Contributing
 
 Contributions are welcome via pull request. Please:
 
@@ -458,7 +502,7 @@ Contributions are welcome via pull request. Please:
 4. Follow existing code style and patterns
 5. Update documentation as needed
 
-## Helpful links
+## Helpful Links
 
 - [API documentation](https://docs.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
 - [Product overview](https://www.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)

pdfdancer_client_python-3.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+pdfdancer/__init__.py,sha256=iD0IWfpLFrPoFQhsZ_fGUpv9fH21QNJchM_23pTtdds,4419
+pdfdancer/_runtime_version.py,sha256=UIId9w7Jk97tPVOppEJeq4HKVEt3BIMc6jeThKU31k4,825
+pdfdancer/_version.py,sha256=DQj8PXaBgkooJVvjTVd86hfQE03x_PUMKRF3guh3670,520
+pdfdancer/exceptions.py,sha256=U6kD3NvcdNt05_OU11Tml5dXGtlodEtYC9zcV4fHXkc,2270
+pdfdancer/fingerprint.py,sha256=eL3PHPgv-knMya7s95RXg3qzzpkAA1aevxqb6tuOb34,3061
+pdfdancer/image_builder.py,sha256=R4ik7ZN-iGWUsy7UHoMvpAEzc_MHquPY9Q27g_zuEtI,2987
+pdfdancer/models.py,sha256=6N-rybJnXo2Y3KrWcBxN0uVq5HxyrVDqMO52lcvW_G4,51558
+pdfdancer/page_builder.py,sha256=2Ll98fkNen7dtlQe_uhYDJPKqqnqMMeOTYlymeWtaII,3528
+pdfdancer/path_builder.py,sha256=znQD3zgBs7u--pQ3OdUJOSvBhBLCm80pdH6Kg0_T-io,28502
+pdfdancer/pdfdancer_v2.py,sha256=8YiMMDeaybPNBpybf9kESwnE48wscdOlk1AcJrDCBSc,120419
+pdfdancer/text_editing.py,sha256=iA3n-yWca95ilNJSHMxFirGKhXpl_SGgg2NuuAUVGOQ,51768
+pdfdancer/types.py,sha256=Mwr4d1C-pS7kSctgXH0F6LEOu8Q0EFaFAOMjiGlrRaQ,16961
+pdfdancer_client_python-3.0.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+pdfdancer_client_python-3.0.1.dist-info/licenses/NOTICE,sha256=xaC4l-IChAmtViNDie8ZWzUk0O6XRMyzOl0zLmVZ2HE,232
+pdfdancer_client_python-3.0.1.dist-info/METADATA,sha256=oiYBb7IxHTiNZL3ZyIo30Ht0Q9xpzMV_rVrB3_GI-vw,17618
+pdfdancer_client_python-3.0.1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pdfdancer_client_python-3.0.1.dist-info/top_level.txt,sha256=ICwSVRpcCKrdBF9QlaX9Y0e_N3Nk1p7QVxadGOnbxeY,10
+pdfdancer_client_python-3.0.1.dist-info/RECORD,,

{pdfdancer_client_python-0.3.14.dist-info → pdfdancer_client_python-3.0.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any