Template Transform Reference

Use this page for maintainer-facing transform entrypoints that expand upstream DSW template source into translation-friendly workspaces and compact it back for upload or comparison. Use the parser guide for the lower-level rewrite rules behind these APIs.

Transform Facade

Reversible expansion helpers for translation-friendly DSW templates.

exception dsw_document_template_tool.template_transform.TemplateTransformError[source]

Bases: RuntimeError

Raised when a template cannot be expanded or compacted safely.

dsw_document_template_tool.template_transform.snapshot_tree(root_dir)[source]

Return one deterministic file snapshot for content comparisons.

Parameters:

root_dir (Path)

Return type:

dict[str, bytes]

dsw_document_template_tool.template_transform.expand_template_dir(*, source_dir, output_dir, apply_local_patches=True)[source]

Expand one compact DSW template directory into a translation workspace.

Parameters:

  • source_dir (Path)

  • output_dir (Path)

  • apply_local_patches (bool)

Return type:

Path

dsw_document_template_tool.template_transform.compact_template_dir(*, source_dir, output_dir)[source]

Compact one expanded translation workspace back into DSW uploadable form.

Parameters:

  • source_dir (Path)

  • output_dir (Path)

Return type:

Path

dsw_document_template_tool.template_transform.explain_transform_workspace(source_dir)[source]

Render a concise rule trace from an expanded workspace manifest.

Parameters:

source_dir (Path)

Return type:

str

CLI Entry Point

CLI entrypoint for compact <-> expanded DSW template transforms.

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

Build the CLI argument parser.

Return type:

ArgumentParser

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

Run the selected transform command.

Return type:

None

Implementation Modules

These modules are implementation details, but they are intentionally documented for maintainers changing parser or rewrite behavior.

Shared models for template transform helpers.

exception dsw_document_template_tool._template_transform.models.TemplateTransformError[source]

Bases: RuntimeError

Raised when a template cannot be expanded or compacted safely.

Filesystem helpers for expanded template workspaces.

dsw_document_template_tool._template_transform.workspace.reset_dir(path)[source]

Replace one directory with an empty directory.

Parameters:

path (Path)

Return type:

None

dsw_document_template_tool._template_transform.workspace.validate_template_dir(source_dir)[source]

Ensure one directory looks like a DSW document template.

Parameters:

source_dir (Path)

Return type:

None

dsw_document_template_tool._template_transform.workspace.snapshot_tree(root_dir)[source]

Return one deterministic file snapshot for content comparisons.

Parameters:

root_dir (Path)

Return type:

dict[str, bytes]

dsw_document_template_tool._template_transform.workspace.rewrite_workspace_readme(*, source_dir, output_dir)[source]

Write the translator-facing README while preserving the upstream README.

Parameters:

  • source_dir (Path)

  • output_dir (Path)

Return type:

None

Low-level HTML/Jinja tokenization helpers for template transforms.

class dsw_document_template_tool._template_transform.scanner.SourceToken[source]

Bases: object

One lexed template token with original source offsets.

class dsw_document_template_tool._template_transform.scanner.AnnotationRegion[source]

Bases: object

One translatable source region in the expanded workspace.

dsw_document_template_tool._template_transform.scanner.lex_source_tokens(source_text)[source]

Tokenize one Jinja/HTML source string while preserving offsets.

Parameters:

source_text (str)

Return type:

list[SourceToken]

dsw_document_template_tool._template_transform.scanner.find_matching_tag_end(*, tokens, start_index)[source]

Find the matching close token for one opening HTML token.

Parameters:
Return type:

int | None

Small helpers for exact, reversible source rewrites.

class dsw_document_template_tool._template_transform.rewrite_rules.ReversibleReplacementGroup[source]

Bases: object

A named group of exact source rewrites.

The group ID is intentionally diagnostic-only. It gives template-specific rewrite modules a place to document why a set of replacements exists without changing the generated template output.

dsw_document_template_tool._template_transform.rewrite_rules.apply_reversible_replacement_groups(source_text, groups, *, source_file='', trace=None)[source]

Apply named exact replacement groups in order.

Parameters:
Return type:

str

dsw_document_template_tool._template_transform.rewrite_rules.apply_reversible_replacements(source_text, replacements)[source]

Apply exact replacements and preserve the original text for compaction.

