PDFCLOUD-6254: Convert structured documents to PDF

AGENTS.md

@@ -220,10 +220,14 @@
   customization (sync + async), validation failures, and multi-file guards. Add
   a shared validation suite when multiple endpoints rely on the same input rules
   (e.g., `tests/test_graphic_payload_validation.py`).
-- Do not import from private modules (names beginning with an underscore) in
-  production code. In tests, prefer public modules first; allow private-model
-  imports only when necessary to validate request serialization or mock
-  server-facing payload contracts that are not exposed publicly.
+- Production code may import private modules and symbols within its own package,
+  including `pdfrest.client` importing `pdfrest.models._internal`. Do not import
+  private modules or symbols from external packages; use their supported public
+  APIs. Another company-owned package is still an external dependency. Keep
+  package-owned internals outside public exports unless intentionally promoted
+  to a supported API. In tests, prefer public APIs; access package-owned
+  internals when needed to verify implementation behavior or request
+  serialization.
 
 ## Testing Guidelines
 
@@ -433,7 +437,16 @@
 
 ## Commit & Pull Request Guidelines
 
-- Follow the `area: summary` convention seen in `pdfassistant-chatbot` (e.g.,
+- This is a public repository. Keep source, tests, examples, documentation,
+  commit messages, PR descriptions, and review comments suitable for public
+  disclosure. Do not name or link private components, implementation classes,
+  repositories, infrastructure, internal hosts, or unrelated Jira work items.
+- Describe service limitations using observable API behavior. For blocked live
+  coverage, document the affected cases and the steps to re-enable them without
+  exposing private implementation details. Reference only the PR's primary Jira
+  work item unless the user explicitly authorizes another reference and confirms
+  it is suitable for public disclosure.
+- Follow the `area: summary` convention (e.g.,
   `client: Add document merge service`).
 - Name the commit scope after the primary file, directory, or domain object
   affected by the change, such as `AGENTS`, `pdfrest-client-api`, `client`,

docs/api-guide.md

@@ -135,7 +135,12 @@ formats.
   [convert_email_to_pdf][pdfrest.PdfRestClient.convert_email_to_pdf],
   [convert_image_to_pdf][pdfrest.PdfRestClient.convert_image_to_pdf],
   [convert_html_to_pdf][pdfrest.PdfRestClient.convert_html_to_pdf],
-  [convert_url_to_pdf][pdfrest.PdfRestClient.convert_url_to_pdf]
+  [convert_url_to_pdf][pdfrest.PdfRestClient.convert_url_to_pdf],
+  [convert_markdown_to_pdf][pdfrest.PdfRestClient.convert_markdown_to_pdf],
+  [convert_plain_text_to_pdf][pdfrest.PdfRestClient.convert_plain_text_to_pdf],
+  [convert_json_to_pdf][pdfrest.PdfRestClient.convert_json_to_pdf],
+  [convert_xml_to_pdf][pdfrest.PdfRestClient.convert_xml_to_pdf],
+  [convert_csv_to_pdf][pdfrest.PdfRestClient.convert_csv_to_pdf]
 - Out of PDF:
   [convert_to_word][pdfrest.PdfRestClient.convert_to_word],
   [convert_to_excel][pdfrest.PdfRestClient.convert_to_excel],

examples/README.md

@@ -23,6 +23,9 @@ supported interpreter matrix.
 
 - `examples/add_shapes/add_shapes_to_pdf_example.py` – add a styled rectangle
   and divider line to a PDF with accessibility tagging enabled.
+- `examples/convert_structured_documents/convert_structured_documents_to_pdf_example.py`
+  – convert Markdown, plain text, JSON, XML, and CSV documents to PDF with
+  format-specific options.
 - `examples/delete/delete_example.py` – demonstrate file deletion (sync + async
   variants).
 - `examples/extract_text/extract_pdf_text_example.py` – run `extract_pdf_text`

examples/convert_structured_documents/convert_structured_documents_to_pdf_example.py

@@ -0,0 +1,144 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pdfrest", "python-dotenv"]
+# ///
+"""Convert Markdown, plain text, JSON, XML, and CSV documents to PDF.
+
+This sample demonstrates how to:
+
+1. Upload the five deterministic structured documents in ``examples/resources``.
+2. Select format-specific conversion options with public typed dictionaries.
+3. Generate one PDF from each source through the focused client helpers.
+4. Print the returned PDF names, MIME types, sizes, and download URLs.
+
+Set ``PDFREST_API_KEY``, then run from the repository root with
+``uv run examples/convert_structured_documents/convert_structured_documents_to_pdf_example.py``.
+All required input files are included in the repository.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from pdfrest import PdfRestClient
+from pdfrest.models import PdfRestFileBasedResponse
+from pdfrest.types import (
+    PdfStructuredTextCsvColumn,
+    PdfStructuredTextMargin,
+    PdfStructuredTextPageSetup,
+    PdfStructuredTextStyle,
+    PdfStructuredTextTableStyle,
+)
+
+RESOURCE_DIRECTORY = Path(__file__).resolve().parents[1] / "resources"
+RESOURCE_PATHS = [
+    RESOURCE_DIRECTORY / "structured-document.md",
+    RESOURCE_DIRECTORY / "structured-document.txt",
+    RESOURCE_DIRECTORY / "structured-document.json",
+    RESOURCE_DIRECTORY / "structured-document.xml",
+    RESOURCE_DIRECTORY / "structured-document.csv",
+]
+
+
+def _print_result(label: str, response: PdfRestFileBasedResponse) -> None:
+    output = response.output_file
+    print(f"{label}: {output.name}")
+    print(f"  MIME type: {output.type}")
+    print(f"  Size: {output.size} bytes")
+    print(f"  Download URL: {output.url}")
+
+
+def convert_structured_documents() -> None:
+    """Upload each sample and convert it with its format-specific helper."""
+    load_dotenv()
+    page_setup = PdfStructuredTextPageSetup(
+        size="Letter",
+        orientation="portrait",
+        margin=PdfStructuredTextMargin(top=36, right=36, bottom=36, left=36),
+    )
+    style = PdfStructuredTextStyle(
+        font="Arial",
+        text_size=11,
+        text_color_rgb=(32, 42, 54),
+        heading_scale=1.4,
+    )
+    table_style = PdfStructuredTextTableStyle(
+        show_borders=True,
+        repeat_headers_on_overflow=True,
+        header_fill_color_rgb=(34, 93, 131),
+        header_text_color_rgb=(255, 255, 255),
+    )
+    columns = [
+        PdfStructuredTextCsvColumn(index=0, text_align="left", width_weight=2),
+        PdfStructuredTextCsvColumn(index=1, text_align="right", width_weight=1),
+    ]
+
+    with PdfRestClient() as client:
+        markdown, plain_text, json_file, xml_file, csv_file = (
+            client.files.create_from_paths(RESOURCE_PATHS)
+        )
+        responses = [
+            (
+                "Markdown",
+                client.convert_markdown_to_pdf(
+                    markdown,
+                    title="Markdown service summary",
+                    enable_tagging=True,
+                    page_setup=page_setup,
+                    style=style,
+                    table_style=table_style,
+                    output="markdown-summary",
+                ),
+            ),
+            (
+                "Plain text",
+                client.convert_plain_text_to_pdf(
+                    plain_text,
+                    line_handling="reflow",
+                    page_setup=page_setup,
+                    style=style,
+                    output="plain-text-summary",
+                ),
+            ),
+            (
+                "JSON",
+                client.convert_json_to_pdf(
+                    json_file,
+                    data_presentation="hierarchy",
+                    page_setup=page_setup,
+                    style=style,
+                    output="json-summary",
+                ),
+            ),
+            (
+                "XML",
+                client.convert_xml_to_pdf(
+                    xml_file,
+                    data_presentation="hierarchy",
+                    page_setup=page_setup,
+                    style=style,
+                    output="xml-summary",
+                ),
+            ),
+            (
+                "CSV",
+                client.convert_csv_to_pdf(
+                    csv_file,
+                    first_row_is_header=True,
+                    columns=columns,
+                    table_style=table_style,
+                    page_setup=page_setup,
+                    style=style,
+                    output="csv-summary",
+                ),
+            ),
+        ]
+
+    for label, response in responses:
+        _print_result(label, response)
+
+
+if __name__ == "__main__":  # pragma: no cover - manual example
+    convert_structured_documents()

examples/resources/structured-document.csv

@@ -0,0 +1,3 @@
+service,availability_percent,status
+Document API,99.98,healthy
+Conversion API,99.97,healthy

examples/resources/structured-document.json

@@ -0,0 +1,5 @@
+{
+  "quarter": "Q3",
+  "availability_percent": 99.98,
+  "priorities": ["accessibility", "document generation"]
+}

examples/resources/structured-document.md

@@ -0,0 +1,10 @@
+**The Importance of Sleep**
+
+Sleep is often underestimated, but it plays a vital role in maintaining health
+and well-being. During sleep, the body repairs tissues, consolidates memories,
+and restores energy for the next day.
+
+Modern life tends to push sleep aside. Busy schedules, late-night work, and
+constant access to technology can all reduce rest.
+
+Prioritizing sleep supports balance and long-term health.

examples/resources/structured-document.txt

@@ -0,0 +1,4 @@
+Quarterly service summary
+
+Availability improved during the quarter while response times remained stable.
+The next release focuses on accessibility and document-generation workflows.

examples/resources/structured-document.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<service-summary quarter="Q3">
+  <availability-percent>99.98</availability-percent>
+  <priority>accessibility</priority>
+  <priority>document generation</priority>
+</service-summary>

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pdfrest"
-version = "1.1.0"
+version = "1.2.0"
 description = "Python client library for interacting with the pdfRest API"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [