Migration and Config Reference

Use this page for public translated-template repository policy, version-branch paths, DSW runtime compatibility, and workflow configuration contracts. These objects are the stable boundary between the tool repository, public repository sync/v* branches, and GitHub Actions helper scripts.

Translation Repository Config

Read-only consistency review across translated template version branches.

class dsw_document_template_tool.translation_repository.consistency.TranslationVersionRecord[source]

Bases: object

One source/target pair read from a version branch translation unit.

class dsw_document_template_tool.translation_repository.consistency.TranslationConsistencyFinding[source]

Bases: object

One shared source sentence that needs cross-version human review.

class dsw_document_template_tool.translation_repository.consistency.TranslationConsistencyReport[source]

Bases: object

Stable machine-readable result of one cross-version consistency scan.

property translation_gap_count: int

Return the number of shared sources with blank/nonblank target drift.

property wording_drift_count: int

Return the number of shared sources with different nonblank targets.

dsw_document_template_tool.translation_repository.consistency.default_consistency_versions(config)[source]

Return active and maintenance versions expected to have editable branches.

Parameters:

config (TranslationRepositoryConfig)

Return type:

list[str]

dsw_document_template_tool.translation_repository.consistency.fetch_version_branches(*, repo, config)[source]

Refresh remote-tracking refs for the configured version branch prefix.

Parameters:
Return type:

None

dsw_document_template_tool.translation_repository.consistency.inspect_translation_repository(*, repo, config, versions=None)[source]

Read configured version branches and build a consistency report.

Parameters:
Return type:

TranslationConsistencyReport

dsw_document_template_tool.translation_repository.consistency.load_version_records(*, repo, config, version)[source]

Read one version’s tree from its remote or local Git branch without checkout.

Parameters:
Return type:

tuple[TranslationVersionRecord, …]

dsw_document_template_tool.translation_repository.consistency.analyze_translation_records(records_by_version)[source]

Compare records by normalized visible source and return review findings.

Parameters:

records_by_version (dict[str, tuple[TranslationVersionRecord, ...]])

Return type:

TranslationConsistencyReport

dsw_document_template_tool.translation_repository.consistency.report_as_json(report)[source]

Serialize a report with explicit summary counts and stable ordering.

Parameters:

report (TranslationConsistencyReport)

Return type:

str

dsw_document_template_tool.translation_repository.consistency.render_consistency_markdown(report, *, max_findings=None)[source]

Render a concise review report for Actions summaries and artifacts.

Parameters:
Return type:

str

Typed configuration and path models for translated-template repositories.

class dsw_document_template_tool.translation_repository.models.TemplateConfig[source]

Bases: object

Source template coordinates and upstream version policy.

class dsw_document_template_tool.translation_repository.models.TranslationConfig[source]

Bases: object

Target translation metadata.

class dsw_document_template_tool.translation_repository.models.BranchConfig[source]

Bases: object

Translation repository branch naming policy.

class dsw_document_template_tool.translation_repository.models.XliffExchangeConfig[source]

Bases: object

Optional branch-local XLIFF exchange policy.

class dsw_document_template_tool.translation_repository.models.MigrationConfig[source]

Bases: object

Cross-version migration policy.

class dsw_document_template_tool.translation_repository.models.VersionPolicyValues[source]

Bases: object

Operational policy values applied to one template version.

class dsw_document_template_tool.translation_repository.models.VersionPolicyPatch[source]

Bases: object

Fields explicitly supplied by one rule or exact override.

class dsw_document_template_tool.translation_repository.models.VersionPolicyRule[source]

Bases: object

Range-based version policy rule.

class dsw_document_template_tool.translation_repository.models.VersionPolicyConfig[source]

Bases: object

Version lifecycle policy loaded from translation-config.yml.

class dsw_document_template_tool.translation_repository.models.PublicReadmeConfig[source]

Bases: object

User-facing README copied into generated translated templates.

class dsw_document_template_tool.translation_repository.models.ToolingConfig[source]

Bases: object

Tooling repository reference used by downstream workflows.

