WolfSDKWolfXLWolfPPTWolfDocxWolfRender

WolfDocx - field refresh

Update a Word table of contents in Python without opening Word

python-docx can't do this: it never calculates field results, so the usual advice is to set updateFields and let Word ask the reader to refresh on open. WolfDocx refreshes the TOC field itself. refresh_fields rebuilds the entries from the document's headings, computes page numbers with its own page layout from the font files you supply, and saves a new .docx whose table of contents is already current. No Word, COM, or LibreOffice install is involved.

Refresh every field, including the TOC

import hashlib

from wolfdocx.fields import parse_field_refresh_request, refresh_fields

source = "handbook.docx"
report = refresh_fields(parse_field_refresh_request({
    "source": source,
    "source_sha256": hashlib.sha256(open(source, "rb").read()).hexdigest(),
    "output": "handbook_updated.docx",
    "fonts": [
        {"family": "Calibri", "path": "/opt/fonts/calibri.ttf"},
        {"family": "Calibri Light", "path": "/opt/fonts/calibril.ttf"},
    ],
}))
assert report.passed, report.code
print(report.pages, report.converged, len(report.refreshed))

With no fields list, the request refreshes every supported field in the main document: TOC, PAGEREF, PAGE and NUMPAGES, REF, SEQ, and the document-information fields. Page-dependent values are iterated until pagination stops changing; report.converged says whether it did. Pass a fields list from the inventory to refresh only selected fields.

wolfdocx author fields-targets handbook.docx    # list every field and whether it can refresh
wolfdocx author fields-refresh request.json     # the same request as JSON

What the refresh keeps

  • Each field keeps its instruction text, such as TOC \o "1-3" \h \z \u; only the cached result is rewritten.
  • The TOC keeps its nested PAGEREF fields and hyperlinks to the headings.
  • Locked fields keep their result and are reported, not changed.
  • The source hash is checked again before the output is published, so an edited source is never refreshed into a stale output.

Limits

  • Page numbers come from WolfDocx's own layout engine, not from Microsoft Word. They can differ from Word's where line breaking or font metrics differ, so supply the exact font files the document uses.
  • TOC switches \o, \t, \b, \c, \f, \h, \z, and \u are supported. A TOC that uses \n, \p, \s, \w, \a, \d, \g, or \l is refused.
  • A field WolfDocx cannot resolve refuses the whole request before anything is written.
  • The refresh covers one story per request: the body by default, or a selected header, footer, or note part.
  • The full request and report fields are in the WolfDocx API reference.

Get WolfDocx

WolfDocx Commercial is an organization-scoped subscription. WolfDocx Community installs from public PyPI with pip install wolfdocx. WolfDocx Commercial installs from the authenticated WolfDocx package index with a per-purchase credential, issued on the checkout success page after payment and reissued through https://wolfxl.com/recover. There is no public free package.

Review the scoped before-and-after memo files in the reporting walkthrough, or ask about your document before purchasing if compatibility is uncertain.

See WolfDocx Commercial

Related tasks