Skip to content

PDFCLOUD-6573 Add TDM reservation policy support - #60

Open
datalogics-tsmith wants to merge 4 commits into
mainfrom
pdfcloud-6573-add-tdm-reservation-policy-support
Open

datalogics-tsmith wants to merge 4 commits into
mainfrom
pdfcloud-6573-add-tdm-reservation-policy-support

Conversation

@datalogics-tsmith

@datalogics-tsmith datalogics-tsmith commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

PDFCLOUD-6573

Dependency status: PRs #57 and #58 are merged. This branch has been rebased onto the resulting current main, so the diff now contains only the TDM reservation feature and its 1.7.0 release metadata.

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_reservation helpers 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.0 to 1.7.0 for 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-diff confirmed that the client, tests, and documentation commits are patch-equivalent to the original PR. The obsolete 1.5.0 version commit was replaced with a 1.7.0 bump because merged main is now at 1.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 --check also passed. The repository-wide live suite was not rerun locally because PDFREST_API_KEY is 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.

@netlify

netlify Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for pdfrest-python ready!

Name Link
🔨 Latest commit f6d9d71
🔍 Latest deploy log https://app.netlify.com/projects/pdfrest-python/deploys/6af77e4a4556566702bef9f9
😎 Deploy Preview https://deploy-preview-60--pdfrest-python.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

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

@datalogics-kam datalogics-kam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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 datalogics-kam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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",
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

Policy: TESTING_GUIDELINES.md, Response Verification.

if output_name is not None:
assert output_file.name.startswith(output_name)
else:
assert output_file.name.endswith(".pdf")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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.

This branch was previously deployed

1 inactive deployment
ci-live — f6d9d717 Deployed Nov 13, 2026 by datalogics-tsmith via Examples (Python 3.14) #629
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants