docx/extended-properties-basic

Parameter axes

• field (7 values): application, app-version, company, doc-security, pages, words, template

Spec notes

Generator source

scripts/gen_extended_properties_basic.py — runs with --arg_template --field {field.id} --value "{field.value}" --out fixtures/docx/extended-properties-basic--{field.id}.docx

#!/usr/bin/env python3
"""Generate ``fixtures/docx/extended-properties-basic--<field>.docx`` fixtures.

Parameterised generator: one call per field under test. Drives
``features/docx/extended-properties-basic.json``.

Fixtures are byte-reproducible: ``reproducible=True`` pins zip-member
timestamps, and the pinned dcterms:created/modified values keep the core part
stable too (a Document always wires a core-properties part, even when the
feature under test is ``docProps/app.xml``).
"""

from __future__ import annotations

import argparse
import datetime as _dt
from pathlib import Path

from docx import Document

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

_PINNED_CREATED = _dt.datetime(2026, 1, 1, 0, 0, 0, tzinfo=_dt.timezone.utc)
_PINNED_MODIFIED = _dt.datetime(2026, 1, 2, 0, 0, 0, tzinfo=_dt.timezone.utc)


def _apply(doc, field: str, value: str) -> None:
    ep = doc.extended_properties
    if field == "application":
        ep.application = value
    elif field == "app-version":
        ep.app_version = value
    elif field == "company":
        ep.company = value
    elif field == "doc-security":
        # doc_security is exposed as a string-typed field on python-docx
        # (the schema type is xsd:int but python-docx writes the string
        # unchanged); pass an integer-shaped string.
        ep.doc_security = value
    elif field == "pages":
        ep.pages = int(value)
    elif field == "words":
        ep.words = int(value)
    elif field == "template":
        ep.template = value
    else:
        raise SystemExit(f"Unknown field id: {field!r}")


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--field", required=True)
    parser.add_argument("--value", required=True)
    parser.add_argument(
        "--out",
        default=str(_REPO_ROOT / "fixtures" / "docx" / "extended-properties-basic.docx"),
    )
    args = parser.parse_args()

    out_path = Path(args.out)
    if not out_path.is_absolute():
        out_path = _REPO_ROOT / out_path

    doc = Document()
    # Pin core-props timestamps so only app.xml varies per case.
    doc.core_properties.created = _PINNED_CREATED
    doc.core_properties.modified = _PINNED_MODIFIED
    doc.add_paragraph("Body content; extended metadata is the feature under test.")
    _apply(doc, args.field, args.value)
    out_path.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out_path, reproducible=True)
    print(out_path)
    return 0


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/extended-properties-basic",
  "kind": "parameterised",
  "title": "Extended (app) properties: common scalar fields",
  "format": "docx",
  "category": "metadata",
  "summary": "The ``docProps/app.xml`` part carries application-level metadata (Application, AppVersion, Company, DocSecurity, Pages, Words, Template). Each case isolates one field, so each XPath assertion proves that particular field round-trips via python-docx's Document.extended_properties API.",
  "spec": {
    "source": "ecma-376-5-part-4",
    "clause": "22.2",
    "notes": "ECMA-376 Part 4 / ISO 29500-4 section 22.2 defines the extended-properties part (``docProps/app.xml``) in the 'http://schemas.openxmlformats.org/officeDocument/2006/extended-properties' namespace. Its scalar children cover authoring-application metadata and cached statistics. This manifest isolates each common scalar field so an assertion failure points at exactly one property."
  },
  "fixtures": {
    "machine": "docx/extended-properties-basic"
  },
  "generator": {
    "python": "scripts/gen_extended_properties_basic.py",
    "arg_template": "--field {field.id} --value \"{field.value}\" --out fixtures/docx/extended-properties-basic--{field.id}.docx"
  },
  "parameters": {
    "field": [
      {
        "id": "application",
        "value": "Loadfix python-docx",
        "xpath": "//ep:Application"
      },
      {
        "id": "app-version",
        "value": "16.0000",
        "xpath": "//ep:AppVersion"
      },
      {
        "id": "company",
        "value": "Loadfix Inc.",
        "xpath": "//ep:Company"
      },
      {
        "id": "doc-security",
        "value": "0",
        "xpath": "//ep:DocSecurity"
      },
      {
        "id": "pages",
        "value": "3",
        "xpath": "//ep:Pages"
      },
      {
        "id": "words",
        "value": "42",
        "xpath": "//ep:Words"
      },
      {
        "id": "template",
        "value": "Normal.dotm",
        "xpath": "//ep:Template"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "ext-{field.id}-present",
      "part": "docProps/app.xml",
      "namespaces": {
        "ep": "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties"
      },
      "xpath": "{field.xpath}",
      "must": "exist",
      "description": "The {field.id} element must be present in docProps/app.xml."
    },
    {
      "id": "ext-{field.id}-value",
      "part": "docProps/app.xml",
      "namespaces": {
        "ep": "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties"
      },
      "xpath": "{field.xpath}",
      "must": "equal",
      "value": "{field.value}",
      "description": "The {field.id} element's text must equal the supplied value."
    }
  ]
}