class dsw_document_template_tool.translation_repository.models.TranslationRepositoryConfig[source]

Bases: object

Parsed translation repository configuration.

class dsw_document_template_tool.translation_repository.models.VersionWorkspacePaths[source]

Bases: object

Conventional paths for one translated template version branch.

class dsw_document_template_tool.translation_repository.models.CleanArtifactVersionPaths[source]

Bases: object

Conventional paths for one clean upstream scaffold artifact.

class dsw_document_template_tool.translation_repository.models.DswPreviewRuntime[source]

Bases: object

DSW runtime that can preview a template metamodel range.

Strict loader for public translated-template repository configuration.

dsw_document_template_tool.translation_repository.config.load_translation_repository_config(path)[source]

Load and validate translation-config.yml.

Parameters:

path (Path)

Return type:

TranslationRepositoryConfig

Version lifecycle and cross-version synchronization policy.

dsw_document_template_tool.translation_repository.policy.target_versions(config, source_version, requested_targets=None)[source]

Return supported synchronization targets for one source version.

Parameters:
Return type:

list[str]

dsw_document_template_tool.translation_repository.policy.version_policy_decision(config, version)[source]

Return the effective lifecycle policy for one supported version.

Parameters:
Return type:

VersionPolicyValues

dsw_document_template_tool.translation_repository.policy.version_policy_allows_auto_refresh(config, version)[source]

Return whether automation may rebuild a branch from clean artifacts.

Parameters:
Return type:

bool

dsw_document_template_tool.translation_repository.policy.version_policy_allows_manual_refresh(config, version)[source]

Return whether an operator-triggered sync may refresh a version branch.

Parameters:
Return type:

bool

dsw_document_template_tool.translation_repository.policy.version_policy_allows_manual_migration(config, version)[source]

Return whether an explicitly requested sync may use a version.

Parameters:
Return type:

bool

dsw_document_template_tool.translation_repository.policy.version_policy_allows_auto_migration(config, version)[source]

Return whether automatic cross-version sync may use a version.

Parameters:
Return type:

bool

dsw_document_template_tool.translation_repository.policy.merge_version_policy_values(base, overlay)[source]

Apply only fields explicitly present in a rule or exact override.

Parameters:
Return type:

VersionPolicyValues

dsw_document_template_tool.translation_repository.policy.validate_supported_version(config, version)[source]

Raise if a version is not configured as supported.

Parameters:
Return type:

None

Branch and filesystem conventions for translated-template versions.

dsw_document_template_tool.translation_repository.paths.version_branch(config, version)[source]

Return the translation branch name for a version tag.

Parameters:
Return type:

str

dsw_document_template_tool.translation_repository.paths.migration_branch(config, source, target)[source]

Return the bot branch name for one source-to-target migration.

Parameters:
Return type:

str

dsw_document_template_tool.translation_repository.paths.version_paths(config, version)[source]

Return conventional workspace/output paths for one version.

Parameters:
Return type:

VersionWorkspacePaths

dsw_document_template_tool.translation_repository.paths.clean_artifact_version_paths(config, version, artifact_root)[source]

Return clean scaffold paths for one version inside a downloaded artifact.

Parameters:
Return type:

CleanArtifactVersionPaths

dsw_document_template_tool.translation_repository.paths.clean_artifact_versions(*, config, artifact_root)[source]

Return template versions available in a downloaded clean scaffold artifact.

Parameters:
Return type:

list[str]

DSW preview runtime loading and template-version selection.

dsw_document_template_tool.translation_repository.runtime.load_preview_runtimes(path=PosixPath('config/dsw-compat.yml'))[source]

Load DSW preview runtimes from an explicit repository compatibility table.

Parameters:

path (Path)

Return type:

tuple[DswPreviewRuntime, …]

dsw_document_template_tool.translation_repository.runtime.load_preview_runtimes_text(text, *, source='DSW compatibility config')[source]

Load DSW preview runtimes from in-memory YAML with the same strict schema.

Parameters:

  • text (str)

  • source (str)

Return type:

tuple[DswPreviewRuntime, …]

