pdfdancer-client-python 0.3.11__tar.gz → 0.3.13__tar.gz

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [ '**' ]
+    branches: [ 'main' ]
   pull_request:
     branches: [ '**' ]
   workflow_dispatch:
@@ -12,6 +12,10 @@ jobs:
     # Quick minimal test on non-main branches
     if: github.ref != 'refs/heads/main'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
     strategy:
       fail-fast: false
       max-parallel: 2
@@ -20,6 +24,54 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Resolve API base URL
+        id: resolve-api-base-url
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROPAGATE_TOKEN }}
+          script: |
+            const fallbackUrl = 'https://api-staging.pdfdancer.com';
+            const pr = context.payload.pull_request;
+            if (!pr) {
+              core.setOutput('base_url', fallbackUrl);
+              return;
+            }
+
+            const body = pr.body || '';
+            const apiPrMatch = body.match(/## Source API PR[\s\S]*?^- Repository:\s*MenschMachine\/pdfdancer-api\s*$[\s\S]*?^- PR:\s*#?(\d+)\s*$/im);
+            if (!apiPrMatch) {
+              core.info('No Source API PR block found in the PR body; using staging API.');
+              core.setOutput('base_url', fallbackUrl);
+              return;
+            }
+
+            const apiPrNumber = Number(apiPrMatch[1]);
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: 'MenschMachine',
+              repo: 'pdfdancer-api',
+              issue_number: apiPrNumber,
+              per_page: 100,
+            });
+            const previewComments = comments.filter((comment) =>
+              typeof comment.body === 'string' && comment.body.includes('### Preview Environment')
+            );
+            if (previewComments.length === 0) {
+              core.setFailed(`Source API PR #${apiPrNumber} is referenced by this PR, but no preview comment was found.`);
+              return;
+            }
+
+            const previewComment = previewComments[previewComments.length - 1];
+            const urlMatch = previewComment.body.match(/\*\*API URL:\*\*\s*(https?:\/\/\S+)/);
+            if (!urlMatch) {
+              core.setFailed(`Preview comment on source API PR #${apiPrNumber} does not contain a parseable API URL.`);
+              return;
+            }
+
+            core.info(`Using preview API URL from source API PR #${apiPrNumber}: ${urlMatch[1]}`);
+            core.setOutput('base_url', urlMatch[1]);
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -40,8 +92,8 @@ jobs:
 
       - name: Run tests
         run: |
-          PDFDANCER_BASE_URL=https://api-staging.pdfdancer.com \
-          PDFDANCER_TOKEN=42 \
+          PDFDANCER_BASE_URL=${{ steps.resolve-api-base-url.outputs.base_url }} \
+          PDFDANCER_API_TOKEN=42 \
           venv/bin/python -m pytest tests/ -v --maxfail=3
 
       - name: Build distribution packages
@@ -55,6 +107,10 @@ jobs:
     # Full matrix only on main
     if: github.ref == 'refs/heads/main'
     runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+      issues: read
+      pull-requests: read
     strategy:
       fail-fast: false
       max-parallel: 2
@@ -64,6 +120,16 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Resolve API base URL
+        id: resolve-api-base-url
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.PROPAGATE_TOKEN }}
+          script: |
+            core.setOutput('base_url', 'https://api-staging.pdfdancer.com');
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -88,8 +154,8 @@ jobs:
       - name: Run tests (Unix)
         if: runner.os != 'Windows'
         run: |
-          PDFDANCER_BASE_URL=https://api-staging.pdfdancer.com \
-          PDFDANCER_TOKEN=42 \
+          PDFDANCER_BASE_URL=${{ steps.resolve-api-base-url.outputs.base_url }} \
+          PDFDANCER_API_TOKEN=42 \
           venv/bin/python -m pytest tests/ -v --maxfail=3
 
       - name: Build & Validate (Unix)
@@ -119,8 +185,8 @@ jobs:
         if: runner.os == 'Windows'
         shell: cmd
         run: |
-          set PDFDANCER_BASE_URL=https://api-staging.pdfdancer.com
-          set PDFDANCER_TOKEN=42
+          set PDFDANCER_BASE_URL=${{ steps.resolve-api-base-url.outputs.base_url }}
+          set PDFDANCER_API_TOKEN=42
           venv\Scripts\python -m pytest tests/ -v --maxfail=3
 
       - name: Build & Validate (Windows)
