docx/field-page-number

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_field_page_number.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/field-page-number.docx``.

A paragraph containing a simple PAGE field whose cached result is ``1``.
Designed to satisfy the assertions in
``features/docx/field-page-number.json``.

Real-world docs place PAGE fields in headers/footers; here the field is
inline in the body so XPath assertions can run against ``word/document.xml``
directly.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "field-page-number.docx"


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph("Page ")
    # Use python-docx's high-level Paragraph.add_simple_field(); cached text
    # '1' stands in for Word's normal "current page number" render.
    paragraph.add_simple_field(r"PAGE \* MERGEFORMAT", text="1")
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/field-page-number",
  "title": "Field: PAGE (page number)",
  "format": "docx",
  "category": "fields",
  "summary": "A paragraph containing a simple PAGE field that Word replaces with the current page number.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.16.5",
    "element": "w:fldSimple",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "The PAGE field returns the current page number. Simple-field form: <w:fldSimple w:instr=\"PAGE \\* MERGEFORMAT\"/>. Fields are typically placed in headers/footers in real documents; this fixture puts the field inline in the body for testability."
  },
  "fixtures": {
    "machine": "docx/field-page-number",
    "office": "docx/field-page-number"
  },
  "generator": {
    "python": "scripts/gen_field_page_number.py"
  },
  "assertions": [
    {
      "id": "page-field-simple-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:fldSimple[starts-with(normalize-space(@w:instr), 'PAGE')]",
      "must": "exist",
      "description": "A <w:fldSimple> element whose w:instr starts with 'PAGE' must be present in the body."
    },
    {
      "id": "page-field-label-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[.//w:fldSimple[starts-with(normalize-space(@w:instr), 'PAGE')]]//w:t[normalize-space()='Page']",
      "must": "exist",
      "description": "The paragraph hosting the PAGE field must carry the 'Page ' literal run (the paragraph's human-readable label)."
    }
  ],
  "render_assertions": [
    {
      "id": "page-field-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper [data-field='PAGE'], .docx-wrapper .field-page, .docx-wrapper p",
      "must": "match-text",
      "value": "Page\\s*\\d+",
      "description": "A renderer-exposed PAGE field (or the fallback paragraph) must contain 'Page' followed by a digit. Most renderers write the cached result value as plain text."
    }
  ]
}