Render and Regression Reference

Use this page for maintainer-facing DSW rendering, fixture generation, HTML comparison, and regression workflow entrypoints. Use the regression workflow runbook for operational steps before running these APIs directly.

Regression Workflow Service

class dsw_document_template_tool.workflow.DocumentTemplateWorkflowService[source]

Bases: object

High-level service that performs headless regression comparisons.

run(config_path)[source]

Load config and execute the full regression workflow.

Parameters:

config_path (str | Path)

Return type:

RegressionReport

classmethod __new__(*args, **kwargs)

DSW API Adapter

The adapter keeps server-generation differences out of workflow and rendering services. Released document templates may be identified by coordinates or by a UUID depending on the DSW runtime.

Small DSW API client for headless preview/document regression flows.

exception dsw_document_template_tool.api.DSWAPIError[source]

Bases: RuntimeError

Raised when the DSW API returns an unexpected response.

class dsw_document_template_tool.api.KnowledgeModelPackageReference[source]

Bases: object

Resolved KM package identifiers across DSW API generations.

require_project_create_identifier()[source]

Return the best package identifier for older project create payloads.

Return type:

str

require_uuid()[source]

Return the UUID required by current project APIs.

Return type:

str

class dsw_document_template_tool.api.DSWApiClient[source]

Bases: object

Minimal API client used by the regression workflow.

close()[source]

Close the underlying requests session.

Return type:

None

set_token(token)[source]

Store the bearer token for future authenticated requests.

Parameters:

token (str)

Return type:

None

login(*, email, password)[source]

Create an API token using DSW email/password credentials.

Parameters:

  • email (str)

  • password (str)

Return type:

str

get_current_user()[source]

Fetch the current authenticated user.

Return type:

dict[str, Any]

find_draft_uuid_by_id(template_id)[source]

Resolve draft coordinates into the API’s draft reference.

DSW 4.30+ exposes draft UUIDs. Older DSW releases identify drafts by tId (org:template:version) while using the same preview endpoints. The caller only needs an endpoint reference, so this method returns whichever identifier the server exposes.

Parameters:

template_id (str)

Return type:

str | None

check_draft_exists(draft_uuid)[source]

Return whether a specific draft UUID exists.

Parameters:

draft_uuid (str)

Return type:

bool

resolve_document_template_reference(template_id)[source]

Resolve released template coordinates across DSW API generations.

Parameters:

template_id (str)

Return type:

DocumentTemplateReference

resolve_knowledge_model_package_uuid(package_id)[source]

Resolve released KM package coordinates into the API’s UUID field.

Parameters:

package_id (str)

Return type:

str

resolve_knowledge_model_package_reference(package_id)[source]

Resolve a KM package across current and older DSW API shapes.

Parameters:

package_id (str)

Return type:

KnowledgeModelPackageReference

find_knowledge_model_package_uuid_by_id(package_id)[source]

Resolve KM coordinates like org:km:version into a package UUID.

Parameters:

package_id (str)

Return type:

str | None

find_knowledge_model_package_reference_by_id(package_id)[source]

Resolve KM coordinates into whichever identifiers the DSW API exposes.

Parameters:

package_id (str)

Return type:

KnowledgeModelPackageReference | None

create_project_from_package(*, name, knowledge_model_package_id, question_tag_uuids, visibility, sharing)[source]

Create one fixture project.

Parameters:

  • name (str)

  • knowledge_model_package_id (str)

  • question_tag_uuids (list[str])

  • visibility (str)

  • sharing (str)

Return type:

dict[str, Any]

put_project_content(*, project_uuid, events)[source]

Apply a stable fixture event list to one project.

Parameters:

  • project_uuid (str)

  • events (list[dict[str, Any]])

Return type:

None

get_project_questionnaire(project_uuid)[source]

Fetch one project with the server-compiled knowledge model.

Parameters:

project_uuid (str)

Return type:

