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

pdfdancer_client_python-0.3.11/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Create virtual environment
+        run: python -m venv venv
+
+      - name: Install dependencies
+        run: |
+          venv/bin/pip install --upgrade pip
+          venv/bin/pip install -e ".[dev]"
+
+      - name: Run linter
+        run: venv/bin/python -m flake8 src/
+
+      - name: Run tests
+        run: venv/bin/python -m pytest tests/ -v --maxfail=1 --ignore=tests/e2e/test_pdfdancer.py
+        env:
+          PDFDANCER_BASE_URL: https://api.pdfdancer.com
+          PDFDANCER_API_TOKEN: ${{ secrets.PDFDANCER_API_TOKEN_PRODUCTION }}
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(python -c "import re; print(re.search(r'version\s*=\s*\"([^\"]+)\"', open('pyproject.toml').read()).group(1))")
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match pyproject.toml version ($PKG_VERSION)"
+            exit 1
+          fi
+          echo "Version verified: $TAG_VERSION"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release
+        run: gh release create "$GITHUB_REF_NAME" --generate-notes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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

@@ -18,3 +18,4 @@ __pycache__/
 .Python
 /.run/
 /build
+.env

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pdfdancer-client-python
-Version: 0.3.9
+Version: 0.3.11
 Summary: Python client for PDFDancer API
 Author-email: "The Famous Cat Ltd." <hi@thefamouscat.com>
 License: 
@@ -210,7 +210,7 @@ Project-URL: Homepage, https://www.pdfdancer.com/
 Project-URL: Documentation, https://www.pdfdancer.com/
 Project-URL: Source, https://github.com/MenschMachine/pdfdancer-client-python
 Project-URL: Issues, https://github.com/MenschMachine/pdfdancer-client-python/issues
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.10
@@ -571,15 +571,16 @@ Artifacts will be created in the `dist/` directory.
 
 #### Publishing to PyPI
 
-```bash
-# Test upload to TestPyPI (recommended first)
-python -m twine upload --repository testpypi dist/*
+Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub (via GitHub Actions with Trusted Publishers).
 
-# Upload to PyPI
-python -m twine upload dist/*
+```bash
+# Set version, commit, and push tag — GitHub Actions handles the rest
+python release.py tag --version 1.1.0
 
