PDFCLOUD-6254: Convert structured documents to PDF - #46
Closed
datalogics-kam wants to merge 11 commits into
Closed
Conversation
- Export public structured document types for page, style, table, and format-specific options. - Add format-specific payload validation and nested wire serialization. - Deduplicate uploaded Markdown images into ordered resource IDs. Assisted-by: Codex
- Add synchronous and asynchronous helpers for Markdown, plain text, JSON, XML, and CSV inputs. - Cover exact request serialization, validation boundaries, transport behavior, and request customization. Assisted-by: Codex
- Exercise all five structured formats through synchronous and asynchronous clients. - Verify Markdown image resources, response metadata, and server-side invalid-option handling against deterministic fixtures. Assisted-by: Codex
- Add a runnable upload-first example covering Markdown, plain text, JSON, XML, and CSV helpers. - Add deterministic source documents and register the example in the inventory. Assisted-by: Codex
- Add all five format-specific conversion helpers to the Into PDF API guide. - Link generated method signatures to their public structured option types. Assisted-by: Codex
- Release the structured document conversion helpers as a minor feature update. - Keep the project metadata and lockfile package version synchronized. Assisted-by: Codex
- Define an applicability matrix for choosing focused helpers or a coherent discriminated contract. - Allow commit scopes to name the primary file, directory, or domain object they affect. Assisted-by: Codex
- Explain data presentation, page orientation, image alt-text policy, line handling, and CSV alignment values. - Keep value documentation on public aliases for generated API reference reuse. Assisted-by: Codex
Exercise every structured-document literal through both client transports against the live service, including shared page orientation. Assisted-by: Codex
Verify every helper rejects every other structured source before transport, and covers sync and async request customization timeouts. Assisted-by: Codex
Reject below-minimum page, style, table, color, and CSV values so structured conversion constraints are tested on both boundaries. Assisted-by: Codex
datalogics-kam
had a problem deploying
to
ci-live
August 29, 2026 14:28 — with 
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-kam
had a problem deploying
to
ci-live
August 29, 2026 14:28 — with
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-kam
had a problem deploying
to
ci-live
August 29, 2026 14:28 — with
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-kam
had a problem deploying
to
ci-live
August 29, 2026 14:28 — with
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-kam
had a problem deploying
to
ci-live
August 29, 2026 14:28 — with
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-kam
had a problem deploying
to
ci-live
August 29, 2026 14:28 — with
GitHub Actions
Failure
GitHub Actions
Failure
datalogics-kam
deleted the
pdfcloud-6254-add-structured-document-conversions
branch
August 29, 2026 14:43
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
1 participant
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-6254
Why this change
The SDK could not convert structured Markdown, plain text, JSON, XML, or CSV documents through the documented
POST /pdfcapability. Callers had to construct untyped requests and could accidentally combine options that the service accepts only for particular source formats.What changed (high level)
The synchronous and asynchronous clients now provide five format-specific helpers backed by Pydantic payload models and public structured-document types. Format-specific signatures keep incompatible options separate while shared page, typography, table, color, and output settings serialize to the API's
structured_text_optionsobject. Markdown image mappings accept uploaded resources and internally deduplicate their IDs.Behavior changes
Callers upload a source document and pass its
PdfRestFiletoconvert_markdown_to_pdf,convert_plain_text_to_pdf,convert_json_to_pdf,convert_xml_to_pdf, orconvert_csv_to_pdf. Local validation rejects the wrong source format, multiple source files, unsupported Markdown image MIME types, and invalid literal or numeric options before transport. The SDK adds a runnable combined example, fixtures, generated API-guide links, and documented Literal value meanings. This is a feature release from 1.1.0 to 1.2.0; no existing public APIs change.Validation
uv run pytest -n auto --maxschedchunk 2 tests/test_convert_structured_documents_to_pdf.py— 121 passed, 10 expected matching-format skips.PDFREST_LIVE_BASE_URL=http://sleipnir:3000 uvx nox -s tests-3.11 -- tests/live/test_live_convert_structured_documents_to_pdf.py— 32 passed.Risks and follow-ups
This is a stacked draft PR on #45: merge #45 first, then this PR. The base is
pdfcloud-6243-pdf-with-added-shapes, so reviewers see only the structured-document conversion layer. The live coverage depends on the suppliedsleipnir:3000service. No breaking changes are intended.