dict[str, Any]

delete_project(project_uuid)[source]

Delete a fixture project.

Parameters:

project_uuid (str)

Return type:

None

upload_knowledge_model_package_bundle(bundle_path)[source]

Upload one local KM bundle to the DSW API.

Parameters:

bundle_path (Path)

Return type:

dict[str, Any]

upload_knowledge_model_package_bundle_reference(bundle_path)[source]

Upload one local KM bundle and normalize current/older response shapes.

Parameters:

bundle_path (Path)

Return type:

KnowledgeModelPackageReference

upload_document_template_bundle_reference(bundle_path)[source]

Upload one released template and normalize its server identifier.

Parameters:

bundle_path (Path)

Return type:

DocumentTemplateReference

put_draft_preview_settings(*, draft_uuid, format_uuid, project_uuid)[source]

Bind one draft preview to a format and a project.

Parameters:

  • draft_uuid (str)

  • format_uuid (str)

  • project_uuid (str)

Return type:

dict[str, Any]

poll_draft_preview_url(*, draft_uuid, timeout_seconds, poll_seconds)[source]

Poll the preview endpoint until a downloadable URL is ready.

Parameters:

  • draft_uuid (str)

  • timeout_seconds (int)

  • poll_seconds (float)

Return type:

str

create_document(*, name, project_uuid, document_template, format_uuid, project_event_uuid)[source]

Queue one final document generation job.

Parameters:

  • name (str)

  • project_uuid (str)

  • document_template (DocumentTemplateReference)

  • format_uuid (str)

  • project_event_uuid (str | None)

Return type:

dict[str, Any]

list_project_documents(project_uuid)[source]

List current documents for one project.

Parameters:

project_uuid (str)

Return type:

list[dict[str, Any]]

poll_document_ready(*, project_uuid, document_uuid, timeout_seconds, poll_seconds)[source]

Poll a queued document until it becomes DoneDocumentState or errors.

Parameters:

  • project_uuid (str)

  • document_uuid (str)

  • timeout_seconds (int)

  • poll_seconds (float)

Return type:

dict[str, Any]

get_document_download_url(document_uuid)[source]

Get the download URL for one completed document.

Parameters:

document_uuid (str)

Return type:

str

download_url_text(url)[source]

Download one rendered artifact as UTF-8 text.

Parameters:

url (str)

Return type:

str

download_url_bytes(url)[source]

Download one rendered artifact as raw bytes.

Parameters:

url (str)

Return type:

bytes

class dsw_document_template_tool.models.DocumentTemplateReference[source]

Bases: object

Released template identifiers exposed by different DSW API generations.

Render Project

Service for rendering one DSW project with a document template.

class dsw_document_template_tool.render_project.ResolvedProject[source]

Bases: object

Project UUID resolved from an existing reference or created from events.

dsw_document_template_tool.render_project.render_project(*, project_uuid, project_ref, template_dir, template_package, output_path, format_uuid, stage_id, api_url, api_key, email, password, tdk_executable, timeout_seconds, poll_seconds, verify_ssl, keep_created_project=False)[source]

Render one project with a draft source tree or released package zip.

Parameters:

  • project_uuid (str | None)

  • project_ref (Path)

  • template_dir (Path)

  • template_package (Path | None)

  • output_path (Path)

  • format_uuid (str)

  • stage_id (str | None)

  • api_url (str)

  • api_key (str | None)

  • email (str)

  • password (str)

  • tdk_executable (str)

  • timeout_seconds (int)

  • poll_seconds (float)

  • verify_ssl (bool)

  • keep_created_project (bool)

Return type:

Path

Fixture Generation

Plan a compact set of generated projects that covers questionnaire branches.

class dsw_document_template_tool.fixture_coverage.BranchToken[source]

Bases: object

One answer or collection shape that a generated fixture can exercise.

as_dict()[source]

Return a JSON-serializable representation.

