xlsx/named-style-builtin--linked-cell

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_named_style_builtin.py

#!/usr/bin/env python3
"""Generate a ``fixtures/xlsx/named-style-builtin--<style-id>.xlsx`` fixture.

Parameterised generator for the ``xlsx/named-style-builtin`` manifest.
Writes a minimal one-sheet workbook with cell A1 bearing a python-xlsx
built-in named style (``ws['A1'].style = <name>``). python-xlsx
auto-materialises the named style into ``xl/styles.xml`` at save time,
producing a ``<cellStyles>/<cellStyle name="..."/>`` entry. The manifest's
``generator.arg_template`` drives ``--style-name`` at expansion time.
"""

from __future__ import annotations

import argparse
import datetime as _dt
from pathlib import Path

from xlsx import Workbook

_REPO_ROOT = Path(__file__).resolve().parent.parent
_REPRODUCIBLE_DT = _dt.datetime(2000, 1, 1, 0, 0, 0)


def _write(style_name: str, out: Path) -> None:
    wb = Workbook()
    ws = wb.active
    ws["A1"] = "Styled cell"
    ws["A1"].style = style_name  # python-xlsx auto-materialises built-in
    out.parent.mkdir(parents=True, exist_ok=True)
    wb.save(out, zip_date_time=_REPRODUCIBLE_DT)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--style-name",
        required=True,
        help="Exact built-in named-style string (e.g. 'Good', 'Accent1', 'Heading 1').",
    )
    parser.add_argument(
        "--out",
        required=True,
        help="Output fixture path (relative to repo root or absolute).",
    )
    args = parser.parse_args()

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


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "xlsx/named-style-builtin--linked-cell",
  "kind": "literal",
  "title": "Built-in named cell styles",
  "format": "xlsx",
  "category": "cell-formatting",
  "summary": "Assigning a python-xlsx built-in named-style string to a cell produces a <cellStyles>/<cellStyle name='...'/> entry in xl/styles.xml.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "18.8.8",
    "element": "cellStyle",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/SpreadsheetML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/sml.xsd",
    "notes": "ECMA-376 Part 1 clause 18.8.8 (cellStyle) defines the named-style container. Named styles sit in xl/styles.xml as <cellStyles>/<cellStyle name='Name' xfId='N' builtinId='K'/> entries; each <cellStyle> points via xfId into <cellStyleXfs>, which a concrete <cellXfs>/<xf> can then reference via its own xfId attribute. Excel reserves a fixed roster of 'built-in' names keyed by builtinId (0='Normal', 8='Hyperlink', 15='Title', 16..19='Heading 1..4', 20='Input', 21='Output', 22='Calculation', 23='Check Cell', 24='Linked Cell', 25='Total', 26='Good', 27='Bad', 28='Neutral', 29='Accent1', 33='Accent2', 37='Accent3', 41='Accent4', 45='Accent5', 49='Accent6', 53='Explanatory Text', etc). python-xlsx ships these via xlsx.styles.builtins.styles — assigning the exact display string to `cell.style = name` auto-materialises the named style into the workbook. Names not in python-xlsx's registry raise `ValueError: <name> is not a known style`. This family parameterises over 18 of Excel's built-in names that python-xlsx recognises (scratch-tested against xlsx.styles.builtins.styles). The single assertion checks for a matching <cellStyle name='...'/> entry in xl/styles.xml. SpreadsheetML parts use a default namespace with no prefix; XPath therefore needs an explicit binding (here 'x'). Note: python-xlsx uses the display string 'Heading N' (matching Excel's canonical name); spec prose sometimes calls these 'Headline N', but the spec name is 'Heading'."
  },
  "fixtures": {
    "machine": "xlsx/named-style-builtin--linked-cell"
  },
  "generator": {
    "python": "scripts/gen_named_style_builtin.py",
    "arg_template": "--style-name \"{style.name}\" --out fixtures/xlsx/named-style-builtin--{style.id}.xlsx"
  },
  "_expansion": {
    "parent_id": "xlsx/named-style-builtin",
    "bindings": {
      "style": "linked-cell"
    }
  },
  "assertions": [
    {
      "id": "named-style-present-linked-cell",
      "part": "xl/styles.xml",
      "namespaces": {
        "x": "http://schemas.openxmlformats.org/spreadsheetml/2006/main"
      },
      "xpath": "//x:cellStyles/x:cellStyle[@name='Linked Cell']",
      "must": "exist",
      "description": "xl/styles.xml must contain a <cellStyle name='Linked Cell'/> entry under <cellStyles>."
    }
  ],
  "render_assertions": [
    {
      "id": "named-style-linked-cell-cell-present",
      "kind": "css_selector",
      "selector": "section.xlsx td",
      "must": "exist",
      "description": "The rendered sheet must contain at least one cell; renderer-specific named-style application is out of scope for this family."
    },
    {
      "id": "sheet-count-linked-cell",
      "kind": "css_selector",
      "selector": "section.xlsx",
      "must": "equal-count",
      "count": 1,
      "description": "Exactly one rendered sheet section per case. Catches renderers that emit zero sheets (hard failure)."
    }
  ]
}