dsw_document_template_tool.translation_repository.runtime.preview_runtime_for_version(version, *, runtimes=None)[source]

Return the DSW runtime that can preview a template version tag.

Parameters:
Return type:

DswPreviewRuntime

dsw_document_template_tool.translation_repository.runtime.preview_runtime_for_template(version, metamodel_version, *, runtimes=None)[source]

Return the configured runtime for a concrete version/metamodel pair.

Parameters:

  • version (str)

  • metamodel_version (str)

  • runtimes (tuple[DswPreviewRuntime, ...] | None)

Return type:

DswPreviewRuntime

dsw_document_template_tool.translation_repository.runtime.preview_runtime_matrix(path=PosixPath('config/dsw-compat.yml'))[source]

Return GitHub Actions matrix rows for configured preview runtimes.

Parameters:

path (Path)

Return type:

list[dict[str, str]]

Semantic version helpers shared by policy, paths, and runtime selection.

dsw_document_template_tool.translation_repository.versions.sorted_versions(versions)[source]

Sort version tags using numeric semantic version ordering.

Parameters:

versions (Iterable[str])

Return type:

list[str]

dsw_document_template_tool.translation_repository.versions.version_sort_key(version)[source]

Return a sortable key for version tags such as v1.30.1.

Parameters:

version (str)

Return type:

tuple[int, …]

dsw_document_template_tool.translation_repository.versions.version_to_number(version)[source]

Convert v1.30.1 to 1.30.1.

Parameters:

version (str)

Return type:

str

dsw_document_template_tool.translation_repository.versions.version_matches_range(version, expression)[source]

Return whether version satisfies a simple semver range expression.

Parameters:

  • version (str)

  • expression (str)

Return type:

bool

Strict scalar and mapping readers shared by repository config loaders.

dsw_document_template_tool.translation_repository.validation.required_str(payload, key)[source]

Read one required non-empty string.

Parameters:

  • payload (object)

  • key (str)

Return type:

str

dsw_document_template_tool.translation_repository.validation.required_str_list(payload, key)[source]

Read one required list of non-empty strings.

Parameters:

  • payload (object)

  • key (str)

Return type:

list[str]

dsw_document_template_tool.translation_repository.validation.optional_bool(payload, key, *, default)[source]

Read one optional strict boolean.

Parameters:

  • payload (object)

  • key (str)

  • default (bool)

Return type:

bool

dsw_document_template_tool.translation_repository.validation.optional_str(payload, key, *, default='')[source]

Read one optional string while preserving an explicit nullable default.

Parameters:

  • payload (object)

  • key (str)

  • default (str | None)

Return type:

str | None

dsw_document_template_tool.translation_repository.validation.reject_unknown_keys(payload, allowed, section)[source]

Reject misspelled or retired configuration fields.

Parameters:

  • payload (object)

  • allowed (set[str])

  • section (str)

Return type:

None

Errors raised by translated-template repository automation.

exception dsw_document_template_tool.translation_repository.errors.TranslationRepositoryError[source]

Bases: RuntimeError

Raised when translation repository configuration or policy is invalid.

Workflow Config

Workflow config loading and validation.

exception dsw_document_template_tool.config.WorkflowConfigError[source]

Bases: ValueError

Raised when the YAML config is missing required workflow fields.

dsw_document_template_tool.config.load_workflow_config(config_path)[source]

Load one YAML workflow config from disk.

Parameters:

config_path (str | Path)

Return type:

WorkflowConfig

Workflow Data Models

Dataclasses shared by the workflow, API client, and CLI.

class dsw_document_template_tool.models.TemplateCoordinates[source]

Bases: object

Stable document template coordinates.

property full_id: str

Return organizationId:templateId:version.

class dsw_document_template_tool.models.DocumentTemplateReference[source]

Bases: object

Released template identifiers exposed by different DSW API generations.

class dsw_document_template_tool.models.ApiConfig[source]

Bases: object

DSW API connection configuration.

class dsw_document_template_tool.models.TdkConfig[source]

Bases: object

Configuration for the dsw-tdk executable.

