docx.fields

Field authoring — formulas, never values.

A field is a formula; static text is a pasted value. This module authors PAGE/NUMPAGES/DATE simple fields, REF/PAGEREF cross-references, and the TOC complex field. Every inserted field carries placeholder result text and sets the document's update-fields-on-open flag: this package never computes a field's value — pagination and evaluation belong to a renderer (Word, or headless LibreOffice in the harness).

The in_field guard recognizes everything authored here, so a span landing inside one of our own fields refuses exactly like one landing in Word's (self-consistency, tested).

`add_caption`

funcadd_caption(paragraph: 'Paragraph', *, label: str = 'Figure', description: str = '') -> None

Append a SEQ caption (Figure 1, Table 1) to paragraph.

Writes the field rather than the displayed integer, so Word recomputes the number on open. Sets the paragraph style to "Caption" without checking that the style exists. Refuses a protected document and an unknown label.

paramparagraph'Paragraph'

paramlabelstr

= 'Figure'

paramdescriptionstr

= ''

Returns

None

`add_date_field`

funcadd_date_field(paragraph: 'Paragraph', *, date_format: Optional[str] = None) -> None

Append a DATE field; date_format is Word's @ picture, for example 'MMMM d, yyyy'.

The result stays a placeholder until a renderer opens the file; this package never computes a date into the result. Refuses a protected document.

paramparagraph'Paragraph'

paramdate_formatOptional[str]

= None

Returns

None

`add_page_count_field`

funcadd_page_count_field(paragraph: 'Paragraph') -> None

Append a NUMPAGES field, typically to a footer paragraph.

Writes the field, not a number, so Word computes the count on open. Refuses a protected document.

paramparagraph'Paragraph'

Returns

None

`add_page_number_field`

funcadd_page_number_field(paragraph: 'Paragraph') -> None

Append a PAGE field, typically to a footer paragraph.

Writes the field, not a number, so Word computes the page on open. Refuses a protected document.

paramparagraph'Paragraph'

Returns

None

`add_reference_field`

funcadd_reference_field(paragraph: 'Paragraph', *, bookmark: str, kind: str = 'text') -> None

Append a cross-reference to bookmark: its text (kind="text"), page ("page"), or paragraph number ("number").

Writes a REF field, so Word recomputes it on open. Refuses a protected document and an unknown bookmark name.

paramparagraph'Paragraph'

parambookmarkstr

paramkindstr

= 'text'

Returns

None

`check_install`

funccheck_install() -> None

Refuse when paper-docx and python-docx are both installed.

Returns

None

`insert_toc_after`

funcinsert_toc_after(document: 'Document', anchor, *, levels: Tuple[int, int] = (1, 3)) -> None

Insert a TOC field in a new paragraph after anchor.

Marked dirty so the renderer builds the real table on open; heading levels maps to the \o "1-3" switch. Refuses a protected document, and an anchor that is missing, ambiguous foreign, or spans more than one paragraph.

paramdocument'Document'

paramanchor

paramlevelsTuple[int, int]

= (1, 3)

Returns

None

`rollback_on_error`

funcrollback_on_error(document: 'Document', *participants: Any) -> Generator[None, None, None]

Restore the live package and named mutable proxies after an error.

paramdocument'Document'

paramparticipantsAny

= ()

Returns

typing.Generator[None, None, None]

On this page