docx/table-border-style

Parameter axes

• style (20 values): single, double, thick, thin-thick-small-gap, thick-thin-small-gap, dashed, dash-small-gap, dotted, dot-dash, dot-dot-dash, wave, wavy-line, three-d-emboss, three-d-engrave, inset, outset, triple, dash-dot-stroked, two-dashes, nil
• side (4 values): top, left, bottom, right

Spec notes

Generator source

scripts/gen_table_border_style.py — runs with --arg_template --style {style.val} --side {side.id} --out fixtures/docx/table-border-style--{side.id}--{style.id}.docx

#!/usr/bin/env python3
"""Generate ``fixtures/docx/table-border-style--<style>--<side>.docx``.

Parameterised generator for the ``docx/table-border-style`` family: writes a
single-cell table whose ``w:tblBorders`` declares a single edge with the
requested ``ST_Border`` line style. Expanded at runtime by the manifest's
``generator.arg_template`` into 20 styles x 4 sides = 80 cases.

Uses raw ``OxmlElement`` rather than the fork's high-level
``Table.set_borders`` API because ``set_borders`` only accepts the
``WD_BORDER_STYLE`` enum, which does not cover every ``ST_Border`` value
enumerated in ECMA-376 Part 1 clause 17.18.2.
"""

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_SIDES = {"top", "left", "bottom", "right", "insideH", "insideV"}


def _write(style_val: str, side: str, out: Path) -> None:
    if side not in _VALID_SIDES:
        raise ValueError(
            f"Unknown side {side!r}; expected one of {sorted(_VALID_SIDES)}"
        )

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

    tblPr = table._tbl.tblPr
    tblBorders = OxmlElement("w:tblBorders")
    edge = OxmlElement(f"w:{side}")
    edge.set(qn("w:val"), style_val)
    edge.set(qn("w:sz"), "8")
    edge.set(qn("w:space"), "0")
    edge.set(qn("w:color"), "000000")
    tblBorders.append(edge)
    tblPr.append(tblBorders)

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


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--style", required=True, help="ST_Border val, e.g. 'single'")
    parser.add_argument(
        "--side",
        required=True,
        help="Edge element local name: top | left | bottom | right (also insideH/insideV)",
    )
    parser.add_argument("--out", required=True, help="Output .docx path")
    args = parser.parse_args()

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


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/table-border-style",
  "kind": "parameterised",
  "title": "Table border style",
  "format": "docx",
  "category": "tables",
  "summary": "Each ST_Border line style applied to a single edge of w:tblBorders (top / left / bottom / right). Expands to 20 styles x 4 sides = 80 cases.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.4.38",
    "element": "w:tblBorders",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "<w:tblBorders> inside <w:tblPr> carries per-edge border child elements (w:top, w:left, w:bottom, w:right, w:insideH, w:insideV). Each child's w:val attribute is an ST_Border line style. ECMA-376 Part 1 clause 17.18.2 enumerates ST_Border; this family covers 20 common values on the four outer edges. Rendering of specific border styles varies wildly across consumers, so only a smoke render check is asserted."
  },
  "fixtures": {
    "machine": "docx/table-border-style"
  },
  "generator": {
    "python": "scripts/gen_table_border_style.py",
    "arg_template": "--style {style.val} --side {side.id} --out fixtures/docx/table-border-style--{side.id}--{style.id}.docx"
  },
  "parameters": {
    "style": [
      {
        "id": "single",
        "val": "single"
      },
      {
        "id": "double",
        "val": "double"
      },
      {
        "id": "thick",
        "val": "thick"
      },
      {
        "id": "thin-thick-small-gap",
        "val": "thinThickSmallGap"
      },
      {
        "id": "thick-thin-small-gap",
        "val": "thickThinSmallGap"
      },
      {
        "id": "dashed",
        "val": "dashed"
      },
      {
        "id": "dash-small-gap",
        "val": "dashSmallGap"
      },
      {
        "id": "dotted",
        "val": "dotted"
      },
      {
        "id": "dot-dash",
        "val": "dotDash"
      },
      {
        "id": "dot-dot-dash",
        "val": "dotDotDash"
      },
      {
        "id": "wave",
        "val": "wave"
      },
      {
        "id": "wavy-line",
        "val": "wavyLine"
      },
      {
        "id": "three-d-emboss",
        "val": "threeDEmboss"
      },
      {
        "id": "three-d-engrave",
        "val": "threeDEngrave"
      },
      {
        "id": "inset",
        "val": "inset"
      },
      {
        "id": "outset",
        "val": "outset"
      },
      {
        "id": "triple",
        "val": "triple"
      },
      {
        "id": "dash-dot-stroked",
        "val": "dashDotStroked"
      },
      {
        "id": "two-dashes",
        "val": "twoDashes"
      },
      {
        "id": "nil",
        "val": "nil"
      }
    ],
    "side": [
      {
        "id": "top",
        "elem": "top"
      },
      {
        "id": "left",
        "elem": "left"
      },
      {
        "id": "bottom",
        "elem": "bottom"
      },
      {
        "id": "right",
        "elem": "right"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "border-{side.id}-is-{style.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:tblPr/w:tblBorders/w:{side.elem}/@w:val",
      "must": "equal",
      "value": "{style.val}",
      "description": "The table's w:tblBorders/{side.elem} edge must declare line style '{style.val}'."
    }
  ],
  "render_assertions_template": [
    {
      "id": "table-border-style-{style.id}-{side.id}-table-present",
      "kind": "css_selector",
      "selector": ".docx-wrapper table",
      "must": "exist",
      "description": "A rendered <table> element must be present under .docx-wrapper."
    },
    {
      "id": "table-border-style-{style.id}-{side.id}-cell-text-smoke",
      "kind": "css_selector",
      "selector": ".docx-wrapper table td, .docx-wrapper table th",
      "must": "match-text",
      "value": "Border test cell",
      "description": "Smoke check: the rendered table cell text must include 'Border test cell'. Exact border-style rendering is renderer-specific and intentionally not asserted."
    }
  ]
}