class dsw_document_template_tool.models.SubjectConfig[source]

Bases: object

One regression subject, such as baseline or candidate.

class dsw_document_template_tool.models.ProjectSeedConfig[source]

Bases: object

Recipe for creating a fixture project from a knowledge model package.

class dsw_document_template_tool.models.GeneratedFixtureConfig[source]

Bases: object

Recipe for deterministic random fixture projects.

class dsw_document_template_tool.models.FixtureConfig[source]

Bases: object

One regression fixture project.

class dsw_document_template_tool.models.RegressionConfig[source]

Bases: object

Regression execution settings.

class dsw_document_template_tool.models.WorkflowConfig[source]

Bases: object

Top-level workflow configuration loaded from YAML.

class dsw_document_template_tool.models.ResolvedSubject[source]

Bases: object

A subject after local staging or remote lookup has completed.

class dsw_document_template_tool.models.FixtureProject[source]

Bases: object

Resolved fixture project information used during one regression run.

class dsw_document_template_tool.models.RenderArtifact[source]

Bases: object

Paths for one rendered subject output.

class dsw_document_template_tool.models.FixtureRegressionResult[source]

Bases: object

Result for one fixture assertion.

class dsw_document_template_tool.models.RegressionReport[source]

Bases: object

Final workflow report written to disk and printed by the CLI.

DSW Compatibility

Official DSW compatibility source helpers.

This module intentionally only discovers candidate runtime information. Checked-in CI runtimes still live in config/dsw-compat.yml and should only be updated after complete import and render validation.

exception dsw_document_template_tool.dsw_compat.DswCompatSourceError[source]

Bases: RuntimeError

Raised when an official DSW compatibility source cannot be used.

class dsw_document_template_tool.dsw_compat.DswTemplateMetamodelSupport[source]

Bases: object

Official minimum DSW version for a document-template metamodel.

dsw_document_template_tool.dsw_compat.fetch_official_template_metamodel_support(source_url='https://guide.ds-wizard.org/en/latest/more/development/document-templates/specification.html', *, timeout_seconds=20)[source]

Fetch and parse the official DSW document-template metamodel table.

Parameters:

  • source_url (str)

  • timeout_seconds (int)

Return type:

dict[str, DswTemplateMetamodelSupport]

dsw_document_template_tool.dsw_compat.parse_template_metamodel_support(text, *, source_url)[source]

Parse DSW metamodel support rows from the official specification page.

Parameters:

  • text (str)

  • source_url (str)

Return type:

dict[str, DswTemplateMetamodelSupport]

dsw_document_template_tool.dsw_compat.runtime_candidate_message(metamodel_version, support_by_metamodel)[source]

Return a maintainer-facing runtime suggestion for one metamodel.

Parameters:
Return type:

str

Compatibility Probe Planning

Plan and render optimistic DSW metamodel compatibility probes.

class dsw_document_template_tool.compat_probe.DiscoveryRow[source]

Bases: object

One row from the upstream compatibility discovery report.

class dsw_document_template_tool.compat_probe.ProbeChange[source]

Bases: object

A generated optimistic runtime probe change.

class dsw_document_template_tool.compat_probe.ProbePlan[source]

Bases: object

Rendered compatibility probe output.

dsw_document_template_tool.compat_probe.build_probe_plan(*, report, compat_text, evidence_text)[source]

Return a compatibility table with optimistic probe rows added.

Parameters:

  • report (str)

  • compat_text (str)

  • evidence_text (str)

Return type:

ProbePlan

dsw_document_template_tool.compat_probe.render_compat_config(runtimes)[source]

Render the DSW compatibility config in stable, reviewable YAML.

Parameters:

runtimes (tuple[DswPreviewRuntime, ...])

Return type:

str

dsw_document_template_tool.compat_probe.render_evidence_config(evidence_text, assignments)[source]

Replace only the generated runtime assignment block in evidence YAML.

Parameters:

  • evidence_text (str)

  • assignments (tuple[tuple[str, str], ...])

Return type:

str

