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

pdfdancer_client_python-0.3.12/.api-url

@@ -0,0 +1 @@
+http://46.225.120.69:8080

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

@@ -2,7 +2,7 @@ name: CI
 
 on:
   push:
-    branches: [ '**' ]
+    branches: [ 'main' ]
   pull_request:
     branches: [ '**' ]
   workflow_dispatch:
@@ -20,6 +20,19 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Detect API URL override
+        if: github.event_name == 'pull_request'
+        id: api-url
+        run: |
+          if [ -f .api-url ]; then
+            url=$(cat .api-url | tr -d '[:space:]')
+            if [ -n "$url" ]; then
+              echo "base_url=$url" >> "$GITHUB_OUTPUT"
+            fi
+          fi
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -40,7 +53,7 @@ jobs:
 
       - name: Run tests
         run: |
-          PDFDANCER_BASE_URL=https://api-staging.pdfdancer.com \
+          PDFDANCER_BASE_URL=${{ steps.api-url.outputs.base_url || 'https://api-staging.pdfdancer.com' }} \
           PDFDANCER_TOKEN=42 \
           venv/bin/python -m pytest tests/ -v --maxfail=3
 
@@ -64,6 +77,20 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Detect API URL override
+        if: github.event_name == 'pull_request'
+        id: api-url
+        shell: bash
+        run: |
+          if [ -f .api-url ]; then
+            url=$(cat .api-url | tr -d '[:space:]')
+            if [ -n "$url" ]; then
+              echo "base_url=$url" >> "$GITHUB_OUTPUT"
+            fi
+          fi
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
@@ -88,7 +115,7 @@ jobs:
       - name: Run tests (Unix)
         if: runner.os != 'Windows'
         run: |
-          PDFDANCER_BASE_URL=https://api-staging.pdfdancer.com \
+          PDFDANCER_BASE_URL=${{ steps.api-url.outputs.base_url || 'https://api-staging.pdfdancer.com' }} \
           PDFDANCER_TOKEN=42 \
           venv/bin/python -m pytest tests/ -v --maxfail=3
 
@@ -119,7 +146,7 @@ jobs:
         if: runner.os == 'Windows'
         shell: cmd
         run: |
-          set PDFDANCER_BASE_URL=https://api-staging.pdfdancer.com
+          set PDFDANCER_BASE_URL=${{ steps.api-url.outputs.base_url || 'https://api-staging.pdfdancer.com' }}
           set PDFDANCER_TOKEN=42
           venv\Scripts\python -m pytest tests/ -v --maxfail=3
 

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.12}/.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.12}/.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.11 → pdfdancer_client_python-0.3.12}/.gitignore

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

pdfdancer_client_python-0.3.12/.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.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.11
+Version: 0.3.12
 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.12}/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.12/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.12}/pyproject.toml

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

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

@@ -55,7 +55,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.12"
 __all__ = [
     "PDFDancer",
     "ParagraphBuilder",

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.12}/src/pdfdancer/pdfdancer_v1.py