Return type:

dict[str, str]

class dsw_document_template_tool.fixture_coverage.GeneratedFixturePlan[source]

Bases: object

Selected case indexes and their branch-coverage report.

property missing: frozenset[BranchToken]

Return expected branches not covered by selected cases.

property complete: bool

Return whether every expected branch has a selected fixture.

as_dict()[source]

Return a stable JSON report suitable for CI artifacts.

Return type:

dict[str, Any]

dsw_document_template_tool.fixture_coverage.plan_generated_fixture_cases(questionnaire, *, seed, case_limit, candidate_count, max_events, max_items_per_list, answer_probability)[source]

Select deterministic cases that greedily maximize reachable branch coverage.

Parameters:

  • questionnaire (dict[str, Any])

  • seed (int)

  • case_limit (int)

  • candidate_count (int)

  • max_events (int)

  • max_items_per_list (int)

  • answer_probability (float)

Return type:

GeneratedFixturePlan

Deterministic branch-sweeping questionnaire fixtures for render regression.

class dsw_document_template_tool.fixture_generator.GeneratedQuestionnaireEvents[source]

Bases: object

Generated event payload plus lightweight coverage statistics.

dsw_document_template_tool.fixture_generator.generate_questionnaire_events(questionnaire, *, seed, case_index, max_events=260, max_items_per_list=2, answer_probability=1.0)[source]

Generate deterministic branch-sweeping DSW SetReplyEvent values.

The generator intentionally consumes the DSW API’s compiled knowledgeModel instead of replaying KM package history. That keeps the fixture robust when a KM package is upgraded: if DSW can create the project, this generator follows the same final chapter/question/answer graph DSW renders. Each question derives an independent deterministic permutation from the case index. This avoids coupling nested branches to the same remainder as their parents while keeping every generated case reproducible.

Parameters:

  • questionnaire (dict[str, Any])

  • seed (int)

  • case_index (int)

  • max_events (int)

  • max_items_per_list (int)

  • answer_probability (float)

Return type:

GeneratedQuestionnaireEvents

Runtime Evidence

Generate version-aware configs for comparison and package render regression.

class dsw_document_template_tool.regression_config.RegressionWorkspace[source]

Bases: object

One built upstream workspace that can be used for full regression.

dsw_document_template_tool.regression_config.select_regression_workspace(*, workspace_root, source_template_id, version, metamodel_version)[source]

Select the latest or explicitly requested workspace for regression.

Parameters:

  • workspace_root (Path)

  • source_template_id (str)

  • version (str)

  • metamodel_version (str)

Return type:

RegressionWorkspace

dsw_document_template_tool.regression_config.discover_regression_workspaces(*, workspace_root, source_template_id, metamodel_version)[source]

Return built regression workspaces sorted by semantic version.

Parameters:

  • workspace_root (Path)

  • source_template_id (str)

  • metamodel_version (str)

Return type:

list[RegressionWorkspace]

dsw_document_template_tool.regression_config.write_workspace_regression_config(*, base_config, output, output_dir_suffix, source_template_id, workspace, knowledge_model_path)[source]

Write an equality config for one compact/expanded upstream pair.

Parameters:

  • base_config (Path)

  • output (Path)

  • output_dir_suffix (str)

  • source_template_id (str)

  • workspace (RegressionWorkspace)

  • knowledge_model_path (Path)

Return type:

None

dsw_document_template_tool.regression_config.write_package_render_config(*, base_config, output, output_dir, package_path, knowledge_model_path)[source]

Write a single-subject full render config for one packaged template.

Parameters:

  • base_config (Path)

  • output (Path)

  • output_dir (Path)

  • package_path (Path)

  • knowledge_model_path (Path)

Return type:

None

dsw_document_template_tool.regression_config.select_regression_knowledge_model(*, compat_config, evidence_config, workspace)[source]

Return verified KM evidence for a selected template workspace.

