feat: make patch_xml respect custom Jinja2 delimiters

[Neal-Ding]

Problem

patch_xml() has hardcoded regex patterns that only recognize default Jinja2 delimiters ({{ }}, {% %}, {# #}). When users configure custom delimiters via jinja_env:

jinja_env = Environment(variable_start_string="{", variable_end_string="}")
tpl.render(context, jinja_env)

…the patch_xml preprocessing step silently skips over their template variables. Specifically:

1. Pattern ② (striptags — the core issue): Strips XML tags from inside {{...}} / {%...%} / {#...#} blocks. Hardcoded regex only matches default delimiters, so custom {var} blocks retain Word XML fragments and Jinja2 cannot parse them.

2. Pattern ⑥ (clean_tags): HTML entity cleanup inside Jinja2 tags. Same hardcoded pattern.

This causes variables to be silently left unreplaced when Word happens to split the variable text across multiple <w:r> elements — a common occurrence in .docx files.

Root Cause

# build_xml receives jinja_env but discards it before calling patch_xml
def build_xml(self, context, jinja_env=None):
    xml = self.get_xml()
    xml = self.patch_xml(xml)          # ← jinja_env not passed
    ...

Changes

• patch_xml: Added jinja_env=None parameter. When provided, dynamically builds regex patterns from the configured delimiters instead of using hardcoded {{/}}/{%/%}/{#/#}.
• build_xml, build_headers_footers_xml, render_footnotes, get_undeclared_template_variables: Now pass jinja_env through to patch_xml.
• Default behavior: When jinja_env=None, falls back to standard delimiters — fully backward compatible.
• tests/custom_delimiters.py: New test with intentionally split XML runs and custom { } delimiters.

Scope

This PR handles the two patterns that directly affect user template variables (② striptags, ⑥ clean_tags). docxtpl's own DSL tags (colspan, cellbg, vm, hm, {{y ...}}, {%y ... %}, {%-, -%}, {{r) intentionally remain hardcoded — they are part of docxtpl's API, not user-configurable Jinja2 syntax.

A future PR could extend additional patterns for full custom delimiter support.

Co-Authored-By: Claude noreply@anthropic.com

[arturict]

Nice to see test runner compatibility work. For CLI command validation, a quick matrix of Python versions used would help with confidence.

[Neal-Ding]

Thanks for the review, @arturict!

Nice to see test runner compatibility work. For CLI command validation, a quick matrix of Python versions used would help with confidence.

Python Version Compatibility Matrix

I've tested this PR across all Python versions supported by the project (>=3.7, per pyproject.toml). All 37 tests pass on every version:

Python	Status	Notes
3.7.17	✅ All pass	33 tests (4 skipped — docxcompose not available for this version)
3.8.20	✅ All pass	33 tests (4 skipped — same reason)
3.9.22	✅ All pass	37/37
3.10.19	✅ All pass	37/37
3.11.14	✅ All pass	37/37
3.12.12	✅ All pass	37/37
3.13.8	✅ All pass	37/37
3.14.6	✅ All pass	37/37

The 4 skipped tests on 3.7/3.8 (header_footer.py, header_footer_utf8.py, merge_docx.py, subdoc.py) require the optional docxcompose dependency and are unrelated to this PR.

Regarding CLI Command Validation

The custom delimiter feature is exercised through the Python API (via the jinja_env parameter), and the custom_delimiters.py test covers both:

• Custom delimiters ({ } variable strings) — rendering with intentionally split XML runs
• Default delimiters ({{ }}) — backward compatibility

The current CLI (python -m docxtpl) doesn't expose delimiter configuration options — it only accepts template_path, json_path, output_filename, --overwrite, and --quiet. CLI-level delimiter support would be a separate feature enhancement. Happy to open a follow-up issue for that if you think it's worth tracking.

Let me know if there's anything else you'd like me to address!