texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/core/templates/runtime.py

@@ -0,0 +1,347 @@
+"""Runtime helpers for binding LaTeX templates to rendered documents."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .base import WrappableTemplate
+from .loader import load_template
+from .manifest import (
+    DEFAULT_TEMPLATE_LANGUAGE,
+    TemplateError,
+    TemplateSlot,
+    _BABEL_LANGUAGE_ALIASES,
+)
+
+from texsmith.core.fragments import FRAGMENT_REGISTRY
+
+if TYPE_CHECKING:
+    from texsmith.adapters.latex.formatter import LaTeXFormatter
+
+
+@dataclass(slots=True)
+class TemplateRuntime:
+    """Resolved template metadata reused across conversions."""
+
+    instance: WrappableTemplate
+    name: str
+    engine: str | None
+    requires_shell_escape: bool
+    slots: dict[str, TemplateSlot]
+    default_slot: str
+    formatter_overrides: dict[str, Path]
+    base_level: int | None
+    required_partials: set[str] = field(default_factory=set)
+    extras: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class TemplateBinding:
+    """Binding between slot requests and a LaTeX template."""
+
+    runtime: TemplateRuntime | None
+    instance: WrappableTemplate | None
+    name: str | None
+    engine: str | None
+    requires_shell_escape: bool
+    formatter_overrides: dict[str, Path]
+    slots: dict[str, TemplateSlot]
+    default_slot: str
+    base_level: int | None
+    required_partials: set[str] = field(default_factory=set)
+
+    def slot_levels(self, *, offset: int = 0) -> dict[str, int]:
+        """Return the resolved base level for each slot."""
+        base = (self.base_level or 0) + offset
+        return {name: slot.resolve_level(base) for name, slot in self.slots.items()}
+
+    def apply_formatter_overrides(self, formatter: "LaTeXFormatter") -> None:
+        """Apply template-provided overrides to a formatter."""
+        for key, override_path in self.formatter_overrides.items():
+            formatter.override_template(key, override_path)
+
+
+def coerce_base_level(value: Any, *, allow_none: bool = True) -> int | None:
+    """Normalise base-level metadata to an integer or ``None``."""
+    if value is None:
+        if allow_none:
+            return None
+        raise TemplateError("Base level value is missing.")
+
+    if isinstance(value, bool):
+        raise TemplateError("Base level must be an integer, booleans are not supported.")
+
+    if isinstance(value, (int, float)):
+        return int(value)
+
+    if isinstance(value, str):
+        candidate = value.strip().lower()
+        if not candidate:
+            if allow_none:
+                return None
+            raise TemplateError("Base level value cannot be empty.")
+        alias_map = {
+            "part": -1,
+            "chapter": 0,
+            "section": 1,
+            "subsection": 2,
+        }
+        if candidate in alias_map:
+            return alias_map[candidate]
+        try:
+            return int(candidate)
+        except ValueError as exc:  # pragma: no cover - defensive
+            raise TemplateError(
+                f"Invalid base level '{value}'. Expected an integer value or one of "
+                f"{', '.join(alias_map)}."
+            ) from exc
+
+    raise TemplateError(
+        f"Base level should be provided as an integer value, got type '{type(value).__name__}'."
+    )
+
+
+def extract_base_level_override(overrides: Mapping[str, Any] | None) -> Any:
+    """Extract a base level override from template metadata overrides."""
+    if not overrides:
+        return None
+
+    press_section = overrides.get("press")
+    direct_candidate = overrides.get("base_level")
+    if direct_candidate is not None:
+        return direct_candidate
+    if isinstance(press_section, Mapping):
+        return press_section.get("base_level")
+    return None
+
+
+def build_template_overrides(front_matter: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Build template overrides from front matter while preserving metadata."""
+    if not front_matter or not isinstance(front_matter, Mapping):
+        return {}
+
+    overrides = dict(front_matter)
+    press_section = overrides.get("press")
+    if isinstance(press_section, Mapping):
+        overrides["press"] = dict(press_section)
+
+    fragments = overrides.get("fragments")
+    if fragments is None and isinstance(press_section, Mapping):
+        fragments = press_section.get("fragments")
+    if isinstance(fragments, list):
+        overrides["fragments"] = list(fragments)
+
+    callouts_section = overrides.get("callouts")
+    if callouts_section is None and isinstance(press_section, Mapping):
+        callouts_section = press_section.get("callouts")
+    if isinstance(callouts_section, Mapping):
+        overrides["callouts"] = dict(callouts_section)
+
+    callouts_style = overrides.get("callouts_style")
+    if callouts_style is None and isinstance(press_section, Mapping):
+        callouts_style = press_section.get("callouts_style")
+    if callouts_style is not None:
+        overrides["callout_style"] = callouts_style
+
+    base_override = overrides.get("base_level")
+    if base_override is None and isinstance(press_section, Mapping):
+        base_override = press_section.get("base_level")
+    if base_override is not None:
+        try:
+            overrides["base_level"] = coerce_base_level(base_override)
+        except TemplateError:
+            overrides["base_level"] = base_override
+
+    return overrides
+
+
+def extract_language_from_front_matter(
+    front_matter: Mapping[str, Any] | None,
+) -> str | None:
+    """Inspect front matter for language hints."""
+    if not isinstance(front_matter, Mapping):
+        return None
+
+    for key in ("language", "lang"):
+        value = front_matter.get(key)
+        if isinstance(value, str):
+            stripped = value.strip()
+            if stripped:
+                return stripped
+
+    press_entry = front_matter.get("press")
+    if isinstance(press_entry, Mapping):
+        for key in ("language", "lang"):
+            value = press_entry.get(key)
+            if isinstance(value, str):
+                stripped = value.strip()
+                if stripped:
+                    return stripped
+    return None
+
+
+def normalise_template_language(value: str | None) -> str | None:
+    """Normalise language codes and map them through babel aliases when available."""
+    if value is None:
+        return None
+
+    stripped = value.strip()
+    if not stripped:
+        return None
+
+    lowered = stripped.lower().replace("_", "-")
+    alias = _BABEL_LANGUAGE_ALIASES.get(lowered)
+    if alias:
+        return alias
+
+    primary = lowered.split("-", 1)[0]
+    alias = _BABEL_LANGUAGE_ALIASES.get(primary)
+    if alias:
+        return alias
+
+    if lowered.isalpha():
+        return lowered
+
+    return None
+
+
+def resolve_template_language(
+    explicit: str | None,
+    front_matter: Mapping[str, Any] | None,
+) -> str:
+    """Resolve the effective template language from CLI and front matter inputs."""
+    candidates = (
+        normalise_template_language(explicit),
+        normalise_template_language(extract_language_from_front_matter(front_matter)),
+    )
+
+    for candidate in candidates:
+        if candidate:
+            return candidate
+
+    return DEFAULT_TEMPLATE_LANGUAGE
+
+
+def load_template_runtime(template: str) -> TemplateRuntime:
+    """Resolve template metadata for repeated conversions."""
+    template_instance = load_template(template)
+
+    template_base = coerce_base_level(
+        template_instance.info.get_attribute_default("base_level"),
+    )
+
+    slots, default_slot = template_instance.info.resolve_slots()
+    formatter_overrides = dict(template_instance.iter_formatter_overrides())
+    extras_payload = getattr(template_instance, "extras", {}) or {}
+    extras = {key: value for key, value in extras_payload.items()}
+    declared_fragments = (
+        list(template_instance.info.fragments) if template_instance.info.fragments is not None else None
+    )
+    extras.setdefault(
+        "fragments",
+        declared_fragments if declared_fragments is not None else [],
+    )
+
+    return TemplateRuntime(
+        instance=template_instance,
+        name=template_instance.info.name,
+        engine=template_instance.info.engine,
+        requires_shell_escape=bool(template_instance.info.shell_escape),
+        slots=slots,
+        default_slot=default_slot,
+        formatter_overrides=formatter_overrides,
+        base_level=template_base,
+        required_partials=set(template_instance.info.required_partials or []),
+        extras=extras,
+    )
+
+
+def resolve_template_binding(
+    *,
+    template: str | None,
+    template_runtime: TemplateRuntime | None,
+    template_overrides: Mapping[str, Any],
+    slot_requests: Mapping[str, str],
+    warn: Callable[[str], None] | None = None,
+) -> tuple[TemplateBinding, dict[str, str]]:
+    """Resolve template runtime metadata and apply slot overrides."""
+    runtime = template_runtime
+    if runtime is None and template:
+        runtime = load_template_runtime(template)
+
+    if runtime is not None:
+        # Adjust base level for book parts when requested via overrides.
+        binding_base_level = runtime.base_level
+        part_flag = None
+        press_section = template_overrides.get("press")
+        if isinstance(template_overrides.get("part"), bool):
+            part_flag = template_overrides.get("part")
+        elif isinstance(press_section, Mapping) and isinstance(press_section.get("part"), bool):
+            part_flag = press_section.get("part")
+        if part_flag and runtime.name == "book":
+            binding_base_level = coerce_base_level("part")
+
+        binding = TemplateBinding(
+            runtime=runtime,
+            instance=runtime.instance,
+            name=runtime.name,
+            engine=runtime.engine,
+            requires_shell_escape=runtime.requires_shell_escape,
+            formatter_overrides=dict(runtime.formatter_overrides),
+            slots=runtime.slots,
+            default_slot=runtime.default_slot,
+            base_level=binding_base_level,
+            required_partials=set(runtime.required_partials),
+        )
+    else:
+        binding = TemplateBinding(
+            runtime=None,
+            instance=None,
+            name=None,
+            engine=None,
+            requires_shell_escape=False,
+            formatter_overrides={},
+            slots={"mainmatter": TemplateSlot(default=True)},
+            default_slot="mainmatter",
+            base_level=None,
+            required_partials=set(),
+        )
+
+    base_override = coerce_base_level(extract_base_level_override(template_overrides))
+    if base_override is not None:
+        binding.base_level = base_override
+
+    filtered: dict[str, str] = {}
+    for slot_name, selector in slot_requests.items():
+        if slot_name not in binding.slots:
+            if warn is not None:
+                template_hint = f"template '{binding.name}'" if binding.name else "the template"
+                warn(
+                    f"slot '{slot_name}' is not defined by {template_hint}; "
+                    f"content will remain in '{binding.default_slot}'."
+                )
+            continue
+        if binding.runtime is None:
+            if warn is not None:
+                warn(f"slot '{slot_name}' was requested but no template is selected; ignoring.")
+            continue
+        filtered[slot_name] = selector
+
+    return binding, filtered
+
+
+__all__ = [
+    "TemplateBinding",
+    "TemplateRuntime",
+    "build_template_overrides",
+    "coerce_base_level",
+    "extract_base_level_override",
+    "extract_language_from_front_matter",
+    "load_template_runtime",
+    "normalise_template_language",
+    "resolve_template_binding",
+    "resolve_template_language",
+]

texsmith/core/templates/text.py

@@ -0,0 +1,14 @@
+"""Utilities for post-processing generated LaTeX artefacts."""
+
+from __future__ import annotations
+
+import re
+
+
+def squash_blank_lines(text: str) -> str:
+    """Trim trailing whitespace and collapse runs of blank lines."""
+    trimmed = re.sub(r"[ \t]+(?=\r?\n|$)", "", text)
+    return re.sub(r"\n{3,}", "\n\n", trimmed)
+
+
+__all__ = ["squash_blank_lines"]

texsmith/core/templates/wrapper.py

@@ -0,0 +1,340 @@
+"""Shared helpers for wrapping LaTeX bodies with template metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+import re
+from typing import Any
+
+from jinja2 import meta
+
+from texsmith.core.callouts import DEFAULT_CALLOUTS, merge_callouts, normalise_callouts
+from texsmith.core.fragments import (
+    FRAGMENT_REGISTRY,
+    inject_fragment_attributes,
+    render_fragments,
+)
+from texsmith.core.templates import TemplateRuntime
+from texsmith.core.templates.manifest import TemplateError
+
+from texsmith.core.conversion.debug import ensure_emitter
+from texsmith.core.diagnostics import DiagnosticEmitter
+from texsmith.fonts.scripts import render_script_macros
+from ..context import DocumentState
+from .base import WrappableTemplate
+from .loader import copy_template_assets
+
+
+@dataclass(slots=True)
+class TemplateWrapResult:
+    """Result artefacts produced after wrapping LaTeX with a template."""
+
+    latex_output: str
+    template_context: dict[str, Any]
+    output_path: Path | None
+    asset_paths: list[Path] = field(default_factory=list)
+    asset_pairs: list[tuple[Path, Path]] = field(default_factory=list)
+    rendered_fragments: list[str] = field(default_factory=list)
+
+
+def wrap_template_document(
+    *,
+    template: WrappableTemplate,
+    default_slot: str,
+    slot_outputs: Mapping[str, str],
+    slot_output_overrides: Mapping[str, str] | None = None,
+    document_state: DocumentState,
+    template_overrides: Mapping[str, Any] | None,
+    output_dir: Path,
+    copy_assets: bool = True,
+    output_name: str | None = None,
+    bibliography_path: Path | None = None,
+    emitter: DiagnosticEmitter | None = None,
+    fragments: list[str] | None = None,
+    template_runtime: TemplateRuntime | None = None,
+) -> TemplateWrapResult:
+    """Wrap LaTeX content using a template and optional asset copying."""
+    output_dir = Path(output_dir).resolve()
+    resolved_slots = {name: value for name, value in slot_outputs.items()}
+    override_slots = (
+        {name: value for name, value in slot_output_overrides.items()}
+        if slot_output_overrides
+        else None
+    )
+    def _process_slot(value: Any) -> Any:
+        return value
+
+    main_slot_content = _process_slot(resolved_slots.get(default_slot, ""))
+    resolved_slots[default_slot] = main_slot_content
+    resolved_slots.setdefault(default_slot, main_slot_content)
+    processed_override_slots: dict[str, Any] | None = None
+    if override_slots is not None:
+        processed_override_slots = {
+            name: _process_slot(value) for name, value in override_slots.items()
+        }
+        processed_override_slots.setdefault(
+            default_slot, resolved_slots.get(default_slot, "")
+        )
+
+    overrides_payload = dict(template_overrides) if template_overrides else None
+    source_dir = None
+    overrides_press = overrides_payload.get("press") if overrides_payload else None
+    if isinstance(overrides_payload, Mapping):
+        raw_source_dir = overrides_payload.get("_source_dir") or overrides_payload.get("source_dir")
+        if isinstance(raw_source_dir, (str, Path)) and str(raw_source_dir):
+            source_dir = Path(raw_source_dir)
+    if source_dir is None and isinstance(overrides_press, Mapping):
+        source_dir_raw = overrides_press.get("_source_dir") or overrides_press.get("source_dir")
+        if source_dir_raw:
+            source_dir = Path(source_dir_raw)
+    fragment_names = list(fragments or [])
+    if not fragment_names:
+        if template_runtime is not None:
+            fragment_names = list(template_runtime.extras.get("fragments") or [])
+        else:
+            manifest_fragments = getattr(template.info, "fragments", None)
+            fragment_names = list(manifest_fragments or [])
+
+    template_context = template.prepare_context(
+        main_slot_content,
+        overrides=overrides_payload,
+    )
+    if isinstance(overrides_press, Mapping):
+        template_context.setdefault("press", overrides_press)
+    root_name: str | None = None
+    if output_name:
+        root_name = Path(output_name).stem
+    if root_name:
+        template_context.setdefault("root_filename", root_name)
+
+    for slot_name, raw_content in resolved_slots.items():
+        if slot_name == default_slot:
+            continue
+        processed_content = _process_slot(raw_content)
+        resolved_slots[slot_name] = processed_content
+        template_context[slot_name] = processed_content
+
+    template_context["index_entries"] = document_state.has_index_entries
+    index_terms = list(dict.fromkeys(getattr(document_state, "index_entries", [])))
+    template_context["has_index"] = bool(index_terms)
+    template_context["index_terms"] = [tuple(term) for term in index_terms]
+
+    registry_entries = index_terms
+    try:  # pragma: no cover - optional dependency
+        from texsmith.index import get_registry
+    except ModuleNotFoundError:
+        template_context["index_registry"] = [tuple(term) for term in registry_entries]
+    else:
+        snapshot = sorted(get_registry().snapshot())
+        template_context["index_registry"] = [tuple(term) for term in snapshot]
+    template_context["acronyms"] = document_state.acronyms.copy()
+    template_context["citations"] = list(document_state.citations)
+    template_context["bibliography_entries"] = document_state.bibliography
+
+    fragment_attributes: dict[str, Any] = {}
+    if fragment_names:
+        fragment_attributes = inject_fragment_attributes(
+            fragment_names,
+            context=template_context,
+            overrides=overrides_payload,
+            source_dir=source_dir,
+            declared_attribute_owners=(
+                template.info.attribute_owners() if hasattr(template, "info") else {}
+            ),
+        )
+
+    code_section = template_context.get("code")
+    code_engine = None
+    code_style = "bw"
+    if isinstance(code_section, Mapping):
+        raw_engine = code_section.get("engine")
+        code_engine = raw_engine if isinstance(raw_engine, str) else None
+        raw_style = code_section.get("style")
+        if isinstance(raw_style, str) and raw_style.strip():
+            code_style = raw_style.strip()
+    elif isinstance(code_section, str):
+        code_engine = code_section
+    code_engine = (code_engine or "pygments").strip().lower()
+    template_context["code_engine"] = code_engine or "pygments"
+    template_context.setdefault("code_style", code_style)
+    if "code" not in template_context:
+        template_context["code"] = {
+            "engine": template_context["code_engine"],
+            "style": template_context["code_style"],
+        }
+    elif isinstance(template_context["code"], dict):
+        template_context["code"].setdefault("style", template_context["code_style"])
+    if code_engine == "pygments" and getattr(document_state, "pygments_styles", {}):
+        styles = getattr(document_state, "pygments_styles", {})
+        template_context["pygments_style_defs"] = "\n".join(styles.values())
+
+    template_context["requires_shell_escape"] = bool(
+        template_context.get("requires_shell_escape", False)
+        or getattr(document_state, "requires_shell_escape", False)
+        or (template_runtime.requires_shell_escape if template_runtime else False)
+        or code_engine == "minted"
+    )
+    if template_runtime and template_runtime.engine:
+        template_context.setdefault("latex_engine", template_runtime.engine)
+
+    emitter_obj = ensure_emitter(emitter)
+
+    if document_state.citations and bibliography_path is not None:
+        template_context["bibliography"] = bibliography_path.stem
+        template_context["bibliography_resource"] = bibliography_path.name
+        template_context.setdefault("bibliography_style", "numeric")
+
+    template_context["ts_uses_callouts"] = bool(getattr(document_state, "callouts_used", False))
+
+    # Render fragments and inject declarations into template variables.
+    requested_fragments = list(fragment_names)
+    callout_overrides = overrides_payload.get("callouts") if overrides_payload else None
+    callouts_defs = normalise_callouts(
+        merge_callouts(
+            DEFAULT_CALLOUTS, callout_overrides if isinstance(callout_overrides, Mapping) else None
+        )
+    )
+    template_context.setdefault("callouts_definitions", callouts_defs)
+    variable_injections: dict[str, list[str]] = {}
+    fragment_providers: dict[str, list[str]] = {}
+    declared_slots, _default_slot = template.info.resolve_slots()
+    declared_slot_names = set(declared_slots.keys())
+    declared_vars = _discover_template_variables(template)
+    rendered_fragments: set[str] = set()
+    if fragment_names:
+        fragment_context: dict[str, Any] = template_context
+
+        def _reassert_effective_emoji_mode(target: dict[str, Any]) -> None:
+            effective_mode = target.get("_texsmith_effective_emoji_mode")
+            if not effective_mode:
+                return
+            target["emoji"] = effective_mode
+            target["emoji_mode"] = effective_mode
+            fonts_section = target.get("fonts")
+            if isinstance(fonts_section, Mapping):
+                if isinstance(fonts_section, dict):
+                    fonts_section["emoji"] = effective_mode
+                else:
+                    updated_fonts = dict(fonts_section)
+                    updated_fonts["emoji"] = effective_mode
+                    target["fonts"] = updated_fonts
+
+        if overrides_payload:
+            for key, value in overrides_payload.items():
+                if key in fragment_attributes:
+                    continue
+                fragment_context.setdefault(key, value)
+            press_section = overrides_payload.get("press")
+            if isinstance(press_section, Mapping):
+                for key, value in press_section.items():
+                    fragment_context.setdefault(key, value)
+            _reassert_effective_emoji_mode(fragment_context)
+        else:
+            _reassert_effective_emoji_mode(fragment_context)
+        fragment_result = render_fragments(
+            fragment_names,
+            context=fragment_context,
+            output_dir=output_dir,
+            source_dir=source_dir,
+            overrides=overrides_payload,
+            declared_slots=declared_slot_names,
+            declared_variables=declared_vars,
+            template_name=template.info.name,
+        )
+        variable_injections = fragment_result.variable_injections
+        fragment_providers = fragment_result.providers
+        for provider_list in fragment_providers.values():
+            rendered_fragments.update(provider_list)
+    template_context["requested_fragments"] = requested_fragments
+    template_context["fragments"] = sorted(rendered_fragments)
+
+    if variable_injections:
+        for variable_name, injections in variable_injections.items():
+            base = template_context.get(variable_name, "")
+            parts: list[str] = [base] if base else []
+            parts.extend(injections)
+            template_context[variable_name] = "\n".join(part for part in parts if part)
+
+    script_macros = render_script_macros(getattr(document_state, "script_usage", []))
+    if script_macros:
+        existing_extra = template_context.get("extra_packages", "")
+        template_context["extra_packages"] = "\n".join(
+            part for part in (existing_extra, script_macros) if part
+        )
+        template_context["script_macros"] = script_macros
+
+    final_slots = processed_override_slots if processed_override_slots is not None else resolved_slots
+    for slot_name, value in final_slots.items():
+        template_context[slot_name] = value
+    main_slot_content = final_slots.get(default_slot, main_slot_content)
+
+    # Append pdfLaTeX-specific packages when not using LuaLaTeX.
+    extra_lines = [line for line in template_context.get("extra_packages", "").splitlines() if line]
+    engine = str(template_context.get("latex_engine") or "").strip().lower()
+    if engine and engine != "lualatex":
+        for package in template_context.get("pdflatex_extra_packages") or []:
+            if package:
+                extra_lines.append(f"\\usepackage{{{package}}}")
+    template_context["extra_packages"] = "\n".join(extra_lines)
+
+    if document_state.citations and bibliography_path is not None:
+        template_context["bibliography"] = bibliography_path.stem
+        template_context["bibliography_resource"] = bibliography_path.name
+        template_context.setdefault("bibliography_style", "plain")
+
+    latex_output = template.wrap_document(
+        main_slot_content,
+        context=template_context,
+    )
+    latex_output = _squash_blank_lines(latex_output)
+
+    asset_paths: list[Path] = []
+    asset_pairs: list[tuple[Path, Path]] = []
+    if copy_assets:
+        declared_assets = list(template.iter_assets())
+        asset_paths = copy_template_assets(
+            template,
+            output_dir,
+            context=template_context,
+            overrides=overrides_payload,
+            assets=declared_assets,
+        )
+        asset_pairs = [(entry.source, dest) for entry, dest in zip(declared_assets, asset_paths)]
+
+    output_path: Path | None = None
+    if output_name:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        output_path = output_dir / output_name
+        output_path.write_text(latex_output, encoding="utf-8")
+        template_context.setdefault("root_filename", output_path.stem)
+
+    return TemplateWrapResult(
+        latex_output=latex_output,
+        template_context=template_context,
+        output_path=output_path,
+        asset_paths=asset_paths,
+        asset_pairs=asset_pairs,
+        rendered_fragments=sorted(rendered_fragments),
+    )
+
+
+def _discover_template_variables(template: WrappableTemplate) -> set[str] | None:
+    """Return undeclared variables referenced by the template entrypoint."""
+    env = template.environment
+    try:
+        source, _, _ = env.loader.get_source(env, template.info.entrypoint)
+    except Exception:
+        return None
+    parsed = env.parse(source)
+    return set(meta.find_undeclared_variables(parsed))
+
+
+def _squash_blank_lines(text: str) -> str:
+    """Normalise LaTeX output by trimming trailing whitespace and blank lines."""
+    trimmed = re.sub(r"[ \t]+(?=\r?\n|$)", "", text)
+    return re.sub(r"\n{3,}", "\n\n", trimmed)
+
+
+__all__ = ["TemplateWrapResult", "wrap_template_document"]