Parameters:
Return type:

KnowledgeModelEvidence

dsw_document_template_tool.regression_config.select_regression_knowledge_model_for_metamodel(*, compat_config, evidence_config, metamodel_version)[source]

Return verified KM evidence for one configured document-template metamodel.

Parameters:

  • compat_config (Path)

  • evidence_config (Path)

  • metamodel_version (str)

Return type:

KnowledgeModelEvidence

Traceable Knowledge Model evidence for DSW render regression.

class dsw_document_template_tool.regression_evidence.KnowledgeModelEvidence[source]

Bases: object

Pinned provenance for one immutable Knowledge Model bundle.

class dsw_document_template_tool.regression_evidence.RegressionEvidenceConfig[source]

Bases: object

Knowledge Model fixtures assigned to supported DSW runtimes.

knowledge_model_for_runtime(runtime)[source]

Return the pinned Knowledge Model assigned to runtime.

Parameters:

runtime (DswPreviewRuntime)

Return type:

KnowledgeModelEvidence

dsw_document_template_tool.regression_evidence.load_regression_evidence_config(path)[source]

Load and validate pinned regression evidence from YAML.

Parameters:

path (Path)

Return type:

RegressionEvidenceConfig

dsw_document_template_tool.regression_evidence.validate_regression_evidence_config(config, runtimes)[source]

Validate runtime assignments and every pinned Knowledge Model bundle.

Parameters:
Return type:

None

dsw_document_template_tool.regression_evidence.verify_knowledge_model_evidence(evidence)[source]

Verify one pinned bundle’s checksum and declared package metadata.

Parameters:

evidence (KnowledgeModelEvidence)

Return type:

None

Build auditable evidence for one DSW render-regression runtime.

class dsw_document_template_tool.runtime_evidence.CoverageEvidence[source]

Bases: object

Complete generated-fixture coverage for one fixture group.

class dsw_document_template_tool.runtime_evidence.VersionEvidence[source]

Bases: object

Regression and PDF evidence for one template version.

class dsw_document_template_tool.runtime_evidence.RuntimeEvidence[source]

Bases: object

Auditable render result for one document-template metamodel runtime.

dsw_document_template_tool.runtime_evidence.collect_runtime_evidence(*, compat_config, evidence_config, metamodel_version, plan_path, preview_root, regression_root, source_template_id, translation_locale)[source]

Collect strict regression, coverage, KM, and preview evidence.

Parameters:

  • compat_config (Path)

  • evidence_config (Path)

  • metamodel_version (str)

  • plan_path (Path)

  • preview_root (Path)

  • regression_root (Path)

  • source_template_id (str)

  • translation_locale (str)

Return type:

RuntimeEvidence

dsw_document_template_tool.runtime_evidence.write_runtime_evidence(report, output_dir)[source]

Write machine-readable JSON and maintainer-facing Markdown reports.

Parameters:
Return type:

tuple[Path, Path]

dsw_document_template_tool.runtime_evidence.render_runtime_evidence(report)[source]

Render one concise runtime-evidence Markdown report.

Parameters:

report (RuntimeEvidence)

Return type:

str

HTML Comparison

HTML normalization and diff helpers used by regression checks.

dsw_document_template_tool.html_diff.normalize_html(html, *, ignore_patterns=None)[source]

Normalize rendered HTML so meaningful regressions diff cleanly.

Parameters:

  • html (str)

  • ignore_patterns (list[str] | None)

Return type:

str

dsw_document_template_tool.html_diff.build_unified_diff(baseline_text, candidate_text, *, baseline_label='baseline', candidate_label='candidate')[source]

Build a unified diff string for normalized HTML.

Parameters:

  • baseline_text (str)

  • candidate_text (str)

  • baseline_label (str)

  • candidate_label (str)

Return type:

str

Regression Internals

Write and compare deterministic regression artifacts.

dsw_document_template_tool._regression.artifacts.write_render_artifact(*, fixture_output_dir, subject, raw_html, ignore_patterns)[source]

Persist raw and normalized HTML for one regression subject.

Parameters:

  • fixture_output_dir (Path)

  • subject (ResolvedSubject)

  • raw_html (str)

  • ignore_patterns (list[str])

Return type:

RenderArtifact

dsw_document_template_tool._regression.artifacts.compare_render_artifacts(*, fixture_output_dir, baseline, candidate)[source]

Compare normalized artifacts and write a unified diff on mismatch.

Parameters:
Return type:

tuple[bool, Path | None]

dsw_document_template_tool._regression.artifacts.serialize_regression_report(report)[source]

Convert a regression report into its stable JSON representation.

Parameters:

report (RegressionReport)

Return type:

dict[str, Any]

Run baseline and candidate renders with isolated API clients.

dsw_document_template_tool._regression.parallel.render_subjects_in_parallel(*, client, baseline_render, candidate_render)[source]

Render both subjects concurrently without sharing a requests session.

Parameters:
Return type:

tuple[str, str]

dsw_document_template_tool._regression.parallel.clone_authenticated_client(client)[source]

Clone API connection settings and bearer token for one render worker.

Parameters:

client (DSWApiClient)

Return type:

DSWApiClient

TDK Helpers

Helpers that stage local templates and invoke dsw-tdk safely.

exception dsw_document_template_tool.tdk.TemplateToolError[source]

Bases: RuntimeError

Raised when a local template cannot be staged or uploaded.

dsw_document_template_tool.tdk.read_local_template_coordinates(template_dir)[source]

Read document template coordinates from template.json.

Parameters:

template_dir (Path)

Return type:

TemplateCoordinates

dsw_document_template_tool.tdk.read_local_template_package_coordinates(package_path)[source]

Read document template coordinates from a packaged template ZIP.

Parameters:

package_path (Path)

Return type:

TemplateCoordinates

dsw_document_template_tool.tdk.stage_local_template_package(*, source_package)[source]

Copy a package under content-addressed coordinates for repeatable local renders.

Parameters:

source_package (Path)

Return type:

tuple[Path, TemplateCoordinates]

dsw_document_template_tool.tdk.stage_local_template_dir(*, source_dir, subject_label, stage_id)[source]

Copy a local template to a temporary staging directory and rewrite IDs.

Parameters:

  • source_dir (Path)

  • subject_label (str)

  • stage_id (str | None)

Return type:

tuple[Path, TemplateCoordinates]

dsw_document_template_tool.tdk.verify_template_dir(*, executable, template_dir)[source]

Run dsw-tdk verify for one local template directory.

Parameters:

  • executable (str)

  • template_dir (Path)

Return type:

None

dsw_document_template_tool.tdk.put_template_dir(*, executable, template_dir, api_url, api_key)[source]

Run dsw-tdk put for one local template directory.

Parameters:

  • executable (str)

  • template_dir (Path)

  • api_url (str)

  • api_key (str)

Return type:

None

dsw_document_template_tool.tdk.parse_template_coordinates(value)[source]

Parse organizationId:templateId:version into structured coordinates.

Parameters:

value (str)

Return type:

TemplateCoordinates

CLI Entry Points

Command-line adapter for rendering one DSW project.

dsw_document_template_tool.cli.render_project.build_argument_parser()[source]

Build the render-project command parser.

Return type:

ArgumentParser

dsw_document_template_tool.cli.render_project.main()[source]

Render the selected project and exit non-zero on failure.

Return type:

None

CLI entrypoint for the headless DSW document template regression workflow.

dsw_document_template_tool.cli.render_regression.build_argument_parser()[source]

Build the CLI argument parser.

Return type:

ArgumentParser

dsw_document_template_tool.cli.render_regression.main()[source]

Run the configured regression workflow and exit non-zero on failure.

Return type:

None