carbotek 0.1.0__py3-none-any.whl

carbotek/__init__.py

@@ -0,0 +1,32 @@
+# pyright: strict, reportPrivateUsage=false
+"""carbotek: DOCX and XLSX templates with Carbone-style markers rendered to DOCX, XLSX or PDF (dxpdf).
+
+import carbotek
+docx = carbotek.render(template_bytes, {"name": "Ann"}, {"lang": "ru"})
+pdf = carbotek.render_pdf(template_bytes, data)
+engine = carbotek.Engine(cache_size=16)   # own compile cache, e.g. for benchmarks
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .api import Engine, default_engine, render, render_pdf
+from .errors import CarbotekError
+from .options import RenderOptions
+from .pdf import convert_docx_to_pdf
+
+# The single source is native/Cargo.toml; the release workflow sets it from the git tag.
+try:
+    __version__ = version("carbotek")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = [
+    "CarbotekError",
+    "Engine",
+    "RenderOptions",
+    "__version__",
+    "convert_docx_to_pdf",
+    "default_engine",
+    "render",
+    "render_pdf",
+]

carbotek/__main__.py

@@ -0,0 +1,6 @@
+# pyright: strict, reportPrivateUsage=false
+"""``python -m carbotek`` runs the command line interface."""
+
+from .cli import main
+
+raise SystemExit(main())

carbotek/_native.pyi

@@ -0,0 +1,14 @@
+from typing import Any, Final
+
+API_VERSION: Final[int]
+PACKAGE_VERSION: Final[str]
+OPERATIONS: Final[dict[str, int]]
+
+class PlainSection:
+    def __init__(self, literals: list[str], slots: list[tuple[int, list[tuple[int, str, str, str, str]]]]) -> None: ...
+    def render(self, rows: object) -> str | None: ...
+    def render_bytes(self, rows: object) -> bytes | None: ...
+
+def digit_currency_cents(value: Any) -> str | None: ...
+def join_utf8(parts: list[str | bytes]) -> bytes: ...
+def decode_data_uri(value: Any) -> bytes | None: ...

carbotek/_native_adapter.py

@@ -0,0 +1,100 @@
+# pyright: strict
+"""Optional compiled section backend; the public rendering API stays in Python.
+
+``CARBOTEK_NATIVE`` is read once, when carbotek is imported: ``0``/``false``/``off``/``no`` keeps
+every render on the Python path, ``1``/``true``/``on``/``yes`` turns a missing extension into an
+import error, and any other value (the default) uses the extension when it is installed.
+"""
+
+import os
+import re
+from collections.abc import Callable
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Protocol
+
+# Operation codes of a native section slot part, shared with native/src/lib.rs (OPERATIONS).
+OP_LITERAL, OP_FIELD, OP_ISO_DATE, OP_RU_NUMBER, OP_IF_EQUAL, OP_CENTS = range(6)
+OPERATIONS = {
+    "literal": OP_LITERAL,
+    "field": OP_FIELD,
+    "iso_date": OP_ISO_DATE,
+    "ru_number": OP_RU_NUMBER,
+    "if_equal": OP_IF_EQUAL,
+    "cents": OP_CENTS,
+}
+
+type SlotPart = tuple[int, str, str, str, str]
+
+
+class PlainSection(Protocol):
+    def render(self, rows: list[object]) -> str | None: ...
+    def render_bytes(self, rows: list[object]) -> bytes | None: ...
+
+
+class _Native(Protocol):
+    """The functions of ``carbotek._native`` (see ``_native.pyi``)."""
+
+    def PlainSection(self, literals: list[str], slots: list[tuple[int, list[SlotPart]]]) -> PlainSection: ...
+    def digit_currency_cents(self, value: Any) -> str | None: ...
+    def join_utf8(self, parts: list[str | bytes]) -> bytes: ...
+    def decode_data_uri(self, value: Any) -> bytes | None: ...
+
+
+def _load(setting: str) -> _Native | None:
+    if setting in {"0", "false", "off", "no"}:
+        return None
+    try:
+        from carbotek import _native  # pyright: ignore[reportMissingModuleSource] - optional extension
+    except ImportError:
+        if setting in {"1", "true", "on", "yes"}:
+            raise
+        return None
+    try:
+        installed_version = version("carbotek")
+    except PackageNotFoundError:
+        installed_version = None
+    native_version = getattr(_native, "PACKAGE_VERSION", None)
+    compatible = getattr(_native, "API_VERSION", None) == 2 and getattr(_native, "OPERATIONS", None) == OPERATIONS
+    if installed_version is not None:
+        normalized = re.sub(
+            r"-(alpha|beta|rc)\.?(\d+)$",
+            lambda match: {"alpha": "a", "beta": "b", "rc": "rc"}[match[1]] + match[2],
+            native_version or "",
+        )
+        compatible = compatible and normalized == installed_version
+    if not compatible:
+        if setting in {"1", "true", "on", "yes"}:
+            raise ImportError(
+                "carbotek._native is incompatible with this Python adapter; reinstall or rebuild carbotek"
+            )
+        return None
+    return _native
+
+
+# Tests switch backends by replacing this attribute (monkeypatch), not the environment.
+_native: _Native | None = _load(os.environ.get("CARBOTEK_NATIVE", "").strip().lower())
+
+
+def native_available() -> bool:
+    return _native is not None
+
+
+def compile_plain_section(literals: list[str], slots: list[tuple[int, list[SlotPart]]]) -> PlainSection | None:
+    native = _native
+    return native.PlainSection(literals, slots) if native is not None else None
+
+
+def native_digit_currency_cents(value: Any) -> str | None:
+    native = _native
+    return native.digit_currency_cents(value) if native is not None else None
+
+
+def native_utf8_joiner() -> Callable[[list[str | bytes]], bytes] | None:
+    """``join_utf8``, chosen before any section field is evaluated; None for the Python path."""
+    native = _native
+    return native.join_utf8 if native is not None else None
+
+
+def native_decode_data_uri(value: Any) -> bytes | None:
+    native = _native
+    return native.decode_data_uri(value) if native is not None else None

carbotek/api.py

@@ -0,0 +1,120 @@
+# pyright: strict, reportPrivateUsage=false
+"""Public synchronous API: module-level helpers over a shared :class:`Engine`."""
+
+from collections.abc import Mapping
+from functools import lru_cache
+from io import BytesIO
+from typing import Any
+from zipfile import BadZipFile, ZipFile
+
+from .docx.renderer import DocxTextRenderer
+from .errors import FeatureUnavailable, ValidationError
+from .features.fetch import ImageSourceConfig
+from .opc import OpcTemplateRepository
+from .options import RenderOptions
+from .pdf import convert_docx_to_pdf
+from .pipeline.compile import CompiledTemplate, CompiledTemplateCache
+from .pipeline.document import RenderDocument
+from .typing_helpers import is_list, is_mapping
+
+type Data = Mapping[str, Any] | list[Any]
+type Options = RenderOptions | Mapping[str, Any] | None
+
+
+class Engine:
+    """A renderer with its own template caches; reuse one instance to benefit from the compile cache.
+
+    ``cache_size``/``cache_bytes`` bound the compiled-template LRU (0 disables caching);
+    ``image_sources`` configures remote/local image loading (default: data URIs only).
+    """
+
+    def __init__(
+        self,
+        *,
+        cache_size: int = 64,
+        cache_bytes: int = 256 * 1024 * 1024,
+        image_sources: ImageSourceConfig | None = None,
+    ) -> None:
+        if image_sources is not None and not isinstance(image_sources, ImageSourceConfig):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ValidationError("image_sources must be ImageSourceConfig or None")
+        self._document = RenderDocument(
+            OpcTemplateRepository(),
+            DocxTextRenderer(),
+            image_sources,
+            CompiledTemplateCache(capacity=cache_size, max_bytes=cache_bytes),
+        )
+
+    def compile(self, template: bytes, options: Options = None) -> CompiledTemplate:
+        """Validate and prepare a template using the same compile cache as render()."""
+        if not isinstance(template, bytes):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise ValidationError("template must be bytes")
+        return self._document.compile(template, _options(options))
+
+    def render(self, template: bytes, data: Data, options: Options = None) -> bytes:
+        """Render a DOCX template into a DOCX document, an XLSX template into an XLSX workbook."""
+        return self._execute(template, data, options, rasterize_svg=False, image_dpi=220)
+
+    def render_pdf(self, template: bytes, data: Data, options: Options = None, *, image_dpi: int = 220) -> bytes:
+        """Render a DOCX template and convert the result to PDF with dxpdf (XLSX has no PDF output)."""
+        if type(image_dpi) is not int or not 1 <= image_dpi <= 2400:
+            raise ValidationError("image_dpi must be an integer between 1 and 2400")
+        if not isinstance(template, bytes):  # pyright: ignore[reportUnnecessaryIsInstance] - public API guard
+            raise ValidationError("template must be bytes")
+        if _is_workbook(template):
+            raise FeatureUnavailable("PDF output is only available for DOCX templates (XLSX needs LibreOffice)")
+        document = self._execute(template, data, options, rasterize_svg=True, image_dpi=image_dpi)
+        return convert_docx_to_pdf(document, image_dpi=image_dpi)
+
+    @property
+    def metrics(self) -> dict[str, int | float]:
+        """Compile cache metrics: size, bytes, hits, misses, hit_rate."""
+        return self._document.metrics
+
+    def _execute(self, template: bytes, data: Data, options: Options, *, rasterize_svg: bool, image_dpi: int) -> bytes:
+        if not isinstance(template, bytes):  # pyright: ignore[reportUnnecessaryIsInstance] - public API guard
+            raise ValidationError("template must be bytes")
+        if not isinstance(data, Mapping | list) or (  # pyright: ignore[reportUnnecessaryIsInstance] - public API guard
+            is_list(data) and any(not is_mapping(item) for item in data)
+        ):
+            raise ValidationError("data must be a mapping or list of mappings")
+        return self._document.execute(
+            template, data, _options(options), rasterize_svg=rasterize_svg, image_dpi=image_dpi
+        )
+
+
+@lru_cache(maxsize=1)
+def default_engine() -> Engine:
+    """The process-wide engine behind :func:`render` and :func:`render_pdf`."""
+    return Engine()
+
+
+def render(template: bytes, data: Data, options: Options = None) -> bytes:
+    """Render a DOCX template into a DOCX document, an XLSX template into an XLSX workbook."""
+    return default_engine().render(template, data, options)
+
+
+def render_pdf(template: bytes, data: Data, options: Options = None, *, image_dpi: int = 220) -> bytes:
+    """Render a DOCX template and convert the resulting package to PDF."""
+    return default_engine().render_pdf(template, data, options, image_dpi=image_dpi)
+
+
+def _is_workbook(template: bytes) -> bool:
+    """Whether the template is an XLSX package (checked before any rendering work)."""
+    try:
+        with ZipFile(BytesIO(template)) as archive:
+            names = archive.namelist()
+    except BadZipFile, ValueError:
+        return False  # rejected with the engine's own error by the render
+    return "word/document.xml" not in names and any(name.startswith("xl/") for name in names)
+
+
+def _options(options: Options) -> RenderOptions:
+    if options is None:
+        return RenderOptions.create()
+    if isinstance(options, RenderOptions):
+        return options
+    if not is_mapping(options):
+        raise ValidationError("options must be a mapping or RenderOptions")
+    if any(not isinstance(key, str) for key in options):  # pyright: ignore[reportUnnecessaryIsInstance]
+        raise ValidationError("option names must be strings")
+    return RenderOptions.create(**options)

carbotek/cache.py

@@ -0,0 +1,17 @@
+# pyright: strict
+"""Explicit process-cache reset for cold benchmark runs."""
+
+import sys
+
+
+def clear_module_caches() -> None:
+    """Clear every loaded Carbotek functools cache, including the shared formatter registry."""
+    cleared: set[int] = set()
+    for name, module in tuple(sys.modules.items()):
+        if module is None or not name.startswith("carbotek."):  # pyright: ignore[reportUnnecessaryComparison]
+            continue
+        for value in tuple(vars(module).values()):
+            clear = getattr(value, "cache_clear", None)
+            if callable(clear) and id(value) not in cleared:
+                clear()
+                cleared.add(id(value))

carbotek/cli.py

@@ -0,0 +1,195 @@
+# pyright: strict, reportPrivateUsage=false
+"""Command line interface.
+
+    carbotek render TEMPLATE DATA [-o OUT] [--pdf] [--lang ru] [--timezone Europe/Moscow] [--options JSON]
+    carbotek bench  TEMPLATE DATA [-n 20] [--warmup 1] [--pdf] [--no-cache] [--profile]
+    carbotek markers TEMPLATE
+
+``DATA`` is a JSON file (``-`` reads stdin). ``--options`` takes :meth:`RenderOptions.create`
+keywords as JSON (``{"complement": {...}, "currency": {"source": "EUR"}, ...}``).
+"""
+
+import argparse
+import json
+import statistics
+import sys
+import time
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .api import Engine
+from .cache import clear_module_caches
+from .errors import CarbotekError, ValidationError
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    arguments = parser.parse_args(argv)
+    try:
+        return int(arguments.handler(arguments))
+    except CarbotekError as error:
+        sys.stderr.write(f"{error.code}: {error}\n")
+        return 2
+    except (OSError, json.JSONDecodeError) as error:
+        sys.stderr.write(f"error: {error}\n")
+        return 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="carbotek", description="Render DOCX and XLSX templates with Carbotek markers."
+    )
+    parser.add_argument("--version", action="version", version=f"carbotek {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    render = commands.add_parser("render", help="render one document")
+    _input_arguments(render)
+    render.add_argument("-o", "--output", type=Path, help="output file (default: TEMPLATE stem + .out.docx/.xlsx/.pdf)")
+    render.set_defaults(handler=_render)
+
+    bench = commands.add_parser("bench", help="measure repeated renders of one template")
+    _input_arguments(bench)
+    bench.add_argument("-n", "--iterations", type=int, default=20, help="measured renders (default 20)")
+    bench.add_argument("--warmup", type=int, default=1, help="unmeasured renders first (default 1)")
+    bench.add_argument(
+        "--no-cache", action="store_true", help="clear module caches and create a new engine for every render"
+    )
+    bench.add_argument("--profile", action="store_true", help="print the cProfile top 25 of the measured renders")
+    bench.add_argument("--json", action="store_true", help="print the result as JSON")
+    bench.set_defaults(handler=_bench)
+
+    markers = commands.add_parser("markers", help="list the markers of a template after normalization")
+    markers.add_argument("template", type=Path)
+    markers.set_defaults(handler=_markers)
+    return parser
+
+
+def _input_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("template", type=Path, help="DOCX or XLSX template")
+    parser.add_argument("data", help="JSON data file, or - for stdin")
+    parser.add_argument("--pdf", action="store_true", help="convert the result to PDF (dxpdf)")
+    parser.add_argument("--image-dpi", type=int, default=220, help="PDF image DPI (default 220)")
+    parser.add_argument("--lang", help="document language (default ru)")
+    parser.add_argument("--timezone", help="IANA time zone (default Europe/Moscow)")
+    parser.add_argument("--options", default="{}", help="RenderOptions.create keywords as JSON")
+
+
+def _load(arguments: argparse.Namespace) -> tuple[bytes, Any, dict[str, Any]]:
+    template = Path(arguments.template).read_bytes()
+    raw = sys.stdin.read() if arguments.data == "-" else Path(arguments.data).read_text(encoding="utf-8")
+    options: dict[str, Any] = json.loads(arguments.options)
+    if not isinstance(options, dict):  # pyright: ignore[reportUnnecessaryIsInstance] - JSON may be an array
+        raise ValidationError("--options must contain a JSON object")
+    if arguments.lang:
+        options["lang"] = arguments.lang
+    if arguments.timezone:
+        options["timezone"] = arguments.timezone
+    return template, json.loads(raw), options
+
+
+def _renderer(engine: Engine, arguments: argparse.Namespace) -> Callable[[bytes, Any, dict[str, Any]], bytes]:
+    if arguments.pdf:
+        return lambda template, data, options: engine.render_pdf(template, data, options, image_dpi=arguments.image_dpi)
+    return engine.render
+
+
+def _render(arguments: argparse.Namespace) -> int:
+    template, data, options = _load(arguments)
+    started = time.perf_counter()
+    engine = Engine()
+    compiled = engine.compile(template, options)
+    result = _renderer(engine, arguments)(template, data, options)
+    elapsed = time.perf_counter() - started
+    suffix = "." + compiled.package.kind
+    output: Path = arguments.output or Path(arguments.template).with_suffix(
+        ".out.pdf" if arguments.pdf else ".out" + suffix
+    )
+    output.write_bytes(result)
+    sys.stderr.write(f"{output} ({len(result)} bytes, {elapsed * 1000:.1f} ms)\n")
+    return 0
+
+
+def _bench(arguments: argparse.Namespace) -> int:
+    template, data, options = _load(arguments)
+    shared = Engine()
+
+    def once() -> float:
+        if arguments.no_cache:
+            clear_module_caches()
+        started = time.perf_counter()
+        engine = Engine(cache_size=0) if arguments.no_cache else shared
+        _renderer(engine, arguments)(template, data, options)
+        return time.perf_counter() - started
+
+    cold = once()
+    for _ in range(max(arguments.warmup - 1, 0)):
+        once()
+    profiler = None
+    if arguments.profile:
+        import cProfile
+
+        profiler = cProfile.Profile()
+        profiler.enable()
+    timings = [once() for _ in range(max(arguments.iterations, 1))]
+    if profiler is not None:
+        profiler.disable()
+    result = _summary(cold, timings, None if arguments.no_cache else shared.metrics)
+    if arguments.json:
+        sys.stdout.write(json.dumps(result) + "\n")
+    else:
+        # Read the package kind after timing; metadata must not warm a measured cold run.
+        kind = "pdf" if arguments.pdf else Engine(cache_size=0).compile(template, options).package.kind
+        sys.stdout.write(
+            f"{arguments.template.name}: {kind}, n={result['iterations']}"
+            f"{', no cache' if arguments.no_cache else ''}\n"
+            f"  cold {result['cold_ms']:.1f} ms | mean {result['mean_ms']:.1f} | p50 {result['p50_ms']:.1f}"
+            f" | p95 {result['p95_ms']:.1f} | min {result['min_ms']:.1f} | max {result['max_ms']:.1f} ms"
+            f" | {result['per_second']:.1f}/s\n"
+        )
+        if result.get("cache"):
+            sys.stdout.write(f"  compile cache: {result['cache']}\n")
+    if profiler is not None:
+        import pstats
+
+        pstats.Stats(profiler, stream=sys.stderr).sort_stats("cumulative").print_stats(25)
+    return 0
+
+
+def _summary(cold: float, timings: list[float], cache: dict[str, int | float] | None) -> dict[str, Any]:
+    ordered = sorted(timings)
+    mean = statistics.fmean(ordered)
+    return {
+        "iterations": len(ordered),
+        "cold_ms": cold * 1000,
+        "mean_ms": mean * 1000,
+        "p50_ms": statistics.median(ordered) * 1000,
+        "p95_ms": ordered[min(len(ordered) - 1, round(0.95 * (len(ordered) - 1)))] * 1000,
+        "min_ms": ordered[0] * 1000,
+        "max_ms": ordered[-1] * 1000,
+        "per_second": 1 / mean if mean else 0.0,
+        "cache": cache,
+    }
+
+
+def _markers(arguments: argparse.Namespace) -> int:
+    from .markers import scan
+    from .ooxml.xml import parse_xml
+
+    compiled = Engine().compile(arguments.template.read_bytes())
+    package = compiled.package
+    for name in package.order:
+        part = package.parts[name]
+        if not part.is_xml:
+            continue
+        for node in parse_xml(part.content).iter():
+            texts = [*node.attrib.values(), node.text or ""] if isinstance(node.tag, str) else []
+            for text in texts:
+                for occurrence in scan(str(text), include_aliases=True):
+                    sys.stdout.write(f"{name}\t{occurrence.raw}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

carbotek/docx/__init__.py

@@ -0,0 +1,2 @@
+# pyright: strict, reportPrivateUsage=false
+"""DOCX-specific tree operations, kept separate from the domain model."""

carbotek/docx/blocks.py

@@ -0,0 +1,90 @@
+# pyright: strict, reportPrivateUsage=false
+"""Structural removal of hidden conditional blocks (``showBegin``/``hideBegin`` ... ``End``).
+
+JS (``extracter.findAndSetValidPositionOfConditionalBlocks_v5`` with
+``parser.findSafeConditionalBlockPosition_v5``) drops the XML between the two markers, split into
+balanced pieces: elements partly inside keep their tags, elements wholly inside go. The tree
+renderer records where hidden blocks start and end during its text pass and removes the elements
+afterwards; the string renderer of loop sections cuts the same elements (``strings.py``).
+"""
+
+from lxml import etree  # pyright: ignore[reportAttributeAccessIssue] lxml has incomplete stubs.
+
+
+class HiddenBlocks:
+    """Hidden conditional blocks of a pass, removed like ``findSafeConditionalBlockPosition_v5``.
+
+    Everything between the begin and the end marker goes; an element holding the begin marker at
+    its very start (and closing before the end marker), or the end marker at its very end (and
+    opening after the begin marker), goes whole, climbing while the element is the first (last)
+    child of its parent. A block inside one text only loses its text.
+    """
+
+    def __init__(self) -> None:
+        self.events: list[tuple[str, str]] = []
+        self._open: tuple[etree._Element, bool] | None = None
+        self._ranges: list[tuple[etree._Element, bool, etree._Element, bool]] = []
+
+    def consume(self, node: etree._Element) -> None:
+        for kind, text in self.events:
+            if kind == "begin":
+                if self._open is None:
+                    self._open = (node, text == "")
+            elif self._open is not None:
+                begin, empty_before = self._open
+                self._open = None
+                if begin is not node:
+                    self._ranges.append((begin, empty_before, node, text == ""))
+        self.events.clear()
+
+    def remove(self) -> None:
+        removals: list[etree._Element] = []
+        for begin, empty_before, end, empty_after in self._ranges:
+            removals.extend(hidden_range(begin, empty_before, end, empty_after))
+        for element in {id(item): item for item in removals}.values():
+            parent = element.getparent()
+            if parent is not None and not any(ancestor in removals for ancestor in element.iterancestors()):
+                parent.remove(element)
+        self._ranges.clear()
+
+
+def hidden_range(
+    begin: etree._Element, empty_before: bool, end: etree._Element, empty_after: bool
+) -> list[etree._Element]:
+    """Elements strictly inside a hidden block (see ``HiddenBlocks``)."""
+    begin_path = [begin, *begin.iterancestors()]
+    end_path = [end, *end.iterancestors()]
+    end_set = set(end_path)
+    common = next((node for node in begin_path if node in end_set), None)
+    if common is None:
+        return []
+    begin_path = begin_path[: begin_path.index(common)]
+    end_path = end_path[: end_path.index(common)]
+    if not begin_path or not end_path:
+        return []  # one holds the other: no element lies between
+    removals: list[etree._Element] = []
+    siblings = list(common)
+    first, last = siblings.index(begin_path[-1]), siblings.index(end_path[-1])
+    removals.extend(siblings[first + 1 : last])
+    for node in begin_path[:-1]:
+        removals.extend(node.itersiblings())
+    for node in end_path[:-1]:
+        removals.extend(node.itersiblings(preceding=True))
+    if empty_before:
+        removals.append(_climb(begin_path, preceding=True))
+    if empty_after:
+        removals.append(_climb(end_path, preceding=False))
+    return removals
+
+
+def _climb(path: list[etree._Element], *, preceding: bool) -> etree._Element:
+    """The highest element of ``path`` the marker opens (closes) directly, with no content before (after)."""
+    top = path[0]
+    for node in path[1:]:
+        child = top
+        if preceding and (node.text or child.getprevious() is not None):
+            break
+        if not preceding and (child.tail or child.getnext() is not None):
+            break
+        top = node
+    return top

carbotek/docx/dialect.py

@@ -0,0 +1,73 @@
+# pyright: strict, reportPrivateUsage=false
+"""The XML vocabulary a templated part is written in: WordprocessingML or SpreadsheetML.
+
+The marker engine (fields, loops, directives, string sections) only needs to know which elements
+hold template text and what a paragraph and a run look like; the rest is shared. The dialect of the
+part being rendered is a context variable set by ``DocxTextRenderer.render_tree``.
+"""
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from lxml import etree  # pyright: ignore[reportAttributeAccessIssue] lxml has incomplete stubs.
+
+from carbotek.ooxml.ns import NAMESPACES, qn
+from carbotek.render_state import StateSlot
+
+SHEET_NAMESPACE = "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
+
+
+class _AnyElement(tuple[Any, ...]):
+    """``texts`` of a dialect where the text of any element can hold markers (SpreadsheetML).
+
+    ``element.iter(*texts)`` visits every element (not comments), ``tag in texts`` holds for them.
+    """
+
+    def __contains__(self, tag: object) -> bool:
+        return isinstance(tag, str)
+
+
+@dataclass(frozen=True, slots=True)
+class Dialect:
+    name: str
+    # Elements whose text can hold markers (``iter(*texts)``, ``tag in texts``).
+    texts: tuple[Any, ...]
+    # The element a new text run gets, its paragraph and run.
+    text: str
+    paragraph: str
+    run: str
+    run_properties: str
+    namespace: str
+
+    def marker_texts(self, element: etree._Element) -> list[etree._Element]:
+        """Text elements of the subtree holding a ``{`` (XPath in C instead of a Python walk)."""
+        return cast(list[etree._Element], _MARKER_TEXTS[self.name](element))
+
+    def emptied_texts(self, element: etree._Element, marker: str) -> list[etree._Element]:
+        """Text elements of the subtree whose whole text is ``marker``."""
+        return cast(list[etree._Element], _EMPTIED_TEXTS[self.name](element, empty=marker))
+
+
+WORD = Dialect("docx", (qn("w:t"),), qn("w:t"), qn("w:p"), qn("w:r"), qn("w:rPr"), NAMESPACES["w"])
+# JS renders a marker in the text of any element of a workbook part: cells (<t>, <v>, <f>), header
+# and footer, defined names, conditional formats, data validations, comments.
+SHEET = Dialect(
+    "xlsx",
+    _AnyElement((etree.Element,)),
+    f"{{{SHEET_NAMESPACE}}}t",
+    f"{{{SHEET_NAMESPACE}}}is",
+    f"{{{SHEET_NAMESPACE}}}r",
+    f"{{{SHEET_NAMESPACE}}}rPr",
+    SHEET_NAMESPACE,
+)
+
+_MARKER_TEXTS = {
+    "docx": etree.XPath("descendant-or-self::w:t[contains(., '{')]", namespaces={"w": NAMESPACES["w"]}),
+    "xlsx": etree.XPath("descendant-or-self::*[text()[contains(., '{')]]"),
+}
+_EMPTIED_TEXTS = {
+    "docx": etree.XPath("descendant::w:t[. = $empty]", namespaces={"w": NAMESPACES["w"]}, smart_strings=False),
+    "xlsx": etree.XPath("descendant::*[not(*) and . = $empty]", smart_strings=False),
+}
+
+DIALECT: StateSlot[Dialect] = StateSlot("DIALECT", default=WORD)