Skip to content

Add independent list instances and continuation paragraphs - #1614

Draft
pseudosavant wants to merge 3 commits into
python-openxml:masterfrom
pseudosavant:codex/list-numbering-upstream
Draft

pseudosavant wants to merge 3 commits into
python-openxml:masterfrom
pseudosavant:codex/list-numbering-upstream

Conversation

@pseudosavant

@pseudosavant pseudosavant commented Sep 24, 2026 •

Copy link
Copy Markdown

Problem

Paragraph styles alone do not give document generators control over list identity, starting numbers, or unnumbered continuation paragraphs. This adds a draft public API for those operations using numbering already present in a document or template.

API

  • Document.add_list(style="List Number", start=1, level=None) creates an independent sequence.
  • ListInstance.apply(paragraph, level=None) numbers a paragraph without changing its style.
  • restart(start=1, level=None) returns an independent sequence.
  • apply_continuation(paragraph, level=None) suppresses numbering and preserves text alignment.
  • levels and default_level expose template level selection.

A caller resumes a sequence by applying the same handle again. Separate abstract definitions preserve independent counters when sequences are interleaved. In Word, sharing an abstract definition caused a 3, 4, 1, 5 sequence to display 3, 4, 1, 2. The implementation copies the original definition and instance overrides without changing template definitions.

This intentionally starts with template-backed list authoring in the main story and table cells. It does not add arbitrary numbering-format authoring or numbering-style-link resolution. Undefined levels, invalid starts, and cross-document use are rejected before mutation. Continuation formatting is a snapshot. Word has no list-item container.

Validation

  • 1,634 unit tests and 652 acceptance scenarios passed against this branch based on upstream master.
  • New coverage includes independent starts and restarts, interleaved sequences, multi-paragraph items, template overrides, invalid references, and cross-document validation.
  • Microsoft Word verified starts, interleaved restart behavior, continuation indentation, and multilevel numbering with nested restarts.
  • Includes a Word-authored multilevel fixture and documentation of the observed behavior.

Design discussion

Related work includes #210 and #582. This draft focuses on a small public authoring API rather than a general numbering editor. API names, supported scope, and XML helper boundaries are open for review. My current downstream consumer is markdown-docx, and I can adapt it to upstream conventions.

This branch contains isolated feature commits based directly on upstream master. It has no fork packaging, version changes, or dependency on the fork's other features.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant