Title: Reading Font.highlight_color raises ValueError for valid `w:highlight w:val="none"` · Issue #1559 · python-openxml/python-docx · GitHub
Open Graph Title: Reading Font.highlight_color raises ValueError for valid `w:highlight w:val="none"` · Issue #1559 · python-openxml/python-docx
X Title: Reading Font.highlight_color raises ValueError for valid `w:highlight w:val="none"` · Issue #1559 · python-openxml/python-docx
Description: Summary Reading Font.highlight_color on a run whose
Open Graph Description: Summary Reading Font.highlight_color on a run whose
X Description: Summary Reading Font.highlight_color on a run whose <w:highlight> element has w:val="none" raises: ValueError: WD_COLOR_INDEX has no XML mapping for 'none' none is a valid S...
Opengraph URL: https://github.com/python-openxml/python-docx/issues/1559
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Reading Font.highlight_color raises ValueError for valid `w:highlight w:val=\"none\"`","articleBody":"## Summary\n\nReading `Font.highlight_color` on a run whose `\u003cw:highlight>` element has `w:val=\"none\"` raises:\n\n```\nValueError: WD_COLOR_INDEX has no XML mapping for 'none'\n```\n\n`none` is a valid `ST_HighlightColor` value — Word writes `\u003cw:highlight w:val=\"none\"/>` when a highlight is explicitly cleared from a run. Because the exception is raised during parsing (any access to `font.highlight_color`), it aborts processing of the entire document, not just the affected run.\n\n## Environment\n\n- python-docx 1.2.0\n- Python 3.12\n\n## Reproduction\n\n```python\nfrom docx import Document\nfrom docx.oxml.ns import qn\n\ndoc = Document()\nr = doc.add_paragraph().add_run(\"hi\")._r\nhl = r.get_or_add_rPr().makeelement(qn(\"w:highlight\"), {qn(\"w:val\"): \"none\"})\nr.get_or_add_rPr().append(hl)\n\ndoc.paragraphs[0].runs[0].font.highlight_color\n# ValueError: WD_COLOR_INDEX has no XML mapping for 'none'\n```\n\nTraceback bottoms out in `BaseXmlEnum.from_xml()` (`docx/enum/base.py`), via `CT_Highlight.val` → `highlight_val`.\n\n## Root cause\n\n`WD_COLOR_INDEX` (`docx/enum/text.py`) maps every `ST_HighlightColor` value **except** `none`. `CT_RPr.highlight_val` does `return highlight.val`, and the `RequiredAttribute(\"w:val\", WD_COLOR_INDEX)` descriptor calls `WD_COLOR_INDEX.from_xml(\"none\")`, which has no member and raises.\n\n## Proposed fix\n\n`none` semantically means \"not highlighted\" — exactly what python-docx already represents as `None` (the value returned when no `w:highlight` element is present, and the value the `highlight_val` setter writes by removing the element). So map the explicit `none` value to `None` in the getter:\n\n```python\n@property\ndef highlight_val(self) -> WD_COLOR_INDEX | None:\n highlight = self.highlight\n if highlight is None:\n return None\n if highlight.get(qn(\"w:val\")) == \"none\":\n return None\n return highlight.val\n```\n\n`none` is the only `ST_HighlightColor` value absent from `WD_COLOR_INDEX`, so this closes the gap completely without an enum-value collision (a `none` enum member would have no distinct MS-API integer — `AUTO` already occupies `0`).\n\nI have a branch with this fix plus a unit test and will open a PR referencing this issue.","author":{"url":"https://github.com/mithunvoe","@type":"Person","name":"mithunvoe"},"datePublished":"2026-06-10T18:45:53Z","url":"https://github.com/python-openxml/python-docx/issues/1559"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:09789f64-ff4b-74b6-73f4-18a599dbf3f7 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 8CE2:36BC9B:231D70:2EF719:6AFF6399 |
| html-safe-nonce | 6c1455e877a3f75d93fd289ce50d6808d63afb3dd49d83bdff775e4ce018ca54 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4Q0UyOjM2QkM5QjoyMzFENzA6MkVGNzE5OjZBRkY2Mzk5IiwidmlzaXRvcl9pZCI6IjUzNTkzOTE5Mzc1NzA3NTk1NzciLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | 47df06b16bf4261ea554e8586150567047443ea5cfef92b4eed673ce905db2c8 |
| hovercard-subject-tag | issue:4634051702 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/python-openxml/python-docx/1559/issue_layout |
| twitter:image | https://opengraph.githubassets.com/1796cf656b44cd7a7205d4072659e56f95c5ebf4fda52ace9c382db03d77c559/python-openxml/python-docx/issues/1559 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/1796cf656b44cd7a7205d4072659e56f95c5ebf4fda52ace9c382db03d77c559/python-openxml/python-docx/issues/1559 |
| og:image:alt | Summary Reading Font.highlight_color on a run whose |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | mithunvoe |
| hostname | github.com |
| expected-hostname | github.com |
| None | 41b58589a1c4eda1e3c8904144a412b88ca4455f63ca2ad3629f2e9f3c3a1d12 |
| turbo-cache-control | no-preview |
| go-import | github.com/python-openxml/python-docx git https://github.com/python-openxml/python-docx.git |
| octolytics-dimension-user_id | 3403760 |
| octolytics-dimension-user_login | python-openxml |
| octolytics-dimension-repository_id | 13592924 |
| octolytics-dimension-repository_nwo | python-openxml/python-docx |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 13592924 |
| octolytics-dimension-repository_network_root_nwo | python-openxml/python-docx |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8968d6d6acc65d74e4df332d23932dd3fd0502a4 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width