fix: ensure font name propagates correctly to existing styles (#74)

* fix(declarative): remove theme font attrs when setting explicit font on heading styles

* version bump

Author: reindervdw-cmi

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cmi-docx"
-version = "0.6.5"
+version = "0.6.6"
 description = "Additional tooling for Python-docx."
 readme = "README.md"
 requires-python = ">=3.12"

src/cmi_docx/declarative/document.py

@@ -179,7 +179,7 @@ def _apply_style_definitions(
             _apply_table_style_definition(docx_doc, defn)
 
 
-def _apply_paragraph_style_definition(  # noqa: C901, PLR0912
+def _apply_paragraph_style_definition(  # noqa: C901, PLR0912, PLR0915
     docx_doc: docx_document.Document,
     defn: styles_mod.ParagraphStyleDefinition,
 ) -> None:
@@ -205,6 +205,21 @@ def _apply_paragraph_style_definition(  # noqa: C901, PLR0912
     font = style.font
     if defn.font is not None:
         font.name = defn.font
+        # font.element is the <w:style> element; <w:rFonts> lives inside <w:rPr>.
+        # We must search the nested <w:rPr> to locate it.
+        rpr = font.element.find(qn("w:rPr"))
+        r_fonts = rpr.find(qn("w:rFonts")) if rpr is not None else None
+        if r_fonts is None:
+            # Built-in styles may already have <w:rPr> but no <w:rFonts>;
+            # create and insert it as the first child of <w:rPr>.
+            if rpr is None:
+                rpr = etree.SubElement(font.element, qn("w:rPr"))
+            r_fonts = etree.SubElement(rpr, qn("w:rFonts"))
+            rpr.insert(0, r_fonts)
+        r_fonts.set(qn("w:ascii"), defn.font)
+        r_fonts.set(qn("w:hAnsi"), defn.font)
+        r_fonts.attrib.pop(qn("w:asciiTheme"), None)
+        r_fonts.attrib.pop(qn("w:hAnsiTheme"), None)
     if defn.font_size is not None:
         font.size = shared.Pt(defn.font_size)
     if defn.bold is not None:

tests/declarative/test_declarative_styles.py

@@ -171,3 +171,32 @@ async def test_table_style_first_row_xml() -> None:
     shd = tc_pr.find(qn("w:shd"))
     assert shd is not None
     assert shd.get(qn("w:fill")) == "003366"
+
+
+@pytest.mark.asyncio
+async def test_heading_style_font_overrides_theme() -> None:
+    """Test that setting font on a built-in heading style removes theme font attributes.
+
+    When font="Arial" is applied to the built-in "Heading 1" style via
+    ParagraphStyleDefinition, the resolved style must:
+    - Report style.font.name == "Arial" (the explicit font wins).
+    - Have no w:asciiTheme attribute on the <w:rFonts> element, so the theme
+      font cannot silently override the explicit font name at render time.
+    """
+    doc = _make_doc(
+        [declarative.ParagraphStyleDefinition(name="Heading 1", font="Arial")],
+        sections=[
+            declarative.Section(
+                children=[declarative.Paragraph(heading=1, text="Hello")],
+            )
+        ],
+    )
+
+    docx = await doc.to_docx()
+
+    style = docx.styles["Heading 1"]
+    assert style.font.name == "Arial"
+
+    r_fonts = style.font.element.rPr.find(qn("w:rFonts"))
+    assert r_fonts is not None
+    assert r_fonts.get(qn("w:asciiTheme")) is None