Repository navigation
PDFCLOUD-6575 Add PDF page box updates - #61
Draft
datalogics-tsmith wants to merge 6 commits into
Draft
datalogics-tsmith wants to merge 6 commits into
datalogics-tsmith wants to merge 6 commits into
Conversation
- Add typed MediaBox and inset page-box definitions for selected pages. - Validate finite margins, ascending ranges, and overlapping selections. - Serialize uploaded PDF IDs and box definitions for the service contract. Assisted-by: Codex
- Add synchronous and asynchronous helpers for uploaded PDF resources. - Accept typed box definitions, output names, and request customization. - Delegate payload validation and serialization to the page-box model. Assisted-by: Codex
- Verify exact payload serialization and every supported page selector. - Exercise sync and async calls, customization, and response mapping. - Reject invalid margins, resources, ranges, and overlapping selections. Assisted-by: Codex
- Exercise every page-box type through synchronous and async clients. - Assert exact geometry, selector targeting, and positive boundaries. - Verify service rejection of invalid, descending, and overlapping input. Assisted-by: Codex
- Add a standalone upload example using typed MediaBox and CropBox input. - Print generated PDF metadata so users and CI can confirm success. - List the page-box workflow in the runnable example inventory. Assisted-by: Codex
- Link the page geometry helper from the cleanup and normalization guide. - List typed MediaBox, CropBox, BleedBox, TrimBox, and ArtBox support. Assisted-by: Codex
datalogics-tsmith
temporarily deployed
to
ci-live
November 4, 2026 21:36 — with 
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 4, 2026 21:36 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 4, 2026 21:36 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 4, 2026 21:36 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 4, 2026 21:36 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
datalogics-tsmith
temporarily deployed
to
ci-live
November 4, 2026 21:36 — with
GitHub Actions
Inactive
GitHub Actions
Inactive
This branch was previously 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-6575
Why this change
The Python SDK does not currently provide a typed way to update PDF page boundary boxes. Callers would otherwise need to reproduce the service's nested JSON-string payload, page-selection rules, and different MediaBox versus inset-box margin requirements themselves.
This draft is stacked on #60, which is itself based on #57 and #58. Those pull requests should merge before this one is made ready for final review.
What changed
This adds public discriminated input types for MediaBox, CropBox, BleedBox, TrimBox, and ArtBox updates. A Pydantic payload model validates and serializes those definitions, while thin synchronous and asynchronous client helpers delegate request execution through the existing file-operation path.
The implementation keeps signed MediaBox margins separate from strictly positive inset-box margins. It also models page selection symbolically so overlapping selections for the same box type can be rejected before transport without preventing different box types from targeting the same page.
Behavior changes
Callers can now pass an uploaded PDF and typed page-box definitions to
set_pdf_page_boxes. Supported selections include positive page numbers, ascending ranges, ranges ending inlast, and theall,even, andoddselectors.Invalid ranges use the service's concise error wording. Non-finite margins, non-positive inset margins, unsupported resources, and overlapping selections for the same box are rejected locally. MediaBox margins remain signed so pages can be enlarged.
This is an additive API change and does not intentionally break existing callers.
Validation
The Python 3.10-3.14 Nox matrix passed with 3,397 tests and 10 expected skips on each interpreter. Total coverage was 96%, and the client-class function coverage gate remained above 90%.
The endpoint-specific unit module passed 106 tests. The live module passed 26 tests through both clients, asserting exact geometry for all five box types, page-number/range/even/odd targeting, the positive inset boundary, and service rejection of invalid, descending, and overlapping selections.
Ruff, basedpyright, changed-file pre-commit hooks, strict documentation builds, package builds, and the standalone live example also passed. The complete live-service catalog and complete examples matrix were not rerun because validation was focused on this endpoint and example.
Risks and follow-ups
The current test service accepts zero and negative inset margins when local validation is bypassed with a raw body override, despite the published contract requiring values greater than zero. The SDK follows the published contract and rejects those values locally; service-side enforcement remains a follow-up.
After #57, #58, and #60 merge, this pull request should be updated onto
mainand reviewed again for conflicts introduced by the stacked changes.