Span

A visible-text interval mapped back to its concrete text atoms.

Spans hold live references into the document tree and go stale when the underlying text changes; every operation revalidates first and raises TargetNotFoundError on staleness. match_policy records the policy that selected a search-produced span, or is None for a span constructed from already-known live offsets.

Span(text: str, story: str, anchor: Anchor, in_insert: bool, in_delete: bool, in_content_control: bool, in_text_box: bool, in_field: bool, crosses_paragraphs: bool, _document: 'Document', _atoms: 'List[_Atom]', _start_offset: int, _end_offset: int, _raw_start: int, _match_start: int, _consumed: bool = False)

Attributes

`anchor`

attributeanchorAnchor

`crosses_paragraphs`

attributecrosses_paragraphsbool

`in_content_control`

attributein_content_controlbool

`in_delete`

attributein_deletebool

`in_field`

attributein_fieldbool

`in_insert`

attributein_insertbool

`in_text_box`

attributein_text_boxbool

`match_policy`

attributematch_policy'Optional[str]'

= field(default=None, init=False)

`story`

attributestorystr

`text`

attributetextstr

Functions

`comment`

funccomment(text: str, *, author: str, initials: Optional[str] = None, date: Optional[dt.datetime] = None) -> 'object'

Anchor a new comment to exactly this span's text, and return the upstream Comment.

Reach for this over Document.add_comment when the anchor must match exact text rather than whole runs. Splits boundary runs, and creates /word/comments.xml on first use. Only the main document story carries comments. Refuses a protected document, a stale span, and a locked or data-bound control surface.

paramtextstr

paramauthorstr

paraminitialsOptional[str]

= None

paramdateOptional[dt.datetime]

= None

Returns

'object'

`replace`

funcreplace

(new_text: str, *, tracked: bool = False, author: Optional[str] = None, date: Optional[dt.datetime] = None, preserve_revision: bool = False) -> ReplaceResult

Replace this span's text and return machine-readable change evidence.

The default is an untracked edit over one proved structural-owner region. When maximal exact prefix/suffix alignment identifies one changed interval, unchanged affix text stays in its existing atoms. A nonempty replacement inherits the complete direct run properties of the changed interval's starting text run; consumed later runs may therefore collapse intentionally. Distinct inline wrapper owners, semantic-scope crossings, positional-marker crossings, and ambiguous affix or pure-insertion boundaries refuse. tracked=True uses the same unique localization and formatting inheritance; tracked deletion pieces retain each source run's properties. A successful tracked change consumes the span; a direct tracked no-op is refused.

preserve_revision=True explicitly permits a current-view span wholly owned by one existing w:ins to be corrected without changing that insertion's id, author, date, or accept/reject meaning; outside revision markup it behaves like an ordinary untracked edit. The corrected text remains attributed to the existing insertion's author and date. preserved_formatting_regions and preserved_revision_ids report independent guarantees; revision_ids remains reserved for newly authored tracked revisions. Every successful text-changing replacement consumes the supplied span; use the returned result and re-find the text before another operation. A no-op, refusal, or rolled-back mutation leaves the span reusable. Refuses a protected document, a stale or foreign span, and unsafe field, control, revision, bookmark, whitespace, or paragraph-boundary structures before mutation.

paramnew_textstr

paramtrackedbool

= False

paramauthorOptional[str]

= None

paramdateOptional[dt.datetime]

= None

parampreserve_revisionbool

= False

Returns

docx.search.ReplaceResult

On this page