docx/round-trip-rels-stable

Parameter axes

• source (5 values): hyperlink, image-inline, page-header, comment, footnote

Spec notes

Generator source

scripts/gen_round_trip_rels_stable.py — runs with --arg_template --source {source.id} --out fixtures/docx/round-trip-rels-stable--{source.id}.docx

#!/usr/bin/env python3
"""Generate round-trip-rels-stable twin fixtures.

Round-trip a fixture whose document part has one non-boilerplate
relationship — hyperlink, image, header, comment, or footnote — and
commit the twin. Assertions then pin the `r:id` value AND the target
of that relationship. If python-docx ever starts renumbering r:id values
non-deterministically during save, or drops a rels entry, the
assertions fail.
"""

from __future__ import annotations

import argparse
import sys
from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_FIX = _REPO_ROOT / "fixtures" / "docx"


def round_trip(source: Path, out: Path) -> None:
    doc = Document(str(source))
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(str(out), reproducible=True)


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--source", required=True, help="Source fixture logical name (without .docx).")
    parser.add_argument("--out", required=True, help="Output fixture path (repo-relative).")
    ns = parser.parse_args(argv)

    source_path = _FIX / f"{ns.source}.docx"
    out_path = _REPO_ROOT / ns.out
    if not source_path.exists():
        print(f"Source fixture missing: {source_path}", file=sys.stderr)
        return 1
    round_trip(source_path, out_path)
    print(out_path)
    return 0


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/round-trip-rels-stable",
  "kind": "parameterised",
  "title": "Round-trip relationship stability (python-docx)",
  "format": "docx",
  "category": "round-trip",
  "summary": "Round-trip a fixture whose document part carries one distinguishing relationship (hyperlink, image, header, comment, or footnote) and assert that after save the relationship still carries exactly its original r:id and Target. Catches non-determinism in python-docx's rels emission and any accidental renumbering.",
  "spec": {
    "source": "ecma-376-5-part-3",
    "clause": "9.3",
    "element": "Relationship",
    "notes": "ECMA-376 Part 3 (OPC) requires each package relationship to carry a stable Id within its source part. Word consumers reference those Ids from the document body (e.g. <w:hyperlink r:id='rId9'>); any save path that re-picks Ids or reorders them will either break intra-document references or produce non-reproducible output that thrashes diffs. python-docx is currently stable on both counts — this manifest pins that stability."
  },
  "fixtures": {
    "machine": "docx/round-trip-rels-stable"
  },
  "round_trip": {
    "library": "python-docx",
    "source_fixture": "docx/round-trip-rels-stable",
    "notes": "Mode B (generator-embedded). The generator loads the committed source fixture (hyperlink.docx / image-inline.docx / page-header.docx / comment.docx / footnote.docx) through python-docx and saves the twin as the manifest fixture."
  },
  "generator": {
    "python": "scripts/gen_round_trip_rels_stable.py",
    "arg_template": "--source {source.id} --out fixtures/docx/round-trip-rels-stable--{source.id}.docx"
  },
  "parameters": {
    "source": [
      {
        "id": "hyperlink",
        "rid": "rId9",
        "rel_type": "hyperlink",
        "target": "https://example.com/",
        "target_mode": "External"
      },
      {
        "id": "image-inline",
        "rid": "rId9",
        "rel_type": "image",
        "target": "media/image1.png",
        "target_mode": "Internal"
      },
      {
        "id": "page-header",
        "rid": "rId9",
        "rel_type": "header",
        "target": "header1.xml",
        "target_mode": "Internal"
      },
      {
        "id": "comment",
        "rid": "rId9",
        "rel_type": "comments",
        "target": "comments.xml",
        "target_mode": "Internal"
      },
      {
        "id": "footnote",
        "rid": "rId9",
        "rel_type": "footnotes",
        "target": "footnotes.xml",
        "target_mode": "Internal"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "rid-preserved-{source.id}",
      "part": "word/_rels/document.xml.rels",
      "namespaces": {
        "r": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "//r:Relationships/r:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/{source.rel_type}']/@Id",
      "must": "equal",
      "value": "{source.rid}",
      "description": "The distinguishing relationship must retain its original r:id across round-trip (no renumbering)."
    },
    {
      "id": "target-preserved-{source.id}",
      "part": "word/_rels/document.xml.rels",
      "namespaces": {
        "r": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "//r:Relationships/r:Relationship[@Id='{source.rid}']/@Target",
      "must": "equal",
      "value": "{source.target}",
      "description": "The relationship's Target must be preserved byte-identical."
    },
    {
      "id": "styles-rel-present-{source.id}",
      "part": "word/_rels/document.xml.rels",
      "namespaces": {
        "r": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "//r:Relationships/r:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles']",
      "must": "exist",
      "description": "Boilerplate rels (styles.xml) must also survive — a round-trip that drops rIds is the classic failure mode this family catches."
    }
  ]
}