DOCX List Processing#

List handling in the DOCX backend (docling/backend/msword_backend.py) 1 revolves around two concerns: correctly grouping list items into ListGroup objects (with proper numbering), and isolating list state so that lists in different table cells don't bleed into one another.

Entry Points#

List Group Creation and Reuse#

Each unique list in the output document is represented by a ListGroup. The backend avoids creating redundant groups when the same numbered list is interrupted (e.g., by an empty paragraph) and then resumes.

Cache variables (initialized at lines 318–322) 2:

• self.last_numid — the numId of the most recently processed list paragraph
• self.last_list_group — the cached ListGroup object
• self.last_list_group_numid — the numId that group was created for
• self.last_list_group_parent — the parent node the group was attached to

_can_reuse_list_group(numId, parent) returns True only when all four cached values match the current paragraph's numId and parent — i.e., the list is resuming in the same structural context 3.

_get_or_create_list_group() either reuses the cached group (and prunes any empty TextItems that were inserted as gap-fillers between list paragraphs) or creates a fresh ListGroup and updates the cache 4. Counter resets via _reset_list_counters_for_new_sequence() 5 only fire when the numId actually changes, not on resumption.

_clear_list_group_cache() zeroes all three cache fields, forcing a fresh group on the next list paragraph 6.

Continuity Detection#

_manage_list_structure() detects continuity by querying the rolling self.history dict 7, which records the numid, indent, level, and name of each processed paragraph:

• _prev_numid() / _prev_indent() — retrieve the immediately preceding paragraph's identifiers 8
• _get_level() — determines the current nesting depth 9

numId and ilvl are extracted from each paragraph's <w:numPr> element (with fallback to the paragraph style) by _get_numId_and_ilvl() 10.

Numbering Counters#

Counter state is stored in self.list_counters: dict[tuple[int, int], int], keyed by (numId, ilvl) 2.

• _get_list_counter() — gets and increments the counter for a (numId, ilvl) pair; automatically resets all sub-level counters when a parent level advances 11.
• _get_level_element() — walks the numbering XML to resolve the abstract numbering definition for a given (numId, ilvl) 12.
• _build_enum_marker() — renders the lvlText template (e.g., "Proposal %1:") into the final marker string 13.
• _VISIBLE_NUMBERING_FORMATS 14 — a frozenset of OOXML numFmt values (decimal, lowerRoman, upperRoman, lowerLetter, upperLetter, decimalZero) that produce visible numeric markers; other formats (bullets, etc.) are excluded 14.

Table Cell State Isolation#

Lists inside table cells must not share group state with lists outside the cell or in other cells, even when they share the same numId.

_isolated_list_context() (a context manager, lines 517–548) 15:

1. Saves history, level_at_new_list, parents, and all three list group cache variables.
2. Calls _clear_list_group_cache() so no prior group bleeds into the cell.
3. Restores the full saved state in a finally block after the cell is processed.

It is applied during rich table cell processing in _handle_tables() 16. For single-paragraph (plain) table cells, _clear_list_group_cache() is called directly 17.

Key Bug Fixes#

Key Source File#