docx/scale-table

Parameter axes

• size (3 values): rows10, rows100, rows1000

Spec notes

Generator source

scripts/gen_scale_table.py — runs with --arg_template --rows {size.rows} --out fixtures/docx/scale-table--{size.id}.docx

#!/usr/bin/env python3
"""Generate ``fixtures/docx/scale-table--<n>.docx``.

Parameterised stress fixture for the ``docx/scale-table`` family. Writes a
single 10-column table whose body contains ``--rows`` rows, each cell
carrying a short deterministic text. Designed to expose non-linear cost
in table add_row / cell addressing.

Assertions count ``<w:tr>`` rows and ``<w:tc>`` cells and compare to the
expected totals.

Usage::

    python scripts/gen_scale_table.py \
        --rows 100 \
        --out fixtures/docx/scale-table--rows100.docx
"""

from __future__ import annotations

import argparse
from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent

_COLS = 10


def _write(rows: int, out: Path) -> None:
    doc = Document()
    table = doc.add_table(rows=rows, cols=_COLS)
    for r in range(rows):
        row_cells = table.rows[r].cells
        for c in range(_COLS):
            row_cells[c].text = f"r{r}c{c}"
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out, reproducible=True)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--rows", required=True, type=int, help="Number of table rows.")
    parser.add_argument("--out", required=True, help="Output path for the .docx file.")
    args = parser.parse_args()

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


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/scale-table",
  "kind": "parameterised",
  "title": "Scale: one 10-column table, many rows",
  "format": "docx",
  "category": "scale",
  "summary": "Stress test that writes a single 10-column table with N rows (each cell populated with a short deterministic string) and verifies the row/cell counts round-trip. Parameterised across N = 10, 100, 1000 rows so O(N^2) behaviour in table construction or save becomes visible.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.4",
    "element": "w:tbl",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "python-docx's add_table(rows, cols) constructs the table eagerly. A thousand-row, ten-column table exercises the row-iteration and cell-addressing code paths in ways a ten-row fixture never reaches. Historically, per-cell gridSpan computation or per-row rsid generation has been the hot spot."
  },
  "fixtures": {
    "machine": "docx/scale-table"
  },
  "generator": {
    "python": "scripts/gen_scale_table.py",
    "arg_template": "--rows {size.rows} --out fixtures/docx/scale-table--{size.id}.docx"
  },
  "parameters": {
    "size": [
      {
        "id": "rows10",
        "rows": "10",
        "cells": "100"
      },
      {
        "id": "rows100",
        "rows": "100",
        "cells": "1000"
      },
      {
        "id": "rows1000",
        "rows": "1000",
        "cells": "10000"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "row-count-{size.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "string(count(//w:tbl/w:tr))",
      "must": "equal",
      "value": "{size.rows}",
      "description": "The table must contain exactly N direct <w:tr> children."
    },
    {
      "id": "cell-count-{size.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "string(count(//w:tbl/w:tr/w:tc))",
      "must": "equal",
      "value": "{size.cells}",
      "description": "The table must contain exactly 10*N <w:tc> cells, ten per row."
    },
    {
      "id": "last-cell-text-{size.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:tbl/w:tr[last()]/w:tc[last()]//w:t",
      "must": "match",
      "value": "^r[0-9]+c9$",
      "description": "The last cell of the last row must carry the deterministic marker 'r<N-1>c9', proving the tail of the stream wasn't truncated."
    }
  ],
  "meta": {
    "performance": {
      "recorded_on": "2026-05-05",
      "notes": "Wall-clock save time and on-disk file size for each case. Not asserted. Note that time scales super-linearly with N (10x rows takes ~6x time at 100->1000), suggesting sub-quadratic but non-linear cost in table construction or serialisation.",
      "cases": [
        {
          "id": "rows10",
          "save_seconds": 0.16,
          "file_bytes": 20902
        },
        {
          "id": "rows100",
          "save_seconds": 0.28,
          "file_bytes": 35490
        },
        {
          "id": "rows1000",
          "save_seconds": 1.68,
          "file_bytes": 179769
        }
      ]
    }
  }
}