-# Or use the release script
-python release.py
+# Or manually:
+# 1. Update version in pyproject.toml and src/pdfdancer/__init__.py
+# 2. Commit
+# 3. git tag v1.1.0 && git push origin HEAD && git push origin v1.1.0
 ```
 
 #### Code Quality
@@ -672,6 +673,7 @@ Contributions are welcome via pull request. Please:
 - [PyPI](https://pypi.org/project/pdfdancer-client-python/)
 - [Changelog](https://www.pdfdancer.com/changelog/?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
 - [Status](https://status.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
+- [Issue tracker](https://github.com/MenschMachine/pdfdancer)
 
 ## Related SDKs
 

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

@@ -332,15 +332,16 @@ Artifacts will be created in the `dist/` directory.
 
 #### Publishing to PyPI
 
-```bash
-# Test upload to TestPyPI (recommended first)
-python -m twine upload --repository testpypi dist/*
+Releases are published automatically to PyPI when a `v*` tag is pushed to GitHub (via GitHub Actions with Trusted Publishers).
 
-# Upload to PyPI
-python -m twine upload dist/*
+```bash
+# Set version, commit, and push tag — GitHub Actions handles the rest
+python release.py tag --version 1.1.0
 
-# Or use the release script
-python release.py
+# Or manually:
+# 1. Update version in pyproject.toml and src/pdfdancer/__init__.py
+# 2. Commit
+# 3. git tag v1.1.0 && git push origin HEAD && git push origin v1.1.0
 ```
 
 #### Code Quality
@@ -433,6 +434,7 @@ Contributions are welcome via pull request. Please:
 - [PyPI](https://pypi.org/project/pdfdancer-client-python/)
 - [Changelog](https://www.pdfdancer.com/changelog/?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
 - [Status](https://status.pdfdancer.com?utm_source=github&utm_medium=readme&utm_campaign=pdfdancer-python)
+- [Issue tracker](https://github.com/MenschMachine/pdfdancer)
 
 ## Related SDKs
 

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pdfdancer-client-python"
-version = "0.3.9"
+version = "0.3.11"
 description = "Python client for PDFDancer API"
 readme = "README.md"
 authors = [
@@ -12,7 +12,7 @@ authors = [
 ]
 license = { file = "LICENSE" }
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3.10",

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.11}/release.py

@@ -20,10 +20,12 @@ class ReleaseError(Exception):
 
 
 class VersionBumper:
-    """Handles version bumping in pyproject.toml."""
+    """Handles version bumping in pyproject.toml and __init__.py."""
 
-    def __init__(self, pyproject_path: Path = Path("pyproject.toml")):
+    def __init__(self, pyproject_path: Path = Path("pyproject.toml"),
+                 init_path: Path = Path("src/pdfdancer/__init__.py")):
         self.pyproject_path = pyproject_path
+        self.init_path = init_path
         if not self.pyproject_path.exists():
             raise ReleaseError(f"pyproject.toml not found at {pyproject_path}")
 
@@ -36,7 +38,8 @@ class VersionBumper:
         return match.group(1)
 
     def set_version(self, new_version: str) -> None:
-        """Set a new version in pyproject.toml."""
+        """Set a new version in pyproject.toml and __init__.py."""
+        # Update pyproject.toml
         content = self.pyproject_path.read_text()
         new_content = re.sub(
             r'^version\s*=\s*"[^"]+"',
@@ -48,6 +51,18 @@ class VersionBumper:
             raise ReleaseError("Failed to update version in pyproject.toml")
         self.pyproject_path.write_text(new_content)
 
+        # Update __init__.py
+        if self.init_path.exists():
+            init_content = self.init_path.read_text()
+            new_init = re.sub(
+                r'^__version__\s*=\s*"[^"]+"',
+                f'__version__ = "{new_version}"',
+                init_content,
+                flags=re.MULTILINE
+            )
+            self.init_path.write_text(new_init)
+            print(f"Updated {self.init_path} to {new_version}")
+
     def bump_version(self, bump_type: str) -> str:
         """Bump version by type (major, minor, patch)."""
         current = self.get_current_version()
@@ -159,8 +174,8 @@ def main():
     parser = argparse.ArgumentParser(description="PDFDancer Python Client Release Tool")
     parser.add_argument(
         "action",
-        choices=["bump", "upload", "release"],
-        help="Action to perform: bump (version only), upload (build+upload), release (bump+test+build+upload)"
+        choices=["bump", "upload", "release", "tag"],
+        help="Action to perform: bump (version only), upload (build+upload), release (bump+test+build+upload), tag (set version + commit + push tag)"
     )
     parser.add_argument(
         "--bump-type",
@@ -230,6 +245,37 @@ def main():
 
             print(f"New version: {new_version}")
 
+        if args.action == "tag":
+            if not args.version:
+                raise ReleaseError("--version is required for the tag action")
+
+            new_version = args.version
+            current_version = version_bumper.get_current_version()
+            print(f"Current version: {current_version}")
+
+            if not args.dry_run:
+                version_bumper.set_version(new_version)
+                print(f"Version set to {new_version}")
+
+                # Commit the version bump
+                uploader.run_command(
+                    ["git", "add", "pyproject.toml", "src/pdfdancer/__init__.py"]
+                )
+                uploader.run_command(
+                    ["git", "commit", "-m", f"release: v{new_version}"]
+                )
+                print(f"Committed version bump")
+
+                # Create and push tag
+                tag_name = f"v{new_version}"
+                uploader.run_command(["git", "tag", tag_name])
+                uploader.run_command(["git", "push", "origin", "HEAD"])
+                uploader.run_command(["git", "push", "origin", tag_name])
+                print(f"Pushed tag {tag_name}")
+            else:
+                print(f"Would set version to {new_version}")
+                print(f"Would commit and push tag v{new_version}")
+
         if args.action in ["upload", "release"]:
             if args.action == "release" and not args.skip_tests:
                 if not args.dry_run:

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

@@ -12,6 +12,7 @@ from .exceptions import (
     PdfDancerException,
     RateLimitException,
     SessionException,
+    SessionNotFoundException,
     ValidationException,
 )
 from .models import (
@@ -34,6 +35,7 @@ from .models import (
     PageSize,
     Paragraph,
     Path,
+    PathGroupInfo,
     PathSegment,
     Point,
     Position,
@@ -47,12 +49,13 @@ from .models import (
     TextObjectRef,
     TextStatus,
 )
+from .types import PathGroupObject
 from .page_builder import PageBuilder
 from .paragraph_builder import ParagraphBuilder
 from .path_builder import BezierBuilder, LineBuilder, PathBuilder
 from .text_line_builder import TextLineBuilder
 
-__version__ = "1.0.0"
+__version__ = "0.3.11"
 __all__ = [
     "PDFDancer",
     "ParagraphBuilder",
@@ -89,6 +92,8 @@ __all__ = [
     "Line",
     "Bezier",
     "Path",
+    "PathGroupInfo",
+    "PathGroupObject",
     "RedactTarget",
     "RedactResponse",
     "ReflowPreset",
@@ -97,6 +102,7 @@ __all__ = [
     "ValidationException",
     "HttpClientException",
     "SessionException",
+    "SessionNotFoundException",
     "RateLimitException",
     "set_ssl_verify",
 ]

{pdfdancer_client_python-0.3.9 → pdfdancer_client_python-0.3.11}/src/pdfdancer/exceptions.py

@@ -55,6 +55,15 @@ class SessionException(PdfDancerException):
     pass
 
 
+class SessionNotFoundException(SessionException):
+    """
+    Exception raised when a session is not found (expired or invalid).
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
 class ValidationException(PdfDancerException):
     """
     Exception raised for input validation errors.

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

@@ -1643,6 +1643,25 @@ class Size:
         return {"width": self.width, "height": self.height}
 
 
+@dataclass
+class PathGroupInfo:
+    group_id: str
+    path_count: int
+    bounding_box: Optional[Dict[str, Any]]
+    x: float
+    y: float
+
+    @staticmethod
+    def from_dict(d: Dict[str, Any]) -> "PathGroupInfo":
+        return PathGroupInfo(
+            group_id=d.get("groupId", ""),
+            path_count=d.get("pathCount", 0),
+            bounding_box=d.get("boundingBox"),
+            x=d.get("x", 0.0),
+            y=d.get("y", 0.0),
+        )
+
+
 class ImageTransformType(Enum):
     """Type of image transformation operation."""
 
@@ -1686,18 +1705,22 @@ class TemplateReplacement:
 
     Parameters:
     - placeholder: The exact text to find and replace in the PDF.
-    - text: The text to replace the placeholder with.
+    - text: The text to replace the placeholder with. None for image replacements.
     - font: Optional font for the replacement text.
     - color: Optional color for the replacement text.
+    - image: Optional Image to replace the placeholder with. When set, text should be None.
     """
 
     placeholder: str
-    text: str
+    text: Optional[str] = None
     font: Optional[Font] = None
     color: Optional[Color] = None
+    image: Optional[Image] = None
 
     def to_dict(self) -> dict:
         """Convert to dictionary for JSON serialization."""
+        import base64
+
         result: Dict[str, Any] = {
             "placeholder": self.placeholder,
             "text": self.text,
@@ -1711,6 +1734,20 @@ class TemplateReplacement:
                 "blue": self.color.b,
                 "alpha": self.color.a,
             }
+        if self.image:
+            image_dict: Dict[str, Any] = {}
+            if self.image.data:
+                image_dict["data"] = base64.b64encode(self.image.data).decode("utf-8")
+            if self.image.format:
+                image_dict["format"] = self.image.format
+            if self.image.width is not None or self.image.height is not None:
+                size: Dict[str, float] = {}
+                if self.image.width is not None:
+                    size["width"] = self.image.width
+                if self.image.height is not None:
+                    size["height"] = self.image.height
+                image_dict["size"] = size
+            result["image"] = image_dict
         return result
 
 

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

@@ -19,7 +19,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, BinaryIO, Dict, List, Mapping, Optional, Union
 
 import httpx
-from dotenv import load_dotenv
+from dotenv import find_dotenv, load_dotenv
 
 from . import BezierBuilder, LineBuilder, ParagraphBuilder, PathBuilder
 from .exceptions import (
@@ -28,6 +28,7 @@ from .exceptions import (
     PdfDancerException,
     RateLimitException,
     SessionException,
+    SessionNotFoundException,
     ValidationException,
 )
 from .fingerprint import Fingerprint
@@ -85,7 +86,16 @@ if TYPE_CHECKING:
     from .models import ImageTransformRequest, PathSegment
     from .path_builder import RectangleBuilder
 
-load_dotenv()
+_env_loaded = False
+
+
+def _load_env():
+    global _env_loaded
+    if _env_loaded:
+        return
+    load_dotenv(find_dotenv(usecwd=True))
+    _env_loaded = True
+
 
 # Client identifier header for all HTTP requests
 # Always reads from installed package metadata (stays in sync with pyproject.toml)
@@ -131,6 +141,34 @@ def _dict_to_replacements(
     for placeholder, value in replacements.items():
         if isinstance(value, str):
             result.append(TemplateReplacement(placeholder=placeholder, text=value))
+        elif "image" in value:
+            image_source = value["image"]
+            if isinstance(image_source, Path):
+                image_data = image_source.read_bytes()
+                image_format = image_source.suffix.lstrip(".").upper()
+                if image_format == "JPG":
+                    image_format = "JPEG"
+            elif isinstance(image_source, bytes):
+                image_data = image_source
+                image_format = None
+            else:
+                raise ValueError(
+                    f"Unsupported image source type: {type(image_source)}. "
+                    "Use a Path or bytes."
+                )
+            img = Image(
+                data=image_data,
+                format=value.get("format", image_format),
+                width=value.get("width"),
+                height=value.get("height"),
+            )
+            result.append(
+                TemplateReplacement(
+                    placeholder=placeholder,
+                    text=None,
+                    image=img,
+                )
+            )
         else:
             result.append(
                 TemplateReplacement(
@@ -644,6 +682,8 @@ class PageClient:
             replacements: Dict mapping placeholder strings to replacement values.
                 - Simple: {"{{NAME}}": "John Doe"}
                 - With options: {"{{NAME}}": {"text": "John", "font": Font(...), "color": Color(...)}}
+                - With image: {"{{LOGO}}": {"image": Path("logo.png")}}
+                - With image and size: {"{{LOGO}}": {"image": Path("logo.png"), "width": 50, "height": 50}}
             reflow_preset: Optional ReflowPreset to control text reflow behavior.
                 - BEST_EFFORT: Attempt to reflow, proceed even if imperfect
                 - FIT_OR_FAIL: Reflow must succeed or operation fails
@@ -698,6 +738,28 @@ class PageClient:
             self.root._find_paths(Position.at_page(self.page_number))
         )
 
+    def group_paths(self, path_ids):
+        """Group paths by their IDs. Returns a PathGroupObject."""
+        from .types import PathGroupObject
+
+        page_index = self.page_number - 1
+        info = self.root._create_path_group(page_index, path_ids=path_ids)
+        return PathGroupObject(self.root, page_index, info)
+
+    def group_paths_in_region(self, region):
+        """Group paths within a bounding region. Returns a PathGroupObject."""
+        from .types import PathGroupObject
+
+        page_index = self.page_number - 1
+        info = self.root._create_path_group(page_index, region=region)
+        return PathGroupObject(self.root, page_index, info)
+
+    def get_path_groups(self):
+        """List all path groups on this page."""
+
+        page_index = self.page_number - 1
+        return self.root._list_path_groups(page_index)
+
     def select_elements(self):
         """
         Select all elements (paragraphs, images, paths, forms) on this page.
@@ -789,6 +851,7 @@ class PDFDancer:
 
     @classmethod
     def _resolve_base_url(cls, base_url: Optional[str]) -> Optional[str]:
+        _load_env()
         env_base_url = os.getenv("PDFDANCER_BASE_URL")
         resolved_base_url = base_url or (
             env_base_url.strip() if env_base_url and env_base_url.strip() else None
@@ -923,6 +986,7 @@ class PDFDancer:
         1. PDFDANCER_API_TOKEN (preferred)
         2. PDFDANCER_TOKEN (legacy)
         """
+        _load_env()
         resolved_token = token.strip() if token and token.strip() else None
         if resolved_token is None:
             # Check PDFDANCER_API_TOKEN first (preferred), then PDFDANCER_TOKEN (legacy)
@@ -1586,7 +1650,7 @@ class PDFDancer:
 
                 _log_generated_at_header(response, method, path)
 
-                # Handle FontNotFoundException
+                # Handle 404 errors
                 if response.status_code == 404:
                     try:
                         error_data = response.json()
@@ -1594,6 +1658,10 @@ class PDFDancer:
                             raise FontNotFoundException(
                                 error_data.get("message", "Font not found")
                             )
+                        if error_data.get("error") == "SessionNotFoundException":
+                            raise SessionNotFoundException(
+                                error_data.get("message", "Session not found")
+                            )
                     except (json.JSONDecodeError, KeyError):
                         pass
 
@@ -2281,6 +2349,8 @@ class PDFDancer:
             replacements: Dict mapping placeholder strings to replacement values.
                 - Simple: {"{{NAME}}": "John Doe"}
                 - With options: {"{{NAME}}": {"text": "John", "font": Font(...), "color": Color(...)}}
+                - With image: {"{{LOGO}}": {"image": Path("logo.png")}}
+                - With image and size: {"{{LOGO}}": {"image": Path("logo.png"), "width": 50, "height": 50}}
             reflow_preset: Optional ReflowPreset to control text reflow behavior.
                 - BEST_EFFORT: Attempt to reflow, proceed even if imperfect
                 - FIT_OR_FAIL: Reflow must succeed or operation fails
@@ -2423,6 +2493,87 @@ class PDFDancer:
 
         return result
 
+    # Path Group Operations (internal, 0-based page_index)
+    def _create_path_group(self, page_index, path_ids=None, region=None):
+        from .models import PathGroupInfo
+
+        if path_ids is not None:
+            if not isinstance(path_ids, list) or len(path_ids) == 0:
+                raise ValidationException("path_ids must be a non-empty list")
+
+        data = {"pageIndex": page_index}
+        if path_ids is not None:
+            data["pathIds"] = path_ids
+        if region is not None:
+            data["region"] = {
+                "x": region.x, "y": region.y,
+                "width": region.width, "height": region.height,
+            }
+        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,
+        }
+        response = self._make_request("PUT", "/pdf/path-group/move", data=data)
+        self._invalidate_snapshots()
+        return response.json()
+
+    def _transform_path_group(self, page_index, group_id, transform_type, **kwargs):
+        data = {
+            "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
+        )
+        self._invalidate_snapshots()
+        return response.json()
+
+    def _scale_path_group(self, page_index, group_id, factor):
+        if factor <= 0:
+            raise ValidationException("Scale factor must be positive")
+        return self._transform_path_group(
+            page_index, group_id, "SCALE", scaleFactor=factor
+        )
+
+    def _rotate_path_group(self, page_index, group_id, degrees):
+        return self._transform_path_group(
+            page_index, group_id, "ROTATE", rotationAngle=degrees
+        )
+
+    def _resize_path_group(self, page_index, group_id, width, height):
+        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,
+        )
+
+    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
+        )
+        self._invalidate_snapshots()
+        return response.json()
+
+    def _list_path_groups(self, page_index):
+        from .models import PathGroupInfo
+        from .types import PathGroupObject
+
+        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 new_paragraph(self) -> ParagraphBuilder:
         return ParagraphBuilder(self)