feat: add type hints

Author: waketzheng

.github/workflows/codestyle.yml

@@ -9,11 +9,12 @@ jobs:
       matrix:
         python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v5
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
+        allow-prereleases: true
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
@@ -23,3 +24,7 @@ jobs:
         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
+    - name: Check type hints
+      run: |
+        pip install mypy lxml-stubs
+        mypy .

.gitignore

@@ -22,6 +22,8 @@ var/
 .installed.cfg
 *.egg
 tests/output/*
+.venv/
+.mypy_cache/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -61,4 +63,4 @@ target/
 .project
 
 #Pycharm
-.idea
+.idea

docxtpl/_compat.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+try:
+    from html import escape
+except ImportError:
+    # cgi.escape is deprecated in python 3.7
+    from cgi import escape  # type:ignore[attr-defined,no-redef]
+
+
+__all__ = ("escape",)

docxtpl/inline_image.py

@@ -4,23 +4,39 @@
 
 @author: Eric Lapouyade
 """
+
+from __future__ import annotations
+
+from typing import IO, TYPE_CHECKING
+
 from docx.oxml import OxmlElement, parse_xml
 from docx.oxml.ns import qn
 
+if TYPE_CHECKING:
+    from docx.shared import Length
+    from .template import DocxTemplate
+
 
 class InlineImage(object):
     """Class to generate an inline image
 
     This is much faster than using Subdoc class.
     """
 
-    tpl = None
-    image_descriptor = None
-    width = None
-    height = None
+    tpl: DocxTemplate = None  # type:ignore[assignment]
+    image_descriptor: str | IO[bytes] = None  # type:ignore[assignment]
+    width: int | Length | None = None
+    height: int | Length | None = None
     anchor = None
 
-    def __init__(self, tpl, image_descriptor, width=None, height=None, anchor=None):
+    def __init__(
+        self,
+        tpl: DocxTemplate,
+        image_descriptor: str | IO[bytes],
+        width: int | Length | None = None,
+        height: int | Length | None = None,
+        anchor=None,
+    ) -> None:
         self.tpl, self.image_descriptor = tpl, image_descriptor
         self.width, self.height = width, height
         self.anchor = anchor
@@ -49,8 +65,8 @@ def _add_hyperlink(self, run, url, part):
 
         return run
 
-    def _insert_image(self):
-        pic = self.tpl.current_rendering_part.new_pic_inline(
+    def _insert_image(self) -> str:
+        pic = self.tpl.current_rendering_part.new_pic_inline(  # type:ignore
             self.image_descriptor,
             self.width,
             self.height,

docxtpl/listing.py

@@ -4,11 +4,8 @@
 
 @author: Eric Lapouyade
 """
-try:
-    from html import escape
-except ImportError:
-    # cgi.escape is deprecated in python 3.7
-    from cgi import escape
+
+from ._compat import escape
 
 
 class Listing(object):

docxtpl/py.typed

@@ -4,11 +4,8 @@
 
 @author: Eric Lapouyade
 """
-try:
-    from html import escape
-except ImportError:
-    # cgi.escape is deprecated in python 3.7
-    from cgi import escape
+
+from ._compat import escape
 
 
 class RichText(object):

docxtpl/richtext.py

@@ -4,6 +4,7 @@
 
 @author: Eric Lapouyade
 """
+# mypy: ignore-errors
 
 from os import PathLike
 from typing import TYPE_CHECKING, Any, Optional, IO, Union, Dict, Set
@@ -18,11 +19,7 @@
 from jinja2 import Environment, Template, meta
 from jinja2.exceptions import TemplateError
 
-try:
-    from html import escape  # noqa: F401
-except ImportError:
-    # cgi.escape is deprecated in python 3.7
-    from cgi import escape  # noqa: F401
+from ._compat import escape  # noqa: F401
 import re
 import binascii
 import os

docxtpl/template.py

@@ -4,6 +4,7 @@
 
 @author: Eric Lapouyade
 """
+from typing import cast
 
 from docxtpl import DocxTemplate
 
@@ -35,6 +36,6 @@
 
 for document_data in documents_data:
     dest_file = document_data["dest_file"]
-    context = document_data["context"]
+    context = cast(dict, document_data["context"])
     tpl.render(context)
     tpl.save("output/%s" % dest_file)

tests/multi_rendering.py

@@ -11,7 +11,7 @@
 
 tpl = DocxTemplate("templates/replace_picture_tpl.docx")
 
-context = {}
+context: dict = {}
 
 tpl.replace_pic("python_logo.png", "templates/python.png")
 tpl.render(context)