@@ -134,7 +134,7 @@ DEFAULT_RETRY_BACKOFF_FACTOR = float(
 
 
 def _dict_to_replacements(
-    replacements: Dict[str, Union[str, dict]]
+    replacements: Dict[str, Union[str, dict]],
 ) -> List[TemplateReplacement]:
     """Convert dict-based replacements to TemplateReplacement list."""
     result = []
@@ -2292,6 +2292,37 @@ class PDFDancer:
         targets = [RedactTarget(obj.internal_id, replacement) for obj in objects]
         return self._redact(targets, replacement, placeholder_color)
 
+    def clear_clipping(self, object_ref: ObjectRef) -> bool:
+        """
+        Clear clipping on a single PDF object.
+
+        Args:
+            object_ref: Reference to the object whose clipping should be removed
+
+        Returns:
+            True when the server cleared clipping successfully
+        """
+        return self._clear_clipping(object_ref)
+
+    def _clear_clipping(self, object_ref: ObjectRef) -> bool:
+        """
+        Internal helper to clear clipping from a single object.
+        """
+        if object_ref is None:
+            raise ValidationException("Object reference cannot be null")
+
+        response = self._make_request(
+            "PUT",
+            "/pdf/clipping/clear",
+            data={"objectRef": object_ref.to_dict()},
+        )
+        result = bool(response.json())
+
+        if result:
+            self._invalidate_snapshots()
+
+        return result
+
     # Template Replacement Operations
 
     def _apply_replacements(
@@ -2506,19 +2537,21 @@ class PDFDancer:
             data["pathIds"] = path_ids
         if region is not None:
             data["region"] = {
-                "x": region.x, "y": region.y,
-                "width": region.width, "height": region.height,
+                "x": region.x,
+                "y": region.y,
+                "width": region.width,
+                "height": region.height,
             }
-        response = self._make_request(
-            "POST", "/pdf/path-group/create", data=data
-        )
+        response = self._make_request("POST", "/pdf/path-group/create", data=data)
         self._invalidate_snapshots()
         return PathGroupInfo.from_dict(response.json())
 
     def _move_path_group(self, page_index, group_id, x, y):
         data = {
-            "pageIndex": page_index, "groupId": group_id,
-            "x": x, "y": y,
+            "pageIndex": page_index,
+            "groupId": group_id,
+            "x": x,
+            "y": y,
         }
         response = self._make_request("PUT", "/pdf/path-group/move", data=data)
         self._invalidate_snapshots()
@@ -2526,13 +2559,12 @@ class PDFDancer:
 
     def _transform_path_group(self, page_index, group_id, transform_type, **kwargs):
         data = {
-            "pageIndex": page_index, "groupId": group_id,
+            "pageIndex": page_index,
+            "groupId": group_id,
             "transformType": transform_type,
         }
         data.update({k: v for k, v in kwargs.items() if v is not None})
-        response = self._make_request(
-            "PUT", "/pdf/path-group/transform", data=data
-        )
+        response = self._make_request("PUT", "/pdf/path-group/transform", data=data)
         self._invalidate_snapshots()
         return response.json()
 
@@ -2552,15 +2584,16 @@ class PDFDancer:
         if width <= 0 or height <= 0:
             raise ValidationException("Width and height must be positive")
         return self._transform_path_group(
-            page_index, group_id, "RESIZE",
-            targetWidth=width, targetHeight=height,
+            page_index,
+            group_id,
+            "RESIZE",
+            targetWidth=width,
+            targetHeight=height,
         )
 
     def _remove_path_group(self, page_index, group_id):
         data = {"pageIndex": page_index, "groupId": group_id}
-        response = self._make_request(
-            "DELETE", "/pdf/path-group/remove", data=data
-        )
+        response = self._make_request("DELETE", "/pdf/path-group/remove", data=data)
         self._invalidate_snapshots()
         return response.json()
 
@@ -2568,12 +2601,52 @@ class PDFDancer:
         from .models import PathGroupInfo
         from .types import PathGroupObject
 
-        response = self._make_request(
-            "GET", f"/pdf/page/{page_index}/path-groups"
-        )
+        response = self._make_request("GET", f"/pdf/page/{page_index}/path-groups")
         infos = [PathGroupInfo.from_dict(d) for d in response.json()]
         return [PathGroupObject(self, page_index, info) for info in infos]
 
+    def clear_path_group_clipping(self, page_number: int, group_id: str) -> bool:
+        """
+        Clear clipping for a grouped set of paths.
+
+        Args:
+            page_number: 1-based page number containing the path group
+            group_id: Identifier returned by `group_paths(...)`
+
+        Returns:
+            True when the server cleared clipping successfully
+        """
+        return self._clear_path_group_clipping(page_number, group_id)
+
+    def _clear_path_group_clipping(self, page_number: int, group_id: str) -> bool:
+        """
+        Internal helper to clear clipping from a path group using the v1 API.
+        """
+        if page_number is None:
+            raise ValidationException("page_number cannot be null")
+        if not isinstance(page_number, int):
+            raise ValidationException(
+                f"page_number must be an integer, got {type(page_number)}"
+            )
+        if page_number < 1:
+            raise ValidationException(
+                f"page_number must be >= 1 (1-based indexing), got {page_number}"
+            )
+        if group_id is None or not str(group_id).strip():
+            raise ValidationException("group_id cannot be null or empty")
+
+        response = self._make_request(
+            "PUT",
+            "/pdf/path-group/clipping/clear",
+            data={"pageNumber": page_number, "groupId": str(group_id).strip()},
+        )
+        result = bool(response.json())
+
+        if result:
+            self._invalidate_snapshots()
+
+        return result
+
     def new_paragraph(self) -> ParagraphBuilder:
         return ParagraphBuilder(self)
 

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.12}/src/pdfdancer/types.py

@@ -65,6 +65,10 @@ class PDFObjectBase:
             Position.at_page_coordinates(self.position.page_number, x, y),
         )
 