@@ -128,4 +194,4 @@ jobs:
         shell: cmd
         run: |
           venv\Scripts\python -m build
-          venv\Scripts\python -m twine check dist/*
+          venv\Scripts\python -m twine check dist/*

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/.github/workflows/daily-tests.yml

@@ -18,6 +18,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/.github/workflows/release.yml

@@ -9,6 +9,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
@@ -39,6 +41,8 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Set up Python 3.12
         uses: actions/setup-python@v5
@@ -71,6 +75,8 @@ jobs:
       contents: write
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
 
       - name: Create GitHub Release
         run: gh release create "$GITHUB_REF_NAME" --generate-notes

pdfdancer_client_python-0.3.13/.github/workflows/sdk-backward-compat.yml

@@ -0,0 +1,88 @@
+name: SDK Backward Compatibility Tests
+
+on:
+  repository_dispatch:
+    types: [api-preview-deployed]
+
+  workflow_dispatch:
+    inputs:
+      api_url:
+        description: 'API base URL to test against'
+        required: true
+        type: string
+      sdk_token:
+        description: 'API token for testing'
+        required: true
+        type: string
+        default: '42'
+
+jobs:
+  get-tags:
+    runs-on: ubuntu-latest
+    outputs:
+      tags: ${{ steps.tags.outputs.tags }}
+    steps:
+      - name: Fetch tags
+        id: tags
+        run: |
+          TAGS=$(git ls-remote --tags https://github.com/MenschMachine/pdfdancer-client-python.git \
+            | grep -v '\^{}' \
+            | awk -F'/' '{print $NF}' \
+            | grep '^v' \
+            | sort -V \
+            | tail -3 \
+            | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          echo "tags=$TAGS" >> "$GITHUB_OUTPUT"
+          echo "Last 3 SDK tags: $TAGS"
+
+  test-compat:
+    needs: get-tags
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      max-parallel: 1
+      matrix:
+        tag: ${{ fromJSON(needs.get-tags.outputs.tags) }}
+
+    steps:
+      - name: Checkout SDK at ${{ matrix.tag }}
+        uses: actions/checkout@v4
+        with:
+          repository: MenschMachine/pdfdancer-client-python
+          ref: ${{ matrix.tag }}
+          path: sdk
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Create virtual environment
+        run: python -m venv venv
+
+      - name: Install SDK at ${{ matrix.tag }}
+        run: |
+          venv/bin/pip install --upgrade pip
+          venv/bin/pip install -e "./sdk[dev]"
+
+      - name: Run e2e tests
+        working-directory: sdk
+        run: |
+          PDFDANCER_BASE_URL=${{ github.event.client_payload.api_url || inputs.api_url }} \
+          PDFDANCER_API_TOKEN=${{ github.event.client_payload.sdk_token || inputs.sdk_token }} \
+          ../venv/bin/python -m pytest -v -x \
+            -k "not test_redact_multiple_paths and not test_context_manager_vs_manual_apply" \
+            --junitxml=test-results.xml
+        env:
+          PYTHONWARNINGS: "ignore:Unverified HTTPS request"
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-${{ matrix.tag }}
+          path: |
+            sdk/test-results.xml
+            sdk/.pytest_cache/
+          retention-days: 7

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/.gitignore

@@ -19,3 +19,5 @@ __pycache__/
 /.run/
 /build
 .env
+.propagate*md
+/.last-message.txt

pdfdancer_client_python-0.3.13/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "tests/fixtures/examples"]
+	path = tests/fixtures/examples
+	url = https://github.com/MenschMachine/pdfdancer-examples.git

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.11
+Version: 0.3.13
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 
@@ -359,7 +359,7 @@ with PDFDancer.open("contract.pdf") as pdf:
 ```
 
 Selectors return typed objects (`ParagraphObject`, `TextLineObject`, `ImageObject`, `FormFieldObject`, `PageClient`, …)
-with helpers such as `delete()`, `move_to(x, y)`, `redact()`, or `edit()` depending on the object type.
+with helpers such as `delete()`, `move_to(x, y)`, `clear_clipping()`, `redact()`, or `edit()` depending on the object type.
 
 **Singular selection methods** return the first match (or `None`) for convenience:
 

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/README.md

@@ -120,7 +120,7 @@ with PDFDancer.open("contract.pdf") as pdf:
 ```
 
 Selectors return typed objects (`ParagraphObject`, `TextLineObject`, `ImageObject`, `FormFieldObject`, `PageClient`, …)
-with helpers such as `delete()`, `move_to(x, y)`, `redact()`, or `edit()` depending on the object type.
+with helpers such as `delete()`, `move_to(x, y)`, `clear_clipping()`, `redact()`, or `edit()` depending on the object type.
 
 **Singular selection methods** return the first match (or `None`) for convenience:
 

pdfdancer_client_python-0.3.13/docs/capabilities/CLEAR_CLIPPING.md

@@ -0,0 +1,61 @@
+# Clear Clipping Capability
+
+Most of the PDF model classes including container classes like PDFParagraph/PDFTextLine/PDFPathGroup now implement ClippingDetachable with the method clearClipping().
+This removes any clipping path which was active for this element.
+
+This is useful in case clients want to move an element but the new position is hidden by the clipping path. clearing it makes the element visible again.
+
+The new backend is version 1.8.6-rc2, available in the local m2 repository
+
+## Test PDFs to use
+
+examples/clipping/invisible-content-clipping-test.pdf
+
+- A PDF where content is present but not visible due to clipping paths that exclude the content areas. Contains an image clipped away by one clipping path and vector paths clipped away by another clipping path.
+
+
+## Api Docs
+
+Explain for all elements and under the clipping-section.
+
+## Website and Marketing
+
+Not to mention there.
+
+## What's new Newsletter
+
+include
+
+## Changelog
+
+include
+
+## Implementation in pdfdancer-api
+
+- Updated backend dependency to `com.tfc.pdf:pdfdancer-backend:1.8.6-rc2` in `build.gradle.kts` to use the clipping-detach support.
+- Added client-facing helpers:
+  - `BaseReference.clearClipping()` for any object reference implementing clipping detach semantics via the API.
+  - `PathGroupReference.clearClipping()` for grouped vector paths.
+  - `PDFDancer.clearClipping(ObjectRef)` calling `PUT /pdf/clipping/clear`.
+  - `PDFDancer.clearPathGroupClipping(pageIndex, groupId)` calling `PUT /pdf/path-group/clipping/clear`.
+  - Both client calls invalidate local snapshot caches after mutation.
+- Added server endpoints in both controllers:
+  - `PDFController` and `PDFControllerV1` expose `PUT /pdf/clipping/clear` and `PUT /pdf/path-group/clipping/clear`.
+  - V1 uses `ClearClippingRequestV1` and `ClearPathGroupClippingRequestV1`, converting both to internal requests via `toInternal()`.
+- Added controller orchestration in `ControllerOps`:
+  - `clearClipping(...)` validates `objectRef`, executes `ClearObjectClippingCommand`, and publishes `PDF_OBJECT_MODIFIED` metric with operation `clear_clipping`.
+  - `clearPathGroupClipping(...)` validates `groupId` and `pageIndex`, executes `ClearPathGroupClippingCommand`, and publishes `VECTOR_MANIPULATION` metric with operation `clear_path_group_clipping`.
+- Wired session and replay support:
+  - `Session.clearClipping(...)` and `Session.clearPathGroupClipping(...)` execute commands inside `SessionContext` and record commands for session history.
+  - `CommandDeserializer` now reconstructs `ClearObjectClippingCommand` and `ClearPathGroupClippingCommand` for debug archive replay.
+- Added tests and assertions:
+  - `ClippingTest` verifies clearing clipping on `PathReference`, `PathGroupReference`, and `TextLineReference`.
+  - `DirectPDFAssertions`/`PDFAssertions` gained helpers to detect clipped paths and assert clipping present/removed.
+
+## Implementation in pdfdancer-client-python
+
+- Added top-level client methods in `src/pdfdancer/pdfdancer_v1.py`: `PDFDancer.clear_clipping(object_ref)` calls `PUT /pdf/clipping/clear`, and `PDFDancer.clear_path_group_clipping(page_number, group_id)` calls `PUT /pdf/path-group/clipping/clear`.
+- The Python client validates required inputs before sending the request: `object_ref` must be present, `page_number` is a 1-based integer for path groups, and `group_id` must be non-empty. Both methods coerce the API response to `bool` and invalidate cached snapshots after a successful mutation.
+- Added object-level convenience methods in `src/pdfdancer/types.py`. `PDFObjectBase.clear_clipping()` makes the capability available on typed selections that expose `object_ref()` such as paths, images, and text lines, while `PathGroupObject.clear_clipping()` forwards to the path-group API using `self._page_index + 1` to convert the internal 0-based index to the public 1-based page number.
+- Updated `README.md` to list `clear_clipping()` alongside other typed-object helper methods so the feature is discoverable from the main usage guide.
+- Added end-to-end coverage in `tests/e2e/test_clipping.py` for direct object calls and top-level client calls on paths, grouped paths, images, and clipped text lines, including a case where clipping spans multiple content streams. `tests/e2e/pdf_assertions.py` was extended with PDF draw-event inspection helpers that assert whether clipping is present or removed.

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/pyproject.toml

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

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/src/pdfdancer/__init__.py

@@ -28,6 +28,7 @@ from .models import (
     ImageTransformRequest,
     ImageTransformType,
     Line,
+    ModifyPathRequest,
     ObjectRef,
     ObjectType,
     Orientation,
@@ -36,6 +37,7 @@ from .models import (
     Paragraph,
     Path,
     PathGroupInfo,
+    PathObjectRef,
     PathSegment,
     Point,
     Position,
@@ -55,7 +57,7 @@ from .paragraph_builder import ParagraphBuilder
 from .path_builder import BezierBuilder, LineBuilder, PathBuilder
 from .text_line_builder import TextLineBuilder
 
-__version__ = "0.3.11"
+__version__ = "0.3.13"
 __all__ = [
     "PDFDancer",
     "ParagraphBuilder",
@@ -65,6 +67,8 @@ __all__ = [
     "LineBuilder",
     "BezierBuilder",
     "ObjectRef",
+    "PathObjectRef",
+    "ModifyPathRequest",
     "Position",
     "ObjectType",
     "Font",

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.13}/src/pdfdancer/models.py

@@ -1895,3 +1895,85 @@ class ImageTransformRequest:
             result["fillColor"] = self.fill_color
 
         return result
+
+
+@dataclass
+class ModifyPathRequest:
+    """Request to modify path stroke and fill colors.
+
+    Parameters:
+    - object_ref: Reference to the path to modify.
+    - stroke_color: New stroke color (optional - null means don't change).
+    - fill_color: New fill color (optional - null means don't change).
+
+    Example:
+    ```python
+    req = ModifyPathRequest(object_ref=path_ref, stroke_color=Color(255, 0, 0), fill_color=None)
+    payload = req.to_dict()
+    ```
+    """
+
+    object_ref: ObjectRef
+    stroke_color: Optional[Color] = None
+    fill_color: Optional[Color] = None
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        result: Dict[str, Any] = {
+            "ref": self.object_ref.to_dict(),
+        }
+
+        if self.stroke_color is not None:
+            result["strokeColor"] = {
+                "red": self.stroke_color.r,
+                "green": self.stroke_color.g,
+                "blue": self.stroke_color.b,
+                "alpha": self.stroke_color.a,
+            }
+
+        if self.fill_color is not None:
+            result["fillColor"] = {
+                "red": self.fill_color.r,
+                "green": self.fill_color.g,
+                "blue": self.fill_color.b,
+                "alpha": self.fill_color.a,
+            }
+
+        return result
+
+
+class PathObjectRef(ObjectRef):
+    """
+    Reference to a path object with stroke and fill color information.
+
+    Parameters (typically provided by the server):
+    - internal_id: Identifier of the path object.
+    - position: Position of the path.
+    - object_type: Should be ObjectType.PATH.
+    - stroke_color: Stroke/outline color of the path (optional).
+    - fill_color: Fill color of the path (optional).
+
+    Usage:
+    - Returned by find/snapshot APIs when querying paths.
+    - Pass to ModifyPathRequest to update path colors.
+    """
+
+    def __init__(
+        self,
+        internal_id: str,
+        position: Position,
+        object_type: ObjectType,
+        stroke_color: Optional[Color] = None,
+        fill_color: Optional[Color] = None,
+    ):
+        super().__init__(internal_id, position, object_type)
+        self.stroke_color = stroke_color
+        self.fill_color = fill_color
+
+    def get_stroke_color(self) -> Optional[Color]:
+        """Get the stroke/outline color of the path."""
+        return self.stroke_color
+
+    def get_fill_color(self) -> Optional[Color]:
+        """Get the fill color of the path."""
+        return self.fill_color