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.