docx/paragraph-break-before

Parameter axes

• break_kind (2 values): present, absent

Spec notes

Generator source

scripts/gen_paragraph_break_before.py — runs with --arg_template --break-kind {break_kind.val} --out fixtures/docx/paragraph-break-before--{break_kind.id}.docx

#!/usr/bin/env python3
"""Generate a ``fixtures/docx/paragraph-break-before--<kind>.docx`` fixture.

Parameterised generator for the ``docx/paragraph-break-before`` feature
family. Two cases are produced:

- ``--break-kind present`` — a two-paragraph document where the second
  paragraph carries ``<w:pageBreakBefore/>`` on its ``<w:pPr>``.
- ``--break-kind absent``  — the same layout without the toggle, so
  layout continues on the same page.

python-docx has no ``ParagraphFormat`` property for page-break-before,
so this generator appends ``<w:pageBreakBefore/>`` via
:class:`docx.oxml.OxmlElement` to the target paragraph's ``<w:pPr>``.
"""

from __future__ import annotations

import argparse
from pathlib import Path

from docx import Document
from docx.oxml import OxmlElement

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

_VALID_KINDS = {"present", "absent"}


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

    doc = Document()
    doc.add_paragraph("First paragraph (before the break).")
    target = doc.add_paragraph("Break-before target")

    if break_kind == "present":
        pPr = target._p.get_or_add_pPr()
        # xmlchemy's descriptor-based insertion would enforce successors; the
        # OxmlElement path is used here to keep the family explicit and let
        # the generator remain agnostic to python-docx's pPr schema ordering.
        pbb = OxmlElement("w:pageBreakBefore")
        pPr.insert(0, pbb)

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


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--break-kind",
        required=True,
        help=f"One of {sorted(_VALID_KINDS)}.",
    )
    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.break_kind, out_path)
    print(out_path)
    return 0


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/paragraph-break-before",
  "kind": "parameterised",
  "title": "Paragraph page-break-before",
  "format": "docx",
  "category": "paragraph-layout",
  "summary": "Toggle <w:pageBreakBefore/> on a paragraph's <w:pPr>, forcing the paragraph to start on a new page when the toggle is present.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.1.23",
    "element": "w:pageBreakBefore",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "<w:pageBreakBefore/> is a CT_OnOff toggle child of <w:pPr>. When present (with no w:val or w:val='1'/'true'/'on') the paragraph is laid out on a new page. This family exercises two concrete cases: the element present, and the element absent. The fuller 'column break' variant (emitted as <w:r><w:br w:type=\"column\"/></w:r>) is covered by the sibling docx/page-break family and is deliberately not re-exercised here. Each case picks the assertion verb (exist / absent) from its parameter record so a single assertions_template covers both shapes."
  },
  "fixtures": {
    "machine": "docx/paragraph-break-before"
  },
  "generator": {
    "python": "scripts/gen_paragraph_break_before.py",
    "arg_template": "--break-kind {break_kind.val} --out fixtures/docx/paragraph-break-before--{break_kind.id}.docx"
  },
  "parameters": {
    "break_kind": [
      {
        "id": "present",
        "val": "present",
        "must": "exist"
      },
      {
        "id": "absent",
        "val": "absent",
        "must": "absent"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "target-paragraph-present-{break_kind.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Break-before target']]",
      "must": "exist",
      "description": "The target paragraph must exist in the document body (anchor for the toggle assertion)."
    },
    {
      "id": "page-break-before-toggle-{break_kind.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Break-before target']]/w:pPr/w:pageBreakBefore",
      "must": "{break_kind.must}",
      "description": "The <w:pageBreakBefore/> element must be present on the target paragraph only in the 'present' case."
    }
  ]
}