+    def clear_clipping(self) -> bool:
+        """Detach any active clipping path from this object."""
+        return self._client.clear_clipping(self.object_ref())
+
     def redact(self, replacement: str = "[REDACTED]") -> bool:
         """Redact this object from the PDF document."""
         from .models import RedactTarget
@@ -329,21 +333,22 @@ class PathGroupObject:
         return True
 
     def rotate(self, degrees: float) -> bool:
-        self._client._rotate_path_group(
-            self._page_index, self.group_id, degrees
-        )
+        self._client._rotate_path_group(self._page_index, self.group_id, degrees)
         return True
 
     def resize(self, width: float, height: float) -> bool:
-        self._client._resize_path_group(
-            self._page_index, self.group_id, width, height
-        )
+        self._client._resize_path_group(self._page_index, self.group_id, width, height)
         return True
 
     def remove(self) -> bool:
         self._client._remove_path_group(self._page_index, self.group_id)
         return True
 
+    def clear_clipping(self) -> bool:
+        return self._client.clear_path_group_clipping(
+            self._page_index + 1, self.group_id
+        )
+
     def __repr__(self):
         return f"PathGroupObject(group_id={self.group_id!r}, path_count={self.path_count}, page_index={self._page_index})"
 

{pdfdancer_client_python-0.3.11 → pdfdancer_client_python-0.3.12}/src/pdfdancer_client_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.11
+Version: 0.3.12
 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.12}/src/pdfdancer_client_python.egg-info/SOURCES.txt

@@ -1,5 +1,7 @@
+.api-url
 .flake8
 .gitignore
+.gitmodules
 CLAUDE.md
 LICENSE
 NOTICE
@@ -9,14 +11,13 @@ check.py
 pyproject.toml
 release.py
 test.sh
-update-api-spec.sh
 .claude/commands/discuss.md
 .claude/commands/implement-new-api-features.md
 .github/workflows/ci.yml
 .github/workflows/daily-tests.yml
 .github/workflows/release.yml
-docs/api-schemas/v0.yml
-docs/api-schemas/v1.yml
+docs/capabilities/.gitkeep
+docs/capabilities/CLEAR_CLIPPING.md
 media/logo-orange-512h.webp
 media/logo-orange-60h.webp
 media/logo-silver-512h.webp
@@ -51,6 +52,7 @@ tests/e2e/__init__.py
 tests/e2e/pdf_assertions.py
 tests/e2e/test_acroform.py
 tests/e2e/test_bezier_builder.py
+tests/e2e/test_clipping.py
 tests/e2e/test_context_manager.py
 tests/e2e/test_form_x_objects.py
 tests/e2e/test_image.py
@@ -74,11 +76,14 @@ tests/e2e/test_snapshot.py
 tests/e2e/test_template_replace.py
 tests/e2e/test_template_replace_linebreak.py
 tests/e2e/test_text_line_edit.py
+tests/fixtures/Asimovian-Regular.ttf
 tests/fixtures/DancingScript-Regular.ttf
 tests/fixtures/Empty.pdf
 tests/fixtures/JetBrainsMono-Regular.ttf
+tests/fixtures/Roboto-Regular.ttf
 tests/fixtures/Showcase.pdf
 tests/fixtures/basic-paths.pdf
 tests/fixtures/form-xobject-example.pdf
+tests/fixtures/invisible-content-clipping-test.pdf
 tests/fixtures/logo-80.png
 tests/fixtures/mixed-form-types.pdf