Repository navigation
PDFCLOUD-6573 Add TDM reservation policy support - #60
datalogics-tsmith wants to merge 4 commits into
Conversation
✅ Deploy Preview for pdfrest-python ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
- Add synchronous and asynchronous helpers for uploaded PDF resources. - Validate HTTP and HTTPS policy URLs without changing valid values. - Cover serialization, customization, validation, and response mapping. Assisted-by: Codex
- Exercise default and custom output names through both client transports. - Inspect generated PDF metadata and server-side policy rejection. Assisted-by: Codex
- Link the helper and explain URL-based reservation metadata behavior. - Add a runnable upload example and list it in the example inventory. Assisted-by: Codex
- Mark the additive TDM helper for the next minor feature release. - Keep the project lock metadata synchronized. Assisted-by: Codex
a92ce61 to
f6d9d71
Compare
datalogics-kam
left a comment
There was a problem hiding this comment.
Please make policy URL validation strict and add regression coverage before merging. Malformed URLs currently pass local validation and are serialized unchanged. Valid URLs must continue to be sent exactly as supplied.
Validation: the offline suite passed locally (3,500 passed, 10 skipped), the 29 focused TDM tests passed, and Ruff, basedpyright, and diff checks passed. A direct reproduction confirmed that strict=True rejects the malformed separator forms that the current adapter call accepts.
| ): | ||
| raise ValueError(message) | ||
| try: | ||
| _ = _HTTP_URL_ADAPTER.validate_python(value) |
There was a problem hiding this comment.
[P2] Reject malformed URLs with strict parsing
validate_python(value) accepts https:/example.com/policy, https:example.com/policy, and https:///example.com/policy by repairing the separators internally. Because the validator returns the original string, those malformed values still reach the API unchanged. Please call validate_python(value, strict=True) and continue returning the original value so valid policy URLs are never rewritten.
Please add parametrized regression tests for all three malformed forms through distinct sync and async client tests, using a fail-if-called transport to prove rejection before any HTTP request. Also test that valid URLs (including a bare origin and an encoded path/query/fragment) serialize exactly as supplied. Retain the existing whitespace, backslash, and malformed-percent checks.
datalogics-kam
left a comment
There was a problem hiding this comment.
Please complete the remaining TDM endpoint test coverage before merging: output validation boundaries, matching sync/async whitespace cases, complete unit response assertions, and concrete default filenames in live tests. The inline comments identify the missing cases and applicable repository testing rules.
This is a separate testing-focused follow-up to the existing review.
Validation at this head: the non-live Python 3.10–3.14 matrix passed with 3,500 passed and 10 expected skips per interpreter; the focused TDM unit suite passed all 29 cases, the focused live suite passed all six cases, and the standalone example passed. These requests concern missing regression coverage despite those passing checks.
| "file": input_file, | ||
| "policy": policy, | ||
| "output": "tdm-reserved", | ||
| } |
There was a problem hiding this comment.
[P3] Add output validation cases through both clients
The new payload constrains output to a non-empty safe filename, but this module only supplies valid output names. Please add parameterized direct-payload tests and distinct sync/async client tests for empty names, directory components, reserved names (profile.json/metadata.json), leading dots, and invalid characters, plus the shortest valid name. Use a fail-if-called transport for client rejection cases so they prove validation happens before HTTP. The existing graphic payload validation suite does not include PdfTdmReservationPayload, so it does not protect this new field's wiring.
Policy: TESTING_GUIDELINES.md, Validation & Payload Modeling and explicit constraint boundaries.
| pytest.param( | ||
| "https://example.com/tdm policy", | ||
| "Must be a valid HTTP or HTTPS URL", | ||
| id="embedded-whitespace", |
There was a problem hiding this comment.
[P3] Exercise both whitespace failures through each transport
The async invalid-policy cases test embedded whitespace, while the sync cases test surrounding whitespace. Each scenario currently runs through only one public client. Please parameterize both surrounding and embedded whitespace in the distinct sync and async tests, retaining their fail-if-called transports.
Policy: TESTING_GUIDELINES.md, distinct sync/async tests for every scenario and AGENTS.md, independently verifiable assertions through both clients.
| assert response.output_file.name == "report_pdfrest_tdm_reserved_pdf.pdf" | ||
| assert response.output_file.type == "application/pdf" | ||
| assert response.output_file.size > 0 | ||
| assert response.warning is None |
There was a problem hiding this comment.
[P3] Assert the complete mapped output response
The sync success assertions here, and the corresponding async assertions at lines 207–214, omit the output URL and exact output_files count. Please assert that exactly one output resource is returned and that its URL matches the mocked file-info response through each client. This catches response-mapping regressions that name/type/size assertions alone would miss.
| if output_name is not None: | ||
| assert output_file.name.startswith(output_name) | ||
| else: | ||
| assert output_file.name.endswith(".pdf") |
There was a problem hiding this comment.
[P3] Assert the deterministic default output filename
For the checked-in report.pdf, the default-output branch only checks that the name ends in .pdf; any incorrect basename or suffix would pass. Please assert the concrete default name report_pdfrest_tdm_reserved_pdf.pdf here and in the matching async branch at line 110. Keep the custom-output prefix assertions for their separate cases.
Policy: TESTING_GUIDELINES.md, concrete assertions for deterministic live fixtures and AGENTS.md.
PDFCLOUD-6573
Why this change
The Python SDK does not expose pdfRest's TDM reservation operation, so callers cannot use the typed clients to embed a hosted text-and-data-mining policy URL in an uploaded PDF. This adds a supported workflow for applying that compliance metadata without requiring callers to assemble raw requests.
What changed (high level)
New synchronous and asynchronous
apply_tdm_reservationhelpers accept one uploaded PDF, an HTTP or HTTPS policy URL, and an optional output name. A dedicated Pydantic payload model owns MIME, cardinality, output-prefix, and URL validation while preserving valid policy URLs exactly in the serialized request. The SDK validates syntax only; it does not fetch or inspect the policy destination.The change also adds focused unit and live coverage, a runnable example, API guidance, and a package version bump from
1.6.0to1.7.0for the additive public helper.Behavior changes
Callers can apply TDM reservation metadata through either client transport and receive the standard typed file response. Missing or empty policies, bare policy text, unsupported schemes, whitespace, malformed percent escapes, backslashes, non-PDF resources, empty resource lists, and multiple resources fail locally before transport. Valid encoded paths, query strings, and fragments are preserved rather than normalized.
The API is additive and does not change existing helper behavior.
Validation
After rebasing,
git range-diffconfirmed that the client, tests, and documentation commits are patch-equivalent to the original PR. The obsolete1.5.0version commit was replaced with a1.7.0bump because mergedmainis now at1.6.0.The complete offline suite passed locally with 3,500 tests passed and 10 expected skips. Ruff formatting and linting, basedpyright, and
git diff --checkalso passed. The repository-wide live suite was not rerun locally becausePDFREST_API_KEYis not configured; the focused endpoint live suite and standalone example passed before the rebase, and main-repository CI is rerunning the full Python, live, example, pre-commit, and documentation matrices on the rebased branch.Risks and follow-ups
The current service/OpenAPI contract still describes any non-empty policy string as accepted, while this SDK helper intentionally requires a valid HTTP or HTTPS URL. Coordinate the service and documentation rollout before releasing the SDK so users see one consistent contract.
No breaking changes are expected. Main-repository CI provides the final clean-environment verification before the draft is marked ready.