xlsx/extended-properties-basic--words

Metadata

XPath assertions

Render assertions

No render assertions declared.

Generator source

scripts/gen_extended_properties_basic_xlsx.py

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

Parameterised generator; drives ``features/xlsx/extended-properties-basic.json``.

python-xlsx's ExtendedProperties ships with a restricted ``__elements__`` tuple
(only Application / AppVersion / DocSecurity + boolean flags are serialised by
default). To exercise Company / Manager / Template / Words we monkey-patch the
tuple so the Serialisable machinery emits the field under test. This is a
generator-side workaround, not a runtime library change -- the underlying
library keeps its usual output shape for any other caller.
"""

from __future__ import annotations

import argparse
import datetime as _dt
from pathlib import Path

from xlsx import Workbook

_REPO_ROOT = Path(__file__).resolve().parent.parent
_REPRODUCIBLE_DT = _dt.datetime(2000, 1, 1, 0, 0, 0)

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

# Scalar fields that must be opted-in via ``__elements__`` before python-xlsx
# will emit them. Cases targeting one of these fields append the XML name to
# the instance ``__elements__`` tuple before save.
_OPT_IN_ELEMENTS = {
    "company": "Company",
    "manager": "Manager",
    "template": "Template",
    "words": "Words",
    "pages": "Pages",
    "hyperlink-base": "HyperlinkBase",
}


def _apply(wb, field: str, value: str) -> None:
    ep = wb.extended_properties
    opt_in = _OPT_IN_ELEMENTS.get(field)
    if opt_in is not None and opt_in not in ep.__elements__:
        ep.__elements__ = ep.__elements__ + (opt_in,)
    if field == "application":
        ep.Application = value
    elif field == "app-version":
        ep.AppVersion = value
    elif field == "company":
        ep.Company = value
    elif field == "doc-security":
        ep.DocSecurity = int(value)
    elif field == "manager":
        ep.Manager = value
    elif field == "template":
        ep.Template = value
    elif field == "words":
        ep.Words = int(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" / "xlsx" / "extended-properties-basic.xlsx"),
    )
    args = parser.parse_args()

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

    wb = Workbook()
    wb.properties.created = _PINNED_CREATED
    wb.properties.modified = _PINNED_MODIFIED
    wb.properties.creator = ""
    _apply(wb, args.field, args.value)
    out_path.parent.mkdir(parents=True, exist_ok=True)
    wb.save(out_path, zip_date_time=_REPRODUCIBLE_DT)
    print(out_path)
    return 0


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "xlsx/extended-properties-basic--words",
  "kind": "literal",
  "title": "Extended (app) properties: common scalar fields",
  "format": "xlsx",
  "category": "metadata",
  "summary": "The ``docProps/app.xml`` part carries application-level metadata (Application, AppVersion, Company, DocSecurity, Manager, Template, Words). Each case isolates one field, so each XPath assertion proves that particular field round-trips via python-xlsx's Workbook.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. python-xlsx's ExtendedProperties class ships a restricted default ``__elements__`` tuple (Application / AppVersion / DocSecurity and a handful of boolean scalars) so Company / Manager / Template / Words / HyperlinkBase need an explicit opt-in to be serialised; the generator augments ``__elements__`` at runtime to include whichever field is under test. If python-xlsx later broadens its default serialisation set, the generator hack becomes a no-op and the family continues to pass."
  },
  "fixtures": {
    "machine": "xlsx/extended-properties-basic--words"
  },
  "generator": {
    "python": "scripts/gen_extended_properties_basic_xlsx.py",
    "arg_template": "--field {field.id} --value \"{field.value}\" --out fixtures/xlsx/extended-properties-basic--{field.id}.xlsx"
  },
  "_expansion": {
    "parent_id": "xlsx/extended-properties-basic",
    "bindings": {
      "field": "words"
    }
  },
  "assertions": [
    {
      "id": "ext-words-present",
      "part": "docProps/app.xml",
      "namespaces": {
        "ep": "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties"
      },
      "xpath": "//ep:Words",
      "must": "exist",
      "description": "The words element must be present in docProps/app.xml."
    },
    {
      "id": "ext-words-value",
      "part": "docProps/app.xml",
      "namespaces": {
        "ep": "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties"
      },
      "xpath": "//ep:Words",
      "must": "equal",
      "value": "42",
      "description": "The words element's text must equal the supplied value."
    }
  ]
}