Repository navigation
PDFCLOUD-6577 Expand image overlay options - #63
Draft
datalogics-tsmith wants to merge 3 commits into
Draft
datalogics-tsmith wants to merge 3 commits into
datalogics-tsmith wants to merge 3 commits into
Conversation
- Add typed single- and multi-image placement controls for synchronous and asynchronous clients. - Validate uploaded formats, page selections, dimensions, and accessibility metadata before requests are sent. - Cover serialization, customization, boundaries, MIME formats, and live service behavior. Assisted-by: Codex
- Add a standalone typed-placement example with checked-in PNG and JPEG resources. - Link the expanded image workflow from the examples inventory and API guide. Assisted-by: Codex
datalogics-tsmith
had a problem deploying
to
ci-live
November 6, 2026 16:52 — with 
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-tsmith
temporarily deployed
to
ci-live
November 6, 2026 16:52 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 6, 2026 16:52 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 6, 2026 16:52 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 6, 2026 16:52 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 6, 2026 16:52 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
- Mark Ruby and Warichu image-overlay cases as strict expected failures for the deployed service's fatal 400 response. - Fail on unexpected success so CI exposes when service support is restored. Assisted-by: Codex
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PDFCLOUD-6577
Why this change
The image-overlay service supports sizing, repeated or multiple image placements, and accessibility metadata, but the Python client only exposed a single basic placement. Users need a typed way to use the full service contract while catching invalid file formats, page selectors, dimensions, and tagging combinations before a request is sent.
What changed (high level)
The existing
add_image_to_pdfhelper remains the concise single-placement API and now accepts optional sizing and accessibility fields. A separateadd_images_to_pdfhelper handles one or more typedPdfAddImageObjectplacements without exposing mode-dependent arguments on the simpler helper. Shared Pydantic payload models serialize uploaded resources to their server IDs and enforce the endpoint contract for both synchronous and asynchronous clients.The public type surface now includes the placement object and documented content-structure values. A standalone example demonstrates multiple uploaded images, image reuse, sizing, page selection, and accessibility metadata.
Behavior changes
Image placements now support JPEG, PNG, TIFF, and GIF uploads, positive finite width and height values, page expressions, and semantic tag metadata. Batch placement coordinates must be non-negative, image resources are limited to one per placement, and tag metadata requires tagging to be enabled. Invalid combinations fail locally with Pydantic validation errors instead of reaching the service.
This is additive and does not remove the existing single-image workflow.
Validation
uv run pre-commit run --all-filesuv run pytest -n auto --maxschedchunk 2 -m 'not live'— 3,569 passed, 10 skippeduvx nox -s tests -- -m 'not live'— Python 3.10 through 3.14 passeduv run mkdocs build --strictRubyandWarichuresponsesThe API-backed live suite could not be rerun locally because
PDFREST_API_KEYwas not available in the validation environment. The focused live cases forRubyandWarichuare strict expected failures limited toPdfRestApiError, so CI will fail with an unexpected success when the deployed behavior is corrected.Risks and follow-ups
This draft is stacked directly on #62 and should remain a draft until the preceding pull requests are merged. Once the stack lands, its base can be changed to
mainif GitHub does not retarget it automatically.The Cloud OpenAPI schema and request validator list
RubyandWarichuas accepted structure types, while the deployed image-overlay operation currently rejects them with a fatal HTTP 400 response. The SDK retains the documented type contract, and the live suite tracks those two values as strict expected failures for both transports. Remove those markers when the service supports standalone image content with those structure elements.