WolfDocx documentation - Commercial

# Refresh Word fields and table of contents from Python

WolfDocx Commercial can refresh supported Word fields, including a table of contents, using refresh_fields. Page-dependent results come from its own layout with the font files you supply, not from Microsoft Word. Community does not include this layout workflow, and saving an edited DOCX does not itself calculate a new TOC.

## Why a saved DOCX can still show old values

A Word field has instruction text and a cached result. Changing a heading or adding content is not the same operation as evaluating that field again. If your pipeline edits text but never refreshes the relevant cache, the document can still contain old TOC entries or page numbers.

This guide addresses an existing TOC field and other supported fields. It does not create a table of contents from an arbitrary list of paragraphs. Prepare the headings and field structure in the reviewed source document, then explicitly run the refresh operation.

## Commercial layout workflow

Install Commercial `wolfdocx` from the authenticated index in an environment separate from Community. Use the authenticated index and credential from the checkout success page. The bash or zsh installation command below assumes pip authentication is already configured and does not embed a secret.

```
python -m pip install wolfdocx --index-url https://packages.wolfxl.com/wolfdocx/simple/
```

The sample needs `handbook.docx` containing supported fields and actual Calibri and Calibri Light font files at the paths shown. Replace those paths with fonts you are entitled to use. Supply the document's required font families rather than assuming the server has the same fonts as the authoring machine.

```
import hashlib
from pathlib import Path
from wolfdocx.fields import (
    discover_field_targets, parse_field_refresh_request, refresh_fields,
)

source = Path("handbook.docx")
found = discover_field_targets(source)
if not found["passed"]:
    raise SystemExit(found["code"])

report = refresh_fields(parse_field_refresh_request({
    "source": str(source),
    "source_sha256": hashlib.sha256(source.read_bytes()).hexdigest(),
    "output": "handbook-refreshed.docx",
    "fonts": [
        {"family": "Calibri", "path": "/opt/fonts/calibri.ttf"},
        {"family": "Calibri Light", "path": "/opt/fonts/calibril.ttf"},
    ],
}))
if not report.passed:
    raise SystemExit(report.code)
print(report.pages, report.converged, len(report.refreshed))
```

The source digest binds the request to the reviewed package. `discover_field_targets` inventories field structures before refresh; it is useful for identifying unsupported instructions and choosing explicit targets. A successful inventory is not a promise that every discovered field is refreshable.

## Request scope and result

| Member | Effect |
| --- | --- |
| `source_sha256` | Bind the request to the exact source bytes. |
| `output` | New destination for the refreshed DOCX. |
| `part` | One story part per request, defaulting to the main document. |
| `fields` | Explicit inventory targets; omit to refresh supported fields in the selected story. |
| `fonts` | Family names and actual font-file paths for native layout. |

TOC entries are rebuilt from the document's heading structure. Page-dependent values are iterated with pagination, and the report exposes `converged`, `pages`, and `refreshed`. Check the operation's pass/fail result first, then record these details rather than equating any returned page count with a successful publication.

Locked fields keep their results and are reported rather than changed. A field or switch outside the accepted refresh scope can refuse the request. Do not remove the instruction to force a successful result: that would change the document's meaning rather than solve field evaluation.

## Use the right layout authority

WolfDocx's page numbers describe its own pagination. Microsoft Word can break lines or pages differently because of font metrics and layout behavior. Supplying the exact fonts reduces one source of difference, but it does not establish rendering equivalence between independent engines.

If Word's exact pagination is the acceptance criterion, verify in that environment. If your pipeline deliberately uses WolfDocx layout, keep the font inputs and refreshed output together so the reported result can be explained. Rendering and PDF conversion remain separate Commercial or Wolf Runtime tasks.

## What it does not do

- Community does not calculate page-dependent fields or render pages.
- This operation does not promise Word-identical page numbers.
- It does not refresh all stories in one implicit document-wide request.
- It does not accept every field instruction or TOC switch.

## Related tasks

See [the TOC task guide](https://wolfdocx.com/update-toc-docx-python), [DOCX-to-PDF conversion](https://wolfdocx.com/convert-docx-to-pdf-python), and [structured reports and CLI requests](https://wolfdocx.com/docs/reports-and-cli).

## Get WolfDocx

WolfDocx Community is MIT-licensed and free, including commercial use. It edits existing .docx files in place in pure Python and does not render pages or convert to PDF. WolfDocx Commercial does not change those rights.

```
pip install 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.

Review the scoped before-and-after memo files in the [reporting walkthrough](https://wolfsdk.com/blog/updating-existing-office-reporting-files), or [ask about your document](mailto:trial@wolfxl.com?subject=WolfDocx%20workflow%20fit) before purchasing if compatibility is uncertain.

[See WolfDocx Commercial](https://wolfdocx.com/)

### Related tasks

- [Update table cells in an existing Word document with Python](https://wolfdocx.com/update-docx-table-python)
- [Replace text in an existing Word document with Python](https://wolfdocx.com/replace-text-docx-python)
- [Fill a Word template table with rows from Python](https://wolfdocx.com/fill-word-template-python)
- [Word mail merge in Python: fill MERGEFIELD templates and repeating table rows](https://wolfdocx.com/mail-merge-docx-python)
- [Merge Word documents in Python without breaking numbering, headers, or styles](https://wolfdocx.com/merge-docx-python)
- [Update a Word table of contents in Python without opening Word](https://wolfdocx.com/update-toc-docx-python)
- [Convert DOCX to PDF in Python without Word or LibreOffice](https://wolfdocx.com/convert-docx-to-pdf-python)
- [A python-docx alternative for editing existing Word documents](https://wolfdocx.com/python-docx-alternative)
- [How can Python generate many legal contracts from one Word template?](https://wolfdocx.com/generate-contracts-docx-python)
- [Which Python workflow assembles one Word document from clauses and sections?](https://wolfdocx.com/document-assembly-python)
- [How do you prevent Word's unreadable content warning after a python-docx save?](https://wolfdocx.com/python-docx-unreadable-content)
- [Why does python-docx change Link to Previous on headers and footers?](https://wolfdocx.com/python-docx-header-footer-link-to-previous)
- [Can python-docx handle nested tables and complex headers?](https://wolfdocx.com/nested-tables-docx-python)