performance: further performance optimizations for large documents#1
Merged
Conversation
Delete the module-level logger and several logger.warning calls in docxtpl/template.py. Added while debugging and should be removed.
Improve documentation in map_tree to explain the optimization: the code swaps the entire <w:body> via root.remove() + root.insert() to avoid O(n) per-child lxml operations, which is effectively O(1) on the document root. Clarify that the body's index is preserved so element order (body before sectPr) remains intact, and spell out the fallback behavior (child-by-child copy) if the body isn't a direct child or if remove/insert fails. Add additional safety and explanatory comments.
Enhance header/footer processing by detecting Jinja tags split across Word XML runs: check both intact tags (_JINJA_PATTERN) and open-tag fragments (_RE_JINJA_OPEN) when scanning part XML. Use a generator to iterate part XML strings once, and keep the existing exception fallback to unconditionally render headers/footers if the fast-path check fails (e.g. malformed XML). Also add clarifying comments about properties and footnotes skipping behaviour and make minor comment style fixes.
Add a fast-path to DocxTemplate.resolve_listing that returns the input XML unchanged when no Listing special characters are present. The check looks for tab, newline, bell and form-feed ("\t", "\n", "\a", "\f") and avoids running the heavier resolution logic in the common case, improving performance without changing behavior.
Introduce pre-compiled regex patterns (_RE_TAG_STRIP and _RE_COMMENT_STRIP) to strip surrounding <w:y> tags from template tags like {%y ...%}, {{y ...}} and comments {#y ...#}. Replace repeated re.sub loops with iteration over these patterns to avoid recompiling the same regexes on every call, reduce code duplication, and improve performance/maintainability.
Clean up docxtpl/template.py by removing unused imports: functools, logging, and Template from jinja2. Keeps Environment and meta from jinja2 and does not change runtime behavior; this reduces linter warnings and unnecessary dependencies.
There was a problem hiding this comment.
Pull request overview
Optimizes docxtpl/template.py to significantly reduce rendering time for large/complex DOCX templates (notably large tables) by reducing repeated regex work, avoiding unnecessary processing, and improving XML tree replacement efficiency.
Changes:
- Pre-compile regexes used during XML patching and add a fast-path in
resolve_listing()when no special characters are present. - Refactor
map_tree()to replace the<w:body>element via root remove/insert (with a fallback path). - Skip header/footer rendering work when no Jinja syntax is detected, with a fallback to unconditional processing on errors.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Update comment in docxtpl/template.py to clarify the fallback behavior when processing headers and footers. The comment now explains the fallback guards against unexpected part structure (e.g. blob is None or missing attributes) rather than implying it handles malformed XML; malformed XML would still fail in build_headers_footers_xml. No functional change.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This pull request refactors and optimizes the
docxtpl/template.pymodule with a strong focus on rendering performance.The primary motivation for these changes was improving rendering performance for large documents containing complex tables. In a real-world case, a document containing a table with 2,164 rows previously required approximately one hour to render. With these optimizations applied, rendering time was reduced to under 10 seconds.
Key Improvements
Performance Optimizations
Pre-compiled regular expressions
Early exit in
resolve_listing()Optimized XML tree manipulation
map_tree()to replace the entire<w:body>element in a single operation (O(1)complexity).Conditional Header/Footer Rendering
The rendering pipeline now skips header and footer processing when no Jinja tags are detected.
Changes include:
This reduces overhead for documents where headers and footers are static.
Real-World Performance Impact
These changes provide substantial improvements for large and complex templates while maintaining compatibility with existing rendering behavior.