Repository navigation
PDFCLOUD-6572 Add ZUGFeRD PDF validation - #58
Conversation
- Add typed rendering options for invoice appearance and localization. - Validate uploaded resources, color channels, fonts, and regeneration. - Serialize the public input shape into the pdfRest wire contract. Assisted-by: Codex
- Add synchronous and asynchronous helpers for uploaded invoice XML. - Support optional PDFs, logos, rendering controls, and request options. - Cover serialization, validation, response mapping, and both transports. Assisted-by: Codex
- Exercise every closed rendering option through both client transports. - Verify regenerated PDFs, response metadata, and server-side rejection. - Add a deterministic minimum-profile invoice fixture. Assisted-by: Codex
- Add a standalone typed example with a deterministic invoice fixture. - Verify the generated PDF and print useful response metadata. - Link the helper from the API guide and example inventories. Assisted-by: Codex
- Compose page ranges from typed ascending selections and reject invalid combinations before transport. - Add deterministic sync and async annotation assertions with a printable PDF fixture. Assisted-by: Codex
- Validate a single uploaded PDF resource before request serialization. - Model validation findings and response status fields returned by pdfRest. - Export the public response models for typed client consumers. Assisted-by: Codex
- Send uploaded PDF resource IDs to the validation endpoint. - Return typed results from synchronous and asynchronous clients. - Preserve request customization and timeout support. Assisted-by: Codex
- Verify payload serialization and local resource validation. - Exercise response literals, aliases, findings, and demo redactions. - Assert sync and async request customization and transport behavior. Assisted-by: Codex
- Exercise valid and invalid validation requests through both clients. - Confirm created and regenerated invoices pass validation and PDF/A checks. - Accept confirmed and demo-redacted content comparison results. Assisted-by: Codex
- Create a deterministic invoice before validating its conformance. - Display typed status, PDF/A, content-match, and finding details. - Add the workflow to the runnable example inventory. Assisted-by: Codex
- Link the validation helper from the electronic invoice API guide. - Describe package, content, and PDF/A conformance validation. Assisted-by: Codex
✅ Deploy Preview for pdfrest-python ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
datalogics-kam
left a comment
There was a problem hiding this comment.
Reviewed only PR #58's incremental changes over PR #57 (7d951b6 to 02cb915), excluding the inherited creation implementation.
Requesting changes for the two inline test-coverage findings: add a real nonconforming-document validation case to the live suite, and make mocked response scenarios and assertions match across the synchronous and asynchronous clients. No runtime or CI regression was found.
Validation passed: 26 focused unit tests, 16 focused live tests, the Python 3.10–3.14 non-live Nox matrix (3,257 passed and 10 expected skips per interpreter), all class-coverage gates, Ruff formatting/lint, and basedpyright. Exploratory validation of the existing report.pdf fixture returned INVALID with pdfa=false through both clients; please preserve that behavior in regression tests.
datalogics-kam
left a comment
There was a problem hiding this comment.
Follow-up to the existing review, scoped to the validation changes over PR #57 at the unchanged head 02cb915.
The existing findings remain recorded there. This review adds only the uncovered empty-resource-list boundary described inline; please add that regression coverage before merging.
No source files changed and no new runtime defect was found. Tests were not rerun for this posting step because the head is unchanged from the completed audit.
- Verify INVALID report.pdf responses live through both clients. - Match valid and demo-redacted response assertions across transports. - Cover empty resource-list rejection before request execution. Assisted-by: Codex
|
This will be approved once #58 is merged. Thanks! |
|
@datalogics-tsmith This needs a merge or rebase with conflict resolution now that #58 is merged. Probably also a minor version bump. |
- Bring the branch up to date with the merged ZUGFeRD creation API and current repository changes. - Preserve the validation helper, response models, example, and tests against the split creation helpers. Assisted-by: Codex
- Advance project metadata from 1.5.0 to 1.6.0. - Keep the locked editable package version synchronized. Assisted-by: Codex
- Validate rendered invoices through both client transports. - Verify regenerated replacement PDFs remain valid and PDF/A conformant. Assisted-by: Codex
datalogics-kam
left a comment
There was a problem hiding this comment.
The only outstanding thing was the merge fixups, and that's been fixed up.
PDFCLOUD-6572
Why this change
The Python SDK does not expose pdfRest's ZUGFeRD validation operation, so callers cannot use the typed clients to verify an existing ZUGFeRD or Factur-X PDF. This adds a supported way to check package structure, embedded invoice XML, visible-content consistency, and PDF/A-3 conformance before accepting or distributing an electronic invoice.
What changed (high level)
New synchronous and asynchronous
validate_zugferd_pdfhelpers accept an uploaded PDF resource and return a typed validation response. A dedicated Pydantic payload model owns resource validation and wire serialization, while public response models preserve status, content-match results, findings, and free-tier notices with forward-compatible handling of additional response fields.The change also adds focused unit coverage, live endpoint coverage, creation-to-validation live coverage, a runnable example, and API documentation. The branch has been refreshed against
mainafter #57 merged, so the final diff contains only validation work and uses the split ZUGFeRD creation helpers introduced there.Behavior changes
Callers can submit one uploaded PDF and receive its overall
VALIDorINVALIDstatus, independent PDF/A result, content-match status, input resource metadata, and detailed findings. Non-PDF inputs and multiple resources fail locally before transport. Free-tier responses with redacted comparison details remain parseable through the typed models.The live suites verify validation of default XML-created invoices, font-rendered invoices, and PDFs regenerated with
allow_regeneration=True. The API is additive and does not change existing helper behavior.Validation
The focused ZUGFeRD creation and validation unit suites passed all 501 tests. The complete non-live Nox matrix passed on Python 3.10–3.14 with 3,471 tests and 10 expected skips per interpreter. The client-class function coverage gate passed. Ruff formatting and linting passed, and basedpyright reported zero errors.
The focused validation endpoint suite passed all 6 sync and async cases against the local service, including default creation-to-validation, invalid-document reporting, and invalid resource IDs. The restored creation-to-validation scenarios passed all 8 focused sync and async cases, covering three requested font resources and mismatched-PDF regeneration. GitHub Actions was triggered from the main repository branch after the review-fix push.
Risks and follow-ups
PR #57 is merged and this branch now includes current
main; GitHub reports the PR as mergeable. Demo-tier deployments can returnDEMO_REDACTEDfor content comparison details, but callers still receive a parseable response and the overall validation status. Required review and the remaining CI jobs must complete before merge.