docx/cell-shading

Parameter axes

• fill (5 values): yellow, red, blue, green, orange
• pattern (3 values): clear, pct10, pct50

Spec notes

Generator source

scripts/gen_cell_shading.py — runs with --arg_template --fill {fill.rgb} --pattern {pattern.val} --out fixtures/docx/cell-shading--{fill.id}--{pattern.id}.docx

#!/usr/bin/env python3
"""Generate a ``fixtures/docx/cell-shading--<fill>--<pattern>.docx`` fixture.

Parameterised generator for the ``docx/cell-shading`` feature family.
Writes a 1x1 table whose single cell carries a ``<w:shd/>`` child on
its ``<w:tcPr>`` with the requested fill RGB and ST_Shd pattern.

Usage::

    python scripts/gen_cell_shading.py \\
        --fill FFFF00 \\
        --pattern clear \\
        --out fixtures/docx/cell-shading--yellow--clear.docx

``--fill``    is a 6-digit uppercase hex RGB background colour.
``--pattern`` is the ST_Shd enumerant (``clear``, ``pct10``, ``pct50``
              — the three this family exercises).
"""

from __future__ import annotations

import argparse
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

_VALID_PATTERNS = {"clear", "pct10", "pct50"}


def _write(fill: str, pattern: str, out: Path) -> None:
    if len(fill) != 6:
        raise ValueError(f"Expected 6-digit hex RRGGBB, got {fill!r}")
    if pattern not in _VALID_PATTERNS:
        raise ValueError(
            f"Unknown pattern {pattern!r}; expected one of {sorted(_VALID_PATTERNS)}"
        )

    doc = Document()
    table = doc.add_table(rows=1, cols=1)
    cell = table.rows[0].cells[0]
    cell.text = "Shaded cell"

    tcPr = cell._tc.get_or_add_tcPr()
    # Drop any pre-existing w:shd so the element stays a singleton.
    for existing in tcPr.findall(qn("w:shd")):
        tcPr.remove(existing)
    shd = OxmlElement("w:shd")
    shd.set(qn("w:val"), pattern)
    shd.set(qn("w:color"), "auto")
    shd.set(qn("w:fill"), fill)
    tcPr.append(shd)

    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out, reproducible=True)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--fill",
        required=True,
        help="6-digit uppercase hex RGB background colour.",
    )
    parser.add_argument(
        "--pattern",
        required=True,
        help=f"ST_Shd pattern; one of {sorted(_VALID_PATTERNS)}.",
    )
    parser.add_argument(
        "--out",
        required=True,
        help="Repo-relative or absolute output path for the .docx.",
    )
    args = parser.parse_args()

    out_path = Path(args.out)
    if not out_path.is_absolute():
        out_path = _REPO_ROOT / out_path
    _write(args.fill, args.pattern, out_path)
    print(out_path)
    return 0


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/cell-shading",
  "kind": "parameterised",
  "title": "Table cell shading",
  "format": "docx",
  "category": "tables",
  "summary": "Shade a table cell with a solid or patterned fill by setting <w:shd> on the cell's tcPr.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.4.33",
    "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": "<w:shd/> on a <w:tcPr> carries w:val (ST_Shd pattern), w:color (foreground of the pattern), and w:fill (background RGB). 'clear' paints a solid w:fill; 'pct10' / 'pct50' draw a stippled w:color over w:fill. This family exercises 5 fill colours x 3 patterns = 15 fixtures. python-docx's CT_Tc has no first-class shading API, so the generator writes the element via OxmlElement directly."
  },
  "fixtures": {
    "machine": "docx/cell-shading"
  },
  "generator": {
    "python": "scripts/gen_cell_shading.py",
    "arg_template": "--fill {fill.rgb} --pattern {pattern.val} --out fixtures/docx/cell-shading--{fill.id}--{pattern.id}.docx"
  },
  "parameters": {
    "fill": [
      {
        "id": "yellow",
        "rgb": "FFFF00"
      },
      {
        "id": "red",
        "rgb": "FF0000"
      },
      {
        "id": "blue",
        "rgb": "0000FF"
      },
      {
        "id": "green",
        "rgb": "00FF00"
      },
      {
        "id": "orange",
        "rgb": "FF7F00"
      }
    ],
    "pattern": [
      {
        "id": "clear",
        "val": "clear"
      },
      {
        "id": "pct10",
        "val": "pct10"
      },
      {
        "id": "pct50",
        "val": "pct50"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "shd-element-present-{fill.id}-{pattern.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:tbl//w:tc/w:tcPr/w:shd",
      "must": "exist",
      "description": "The cell's tcPr must carry a <w:shd> child."
    },
    {
      "id": "shd-fill-is-{fill.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:tbl//w:tc/w:tcPr/w:shd/@w:fill",
      "must": "equal",
      "value": "{fill.rgb}",
      "description": "<w:shd w:fill=...> must equal the requested background RGB."
    },
    {
      "id": "shd-pattern-is-{pattern.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:tbl//w:tc/w:tcPr/w:shd/@w:val",
      "must": "equal",
      "value": "{pattern.val}",
      "description": "<w:shd w:val=...> must equal the requested ST_Shd pattern."
    }
  ]
}