Skip to content

fix: map highlight w:val="none" to None instead of raising#1560

Open
mithunvoe wants to merge 1 commit into
python-openxml:masterfrom
mithunvoe:fix/highlight-val-none
Open

fix: map highlight w:val="none" to None instead of raising#1560
mithunvoe wants to merge 1 commit into
python-openxml:masterfrom
mithunvoe:fix/highlight-val-none

Conversation

@mithunvoe

Copy link
Copy Markdown

Fixes #1559.

Problem

Reading Font.highlight_color on a run with <w:highlight w:val="none"/> raises ValueError: WD_COLOR_INDEX has no XML mapping for 'none'. none is a valid ST_HighlightColor value that Word writes when a highlight is explicitly cleared. Because the error fires during parsing, it aborts processing of any document containing the value.

from docx import Document
from docx.oxml.ns import qn

doc = Document()
r = doc.add_paragraph().add_run("hi")._r
hl = r.get_or_add_rPr().makeelement(qn("w:highlight"), {qn("w:val"): "none"})
r.get_or_add_rPr().append(hl)
doc.paragraphs[0].runs[0].font.highlight_color  # ValueError before this change

Fix

none means "not highlighted" — the same state python-docx already represents as None (returned when no w:highlight element is present, and what the highlight_val setter writes by removing the element). The getter now maps the explicit none value to None.

none is the only ST_HighlightColor value absent from WD_COLOR_INDEX, so this closes the gap without introducing an enum member that would collide on MS-API value 0 with AUTO.

Changes

  • src/docx/oxml/text/font.py: CT_RPr.highlight_val returns None for w:val="none".
  • tests/text/test_font.py: added a parametrized case asserting w:val=none reads as None.

Verification

  • pytest — full suite (1610 passed), including the new case
  • ruff check / ruff format --check — clean
  • pyright on the changed source — 0 errors

`w:val="none"` is a valid `ST_HighlightColor` value that Word writes when
a highlight is explicitly cleared from a run. It has no `WD_COLOR_INDEX`
member, so reading `Font.highlight_color` on such a run raised
`ValueError: WD_COLOR_INDEX has no XML mapping for 'none'` from
`BaseXmlEnum.from_xml()`, which aborts parsing of any document containing
the value.

`none` semantically means "not highlighted", which python-docx already
represents as `None` (the value returned when no `w:highlight` element is
present), and which the `highlight_val` setter writes by removing the
element. Map the explicit `none` value to `None` in the getter to match.

`none` is the only `ST_HighlightColor` value absent from `WD_COLOR_INDEX`,
so this closes the gap completely.
@mithunvoe mithunvoe force-pushed the fix/highlight-val-none branch from d312163 to ce390d3 Compare June 10, 2026 18:47
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.

Reading Font.highlight_color raises ValueError for valid w:highlight w:val="none"

1 participant