vibe.templates_mgmt.updatablereferences

docx_reference_updater.py - Update references in Word documents.

This module provides functionality to update Table of Contents (TOC) and cross-references in .docx documents after template processing (e.g., with docxtpl) has removed sections.

Key features: - Recalculates heading numbers based on document's numbering system - Updates TOC entries with correct section numbers - Updates REF field cross-references - Handles SEQ fields (figure/table numbers) - Configurable handling of missing references

Usage

from docx_reference_updater import UpdatableReferences import docx

d = UpdatableReferences(docx.Document("my_doc.docx")) result = d.update_references(missing_reference_action='warning') d.save("updated_doc.docx")

Note: Does NOT update page numbers (would require a Word-compatible renderer).

MissingReferenceAction

How to handle references to removed sections.

NumberFormat

Word numbering formats.

NumberingLevel

Represents a single level in a numbering definition.

format_number 

format_number(value: int) -> str

Format a number according to this level's format.

NumberingDefinition

Represents a complete numbering definition (abstractNum).

get_level 

get_level(level: int) -> NumberingLevel | None

Return the NumberingLevel for the given outline level, or None if not defined.

HeadingInfo

Information about a heading in the document.

ReferenceInfo

Information about a reference (REF field, TOC entry, etc.).

SequenceInfo

Information about a SEQ field (figure/table numbering).

UpdateResult

Result of the update_references operation.

success 

success: bool

True if no errors occurred during reference update.

NumberingParser

Parses and manages Word numbering definitions.

get_definition_for_num_id 

get_definition_for_num_id(num_id: str) -> NumberingDefinition | None

Get the numbering definition for a numId.

format_number 

format_number(num_id: str, level: int, counters: list[int]) -> str

Format a number string for the given level and counters.

FieldParser

Parses and manages Word field codes.

parse_field_instruction 

parse_field_instruction(instr: str) -> tuple[str, str | None, dict[str, str]]

Parse a field instruction.

Returns: (field_type, target, switches).

DocumentScanner

Scans document for headings, bookmarks, and references.

scan 

scan() -> None

Scan the document for all relevant elements.

ReferenceUpdater

Updates references in a Word document.

update_all_references 

update_all_references() -> UpdateResult

Update all references in the document.

TOCUpdater

Updates Table of Contents entries.

update_toc 

update_toc() -> list[ReferenceInfo]

Update all TOC entries in the document.

UpdatableReferences

Wrapper for python-docx Document that adds reference updating capabilities.

This class wraps a docx.Document object and provides methods to update cross-references, TOC entries, and other field references after template processing has modified the document structure.

Usage

doc = UpdatableReferences(docx.Document("template_output.docx")) result = doc.update_references(missing_reference_action='warning') doc.save("final_output.docx")

Attributes:
  • numbering_info (NumberingParser | None) –

    Parsed numbering definitions

  • headings (list[HeadingInfo]) –

    List of headings found in document

  • sequences (dict[str, list[SequenceInfo]]) –

    Dictionary of sequence fields by name

  • last_update_result (UpdateResult | None) –

    Result of most recent update_references() call

document 

document: Document

Access the wrapped python-docx Document object.

numbering_info 

numbering_info: NumberingParser | None

Get parsed numbering information.

headings 

headings: list[HeadingInfo]

Get list of headings found in document.

sequences 

sequences: dict[str, list[SequenceInfo]]

Get dictionary of sequence fields by name.

bookmarks 

bookmarks: dict[str, Any]

Get dictionary of bookmarks found in document.

__init__ 

__init__(document: Document) -> None

Initialize the wrapper.

Parameters:
  • document (Document) –

    A python-docx Document object

update_references 

update_references(missing_reference_action: str | MissingReferenceAction = 'warning', warning_text: str = 'Error! Reference source not found.', update_toc: bool = True, update_ref_fields: bool = True) -> UpdateResult

Update all references in the document.

This method scans the document for cross-references, TOC entries, and other field references, then updates them to reflect the current document structure (including any changes from template processing).

Parameters:
  • missing_reference_action (str | MissingReferenceAction, default: 'warning' ) –

    How to handle references to removed sections. Can be 'ignore', 'raise', 'warning', or 'remove'. - 'ignore': Leave the reference unchanged - 'raise': Raise a ValueError exception - 'warning': Replace with warning text (like Word does) - 'remove': Remove the reference text

  • warning_text (str, default: 'Error! Reference source not found.' ) –

    Text to use when missing_reference_action is 'warning'

  • update_toc (bool, default: True ) –

    Whether to update Table of Contents entries

  • update_ref_fields (bool, default: True ) –

    Whether to update REF field cross-references
Returns:
  • UpdateResult –

    UpdateResult object containing: - updated_references: List of references that were updated - missing_references: List of references to removed targets - unchanged_references: List of references that didn't need updating - headings_found: List of headings found in document - sequences_found: Dictionary of sequence fields - warnings: Any warnings generated - errors: Any errors encountered
Raises:
  • ValueError –

    If missing_reference_action is 'raise' and a missing reference is encountered

get_heading_map 

get_heading_map() -> dict[str, HeadingInfo]

Get a mapping of bookmark names to heading information.

Useful for debugging or understanding document structure.

Returns:
  • dict[str, HeadingInfo] –

    Dictionary mapping bookmark names to HeadingInfo objects

get_numbering_definitions 

get_numbering_definitions() -> dict[str, NumberingDefinition]

Get all numbering definitions in the document.

Returns:
  • dict[str, NumberingDefinition] –

    Dictionary mapping abstract numbering IDs to NumberingDefinition objects

get_broken_references 

get_broken_references() -> list[ReferenceInfo]

Get list of references that point to non-existent targets.

This can be called before update_references() to preview what references would be affected.

Returns:

rescan 

rescan() -> None

Force a rescan of the document.

Call this if you've made modifications to the document and want to update the internal state before calling update_references().

save 

save(path_or_stream: str | PathLike[str] | IO[bytes] | None = None) -> None

Save the document.

Parameters:
  • path_or_stream (str | PathLike[str] | IO[bytes] | None, default: None ) –

    File path or file-like object. If None, saves to the original location (if opened from a file).

update_document_references 

update_document_references(input_path: str, output_path: str | None = None, missing_reference_action: str = 'warning') -> UpdateResult

Update references in a document file.

Convenience function for simple use cases.

Parameters:
  • input_path (str) –

    Path to input .docx file

  • output_path (str | None, default: None ) –

    Path to output file (defaults to overwriting input)

  • missing_reference_action (str, default: 'warning' ) –

    How to handle missing references
Returns:
  • UpdateResult –

    UpdateResult object with details of what was updated