Move docxcompose to optional dependency

Author: waketzheng

.github/workflows/codestyle.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11','3.12','3.13']
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}
@@ -22,4 +22,4 @@ jobs:
       run: |
         pip install flake8
         # stop the build if there are code styling problems. The GitHub editor is 127 chars wide.
-        flake8 . --count --max-line-length=127 --show-source --statistics
+        flake8 . --count --max-line-length=127 --show-source --statistics

CHANGES.rst

@@ -1,3 +1,7 @@
+0.20.2 *(Unreleased)*
+-------------------
+- Move docxcompose to optional dependency (Thanks to Waket Zheng)
+
 0.20.1 (2025-07-15)
 -------------------
 - Fix and improve get_undeclared_template_variables() method (Thanks to Pablo Esteban)

docs/index.rst

@@ -286,6 +286,8 @@ Please see tests/inline_image.py for an example.
 Sub-documents
 -------------
 
+> Need to install with the subdoc extra: `pip install "docxtpl[subdoc]"`
+
 A template variable can contain a complex subdoc object and be built from scratch using python-docx document methods.
 To do so, first, get the sub-document object from your template object, then use it by treating it as a python-docx document object.
 See example in `tests/subdoc.py`.

docxtpl/__init__.py

@@ -4,11 +4,15 @@
 
 @author: Eric Lapouyade
 """
+
 __version__ = "0.20.1"
 
 # flake8: noqa
 from .inline_image import InlineImage
 from .listing import Listing
 from .richtext import RichText, R, RichTextParagraph, RP
-from .subdoc import Subdoc
 from .template import DocxTemplate
+try:
+    from .subdoc import Subdoc
+except ImportError:
+    pass

docxtpl/template.py

@@ -6,8 +6,7 @@
 """
 
 from os import PathLike
-from typing import Any, Optional, IO, Union, Dict, Set
-from .subdoc import Subdoc
+from typing import TYPE_CHECKING, Any, Optional, IO, Union, Dict, Set
 import functools
 import io
 from lxml import etree
@@ -29,6 +28,9 @@
 import os
 import zipfile
 
+if TYPE_CHECKING:
+    from .subdoc import Subdoc
+
 
 class DocxTemplate(object):
     """Class for managing docx files as they were jinja2 templates"""
@@ -610,7 +612,9 @@ def fix_docpr_ids(self, tree):
             self.docx_ids_index += 1
             elt.attrib["id"] = str(self.docx_ids_index)
 
-    def new_subdoc(self, docpath=None):
+    def new_subdoc(self, docpath=None) -> Subdoc:
+        from .subdoc import Subdoc
+
         self.init_docx()
         return Subdoc(self, docpath)
 

setup.py

@@ -1,8 +1,9 @@
-from setuptools import setup
 import os
 import re
 import sys
 
+from setuptools import setup
+
 # To register onto Pypi :
 # python setup.py sdist bdist_wheel upload
 
@@ -61,15 +62,16 @@ def get_version(pkg):
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
     ],
     keywords="jinja2",
     url="https://github.com/elapouya/python-docx-template",
     author="Eric Lapouyade",
     license="LGPL-2.1-only",
     license_files=[],
     packages=["docxtpl"],
-    install_requires=["python-docx>=1.1.1", "docxcompose", "jinja2", "lxml"],
-    extras_require={"docs": ["Sphinx", "sphinxcontrib-napoleon"]},
+    install_requires=["python-docx>=1.1.1", "jinja2", "lxml"],
+    extras_require={"docs": ["Sphinx", "sphinxcontrib-napoleon"], "subdoc": ["docxcompose"]},
     eager_resources=["docs"],
     zip_safe=False,
 )