Parameters:

  • source_text (str)

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

Return type:

str

dsw_document_template_tool._template_transform.rewrite_rules.wrap_reversible_branch_sentence_rewrite(*, original, replacement)[source]

Wrap replacement text with a marker containing the exact original text.

Parameters:

  • original (str)

  • replacement (str)

Return type:

str

Template profile identity and rewrite trace models.

class dsw_document_template_tool._template_transform.profile.TemplateIdentity[source]

Bases: object

Coordinates that select template-specific transform behavior.

property full_id: str

Return DSW-style template coordinates.

class dsw_document_template_tool._template_transform.profile.TransformContext[source]

Bases: object

Identity and source location available to one transform rule.

class dsw_document_template_tool._template_transform.profile.RewriteApplication[source]

Bases: object

One named rewrite group applied to one source file.

class dsw_document_template_tool._template_transform.profile.TransformTrace[source]

Bases: object

Collect deterministic diagnostics without changing rendered output.

record(*, group_id, rationale, source_file, match_count)[source]

Record a group only when it changed source text.

Parameters:

  • group_id (str)

  • rationale (str)

  • source_file (str)

  • match_count (int)

Return type:

None

to_manifest()[source]

Return stable JSON-compatible trace data.

Return type:

dict[str, object]

dsw_document_template_tool._template_transform.profile.read_template_identity(template_dir)[source]

Read required transform coordinates from template.json.

Parameters:

template_dir (Path)

Return type:

TemplateIdentity

Science Europe-specific reversible source rewrites.

dsw_document_template_tool._template_transform.science_europe.is_science_europe_template(identity)[source]

Return whether the local profile owns this template.

Parameters:

identity (TemplateIdentity)

Return type:

bool

dsw_document_template_tool._template_transform.science_europe.rewrite_science_europe_source(source_text, *, context, trace, phase)[source]

Apply the named Science Europe rewrite phase with trace metadata.

Parameters:
Return type:

str

dsw_document_template_tool._template_transform.science_europe.rewrite_science_europe_balanced_source_fragments(source_text, *, source_file='', trace=None)[source]

Rewrite exact upstream Science Europe fragments before generic expansion.

Parameters:
Return type:

str

dsw_document_template_tool._template_transform.science_europe.rewrite_science_europe_unbalanced_html_fragments(source_text, *, apply_localization_rewrites=True, source_file='', trace=None)[source]

Patch upstream Science Europe sentence fragments that generic HTML cannot see.

A few upstream fragments live inside large, unbalanced list-item wrappers, so the generic paragraph rewriter cannot safely discover their <p> boundaries. These replacements are still reversible: compacting restores the exact upstream text stored in the marker payload.

Parameters:

  • source_text (str)

  • apply_localization_rewrites (bool)

  • source_file (str)

  • trace (TransformTrace | None)

Return type:

str

Balanced exact rewrites for upstream Science Europe templates.

These rules preserve whole sentence-like HTML/Jinja regions before the generic expander runs. Long literals intentionally keep upstream formatting because exact text matching is part of the reversible transform contract.

dsw_document_template_tool._template_transform.science_europe_balanced_rules.rewrite_science_europe_balanced_source_fragments(source_text, *, source_file='', trace=None)[source]

Rewrite exact upstream Science Europe fragments before generic expansion.

Parameters:
Return type:

str

Unbalanced exact rewrites for upstream Science Europe templates.

These rules patch fragments that live inside larger unbalanced HTML/Jinja flows where the generic region scanner cannot safely infer complete boundaries. Long literals intentionally keep upstream formatting because exact text matching is part of the reversible transform contract.

dsw_document_template_tool._template_transform.science_europe_unbalanced_rules.rewrite_science_europe_unbalanced_html_fragments(source_text, *, apply_localization_rewrites=True, source_file='', trace=None)[source]

Patch upstream Science Europe sentence fragments that generic HTML cannot see.

A few upstream fragments live inside large, unbalanced list-item wrappers, so the generic paragraph rewriter cannot safely discover their <p> boundaries. These replacements are still reversible: compacting restores the exact upstream text stored in the marker payload.

Parameters:

  • source_text (str)

  • apply_localization_rewrites (bool)

  • source_file (str)

  • trace (TransformTrace | None)

Return type:

str