docx/paragraph-background

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_paragraph_background.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/paragraph-background.docx``.

A minimal document exercising the ``w:shd`` element on ``w:pPr`` — a
whole-paragraph background fill. python-docx (including the fork as of
2026.05.x) does not expose a high-level ``ParagraphFormat.shading`` API
for the paragraph itself, so we drop to the ``OxmlElement`` layer.
Satisfies the assertions in ``features/docx/paragraph-background.json``.
"""

from __future__ import annotations

from pathlib import Path

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

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "paragraph-background.docx"


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph("Paragraph with shaded background")
    pPr = paragraph._p.get_or_add_pPr()
    shd = OxmlElement("w:shd")
    shd.set(qn("w:val"), "clear")
    shd.set(qn("w:color"), "auto")
    shd.set(qn("w:fill"), "FFFF00")  # yellow
    pPr.append(shd)
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/paragraph-background",
  "title": "Paragraph background shading",
  "format": "docx",
  "category": "paragraph-layout",
  "summary": "Apply a solid background (shading) color to a whole paragraph via pPr/shd.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.1.31",
    "element": "w:shd",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "When <w:shd> is placed on <w:pPr> it fills the entire paragraph cell with the given color. w:val is an ST_Shd pattern ('clear' = solid fill), w:color is the pattern foreground (typically 'auto'), and w:fill is the RRGGBB background color. Distinct from <w:shd> on <w:rPr>, which only shades the run's text box."
  },
  "fixtures": {
    "machine": "docx/paragraph-background",
    "office": "docx/paragraph-background"
  },
  "generator": {
    "python": "scripts/gen_paragraph_background.py"
  },
  "assertions": [
    {
      "id": "ppr-shd-element-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Paragraph with shaded background']]/w:pPr/w:shd",
      "must": "exist",
      "description": "The paragraph must have a <w:shd> child inside <w:pPr>."
    },
    {
      "id": "ppr-shd-fill-is-yellow",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Paragraph with shaded background']]/w:pPr/w:shd/@w:fill",
      "must": "equal",
      "value": "FFFF00",
      "description": "w:fill must equal 'FFFF00' (yellow)."
    }
  ],
  "render_assertions": [
    {
      "id": "paragraph-background-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper [style*='background-color: yellow'], .docx-wrapper [style*='background-color:yellow'], .docx-wrapper [style*='background: yellow'], .docx-wrapper [style*='background:yellow'], .docx-wrapper [style*='rgb(255, 255, 0)'], .docx-wrapper [style*='rgb(255,255,0)'], .docx-wrapper [style*='#ffff00'], .docx-wrapper [style*='#FFFF00']",
      "must": "match-text",
      "value": "Paragraph with shaded background",
      "description": "A DOM node with a yellow background must contain the paragraph text."
    },
    {
      "id": "paragraph-background-visible",
      "kind": "computed_style",
      "selector": ".docx-wrapper p, .docx-wrapper .docx-paragraph, .docx-wrapper div[class*='paragraph']",
      "style_property": "background-color",
      "value": "^(rgb\\(255,\\s*255,\\s*0\\)|#ffff00|#FFFF00|yellow)$",
      "description": "The computed background-color on the paragraph element must resolve to yellow."
    }
  ]
}