Skip to content

docx_plus.fields.update

Mark every field in a document for recalculation on the next Word open. Sets <w:updateFields w:val="true"/> in settings.xml. Word flips the flag back to false after recalculating — it's a one-shot mechanism, not persistent state.

mark_fields_dirty is idempotent: a second call updates the existing element rather than duplicating it.

docx_plus.fields.update

Mark fields dirty so Word recalculates them on next open.

A complex field stores both an instruction (w:instrText) and a cached result (w:t). Word will display the cached result unless it is told to recalculate. Setting <w:updateFields w:val="true"/> in settings.xml flips a one-shot flag — Word resolves every field in the document on open, then clears the flag back to false so the recalculation does not repeat.

This module imports only from docx_plus.core (SPEC §9.1).

mark_fields_dirty 

mark_fields_dirty(doc: Document) -> None

Set w:updateFields="true" in settings.xml.

Idempotent: calling twice produces a single w:updateFields element. If an existing element has w:val="false", it is updated to "true". Should a malformed settings.xml (e.g. from another tool) contain several w:updateFields copies, they are collapsed to one set to "true" — leaving a stale duplicate behind would let Word read the wrong value (CT_Settings permits at most one).

Parameters:

Name Type Description Default
doc Document

The python-docx :class:~docx.document.Document whose settings part should be flagged.

 required
Example

from docx import Document from docx_plus.fields import add_page_number_field, mark_fields_dirty doc = Document() p = doc.add_paragraph("Page ") _ = add_page_number_field(p) mark_fields_dirty(doc)

Source code in docx_plus/fields/update.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def mark_fields_dirty(doc: DocxDocument) -> None:
    """Set ``w:updateFields="true"`` in ``settings.xml``.

    Idempotent: calling twice produces a single ``w:updateFields`` element.
    If an existing element has ``w:val="false"``, it is updated to ``"true"``.
    Should a malformed ``settings.xml`` (e.g. from another tool) contain
    several ``w:updateFields`` copies, they are collapsed to one set to
    ``"true"`` — leaving a stale duplicate behind would let Word read the
    wrong value (``CT_Settings`` permits at most one).

    Args:
        doc: The python-docx :class:`~docx.document.Document` whose settings
            part should be flagged.

    Example:
        >>> from docx import Document
        >>> from docx_plus.fields import add_page_number_field, mark_fields_dirty
        >>> doc = Document()
        >>> p = doc.add_paragraph("Page ")
        >>> _ = add_page_number_field(p)
        >>> mark_fields_dirty(doc)
    """
    settings = doc.settings.element
    existing = settings.findall(qn("w:updateFields"))
    if existing:
        existing[0].set(qn("w:val"), "true")
        for extra in existing[1:]:
            remove(extra)
        return
    new = el("w:updateFields", **{"w:val": "true"})
    insert_before_first_anchor(settings, new, _UPDATE_FIELDS_LATER_SIBLINGS)