`docx_plus.core.ids`¶

The SDT w:id allocator. One registry per document edit session. Other ID namespaces (r:id, bookmark IDs, comment IDs) are separate uniqueness domains and will get their own registries in later phases.

docx_plus.core.ids ¶

Per-document registries of issued w:id values.

OOXML uses w:id for several disjoint namespaces — SDT controls, bookmarks, comments, footnotes, endnotes. Each namespace has its own uniqueness requirement; bookmark id 7 does not collide with comment id 7. v0.1 only minted SDT ids and shipped :class:IdRegistry for that purpose. v0.2 adds further namespaces (comments, bookmarks, notes) and refactors the shared next/reserve/issued mechanics into :class:_IdRegistryBase. Each namespace-specific registry is a tiny subclass that overrides :meth:_seed_from_document with the right discovery query.

SPEC §3, IMPLEMENTATION.md §7.

IdRegistry ¶

IdRegistry(doc: Document)

Bases: _IdRegistryBase

Tracks issued SDT w:id values for one document-edit session.

On construction, the registry scans the document body and settings part for existing w:id values on w:sdt descendants and seeds itself with them, so :meth:next cannot collide with values already in the file.

Source code in docx_plus/core/ids.py

def __init__(self, doc: Document) -> None:
    """Scan ``doc`` for IDs already issued in this namespace.

    Args:
        doc: A python-docx :class:`~docx.document.Document`.
    """
    self._issued: set[int] = set()
    self._seed_from_document(doc)

DuplicateIdError ¶

Bases: DocxPlusError, ValueError

Raised when an ID is reserved twice.

Subclasses ValueError so existing except ValueError: clauses still catch it; also subclasses :class:DocxPlusError per SPEC §9.7.

IdRangeError ¶

Bases: DocxPlusError, ValueError

Raised when a reserved ID falls outside the 31-bit positive range.

Subclasses ValueError for backward compatibility; also subclasses :class:DocxPlusError per SPEC §9.7.

docx_plus.core.ids¶