dsw_document_template_tool.compat_probe.render_probe_report(report, *, plan)[source]

Render a committed compatibility probe report.

Parameters:
Return type:

str

Compatibility Ledger

Offline compatibility fingerprints for upstream template versions.

exception dsw_document_template_tool.compat_ledger.CompatLedgerError[source]

Bases: RuntimeError

Raised when a compatibility ledger cannot be generated.

class dsw_document_template_tool.compat_ledger.VersionWorkspace[source]

Bases: object

Conventional generated workspace paths for one source template version.

dsw_document_template_tool.compat_ledger.write_compat_ledger(*, workspace_root, output_dir, source_template_id, scaffold_root=None, source_lang='en', target_lang='zh_Hant')[source]

Write per-version JSON ledgers and a Markdown summary.

Parameters:

  • workspace_root (Path)

  • output_dir (Path)

  • source_template_id (str)

  • scaffold_root (Path | None)

  • source_lang (str)

  • target_lang (str)

Return type:

list[dict[str, Any]]

dsw_document_template_tool.compat_ledger.build_version_entry(*, workspace, source_template_id, scaffold_root, source_lang, target_lang)[source]

Build one machine-readable compatibility fingerprint.

Parameters:

  • workspace (VersionWorkspace)

  • source_template_id (str)

  • scaffold_root (Path | None)

  • source_lang (str)

  • target_lang (str)

Return type:

dict[str, Any]

dsw_document_template_tool.compat_ledger.iter_version_workspaces(*, workspace_root, source_template_id)[source]

Return generated version workspace paths sorted by semantic version.

Parameters:

  • workspace_root (Path)

  • source_template_id (str)

Return type:

list[VersionWorkspace]

dsw_document_template_tool.compat_ledger.collect_file_tree_stats(root)[source]

Collect stable file-level stats for a generated workspace.

Parameters:

root (Path)

Return type:

dict[str, Any]

dsw_document_template_tool.compat_ledger.collect_expanded_tree_stats(root)[source]

Collect expanded-template stats, including generated translation wrappers.

Parameters:

root (Path)

Return type:

dict[str, Any]

dsw_document_template_tool.compat_ledger.collect_translation_tree_stats(tree_dir, *, source_lang, target_lang)[source]

Collect unit and placeholder stats from a translator-facing tree.

Parameters:

  • tree_dir (Path)

  • source_lang (str)

  • target_lang (str)

Return type:

dict[str, Any]

dsw_document_template_tool.compat_ledger.collect_scaffold_packages(*, scaffold_root, version)[source]

Collect package metadata for generated clean scaffold zip files.

Parameters:

  • scaffold_root (Path | None)

  • version (str)

Return type:

list[dict[str, Any]]

dsw_document_template_tool.compat_ledger.render_compat_ledger_summary(entries)[source]

Render a maintainer-facing compatibility summary.

Parameters:

entries (list[dict[str, Any]])

Return type:

str

dsw_document_template_tool.compat_ledger.build_regression_plan(entries)[source]

Recommend high-value DSW regression candidates from ledger entries.

Parameters:

entries (list[dict[str, Any]])

Return type:

dict[str, Any]

dsw_document_template_tool.compat_ledger.structure_signature(entry)[source]

Return the low-noise expanded/tree structure signature for one version.

Parameters:

entry (dict[str, Any])

Return type:

dict[str, Any]

dsw_document_template_tool.compat_ledger.render_regression_plan_summary(plan)[source]

Render a maintainer-facing regression candidate plan.

Parameters:

plan (dict[str, Any])

Return type:

str

dsw_document_template_tool.compat_ledger.digest_file_tree(root)[source]

Return a deterministic digest for paths and contents below root.

Parameters:

root (Path)

Return type:

str

dsw_document_template_tool.compat_ledger.digest_json(payload)[source]

Return a deterministic SHA-256 digest for JSON-compatible data.

Parameters:

payload (Any)

Return type:

str

dsw_document_template_tool.compat_ledger.digest_file(path)[source]

Return a SHA-256 digest for one file.

Parameters:

path (Path)

Return type:

str