docx/custom-properties-types

Parameter axes

• type (6 values): lpwstr, bool, i4, r8, filetime, date

Spec notes

Generator source

scripts/gen_custom_properties_types.py — runs with --arg_template --type {type.id} --value "{type.value}" --out fixtures/docx/custom-properties-types--{type.id}.docx

#!/usr/bin/env python3
"""Generate ``fixtures/docx/custom-properties-types--<type>.docx`` fixtures.

Parameterised generator; drives ``features/docx/custom-properties-types.json``.
One .docx per vt: type python-docx can emit; the custom property is always
named ``TestProp``.
"""

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 _coerce(vt_id: str, value: str):
    if vt_id == "lpwstr":
        return value
    if vt_id == "bool":
        return value.lower() == "true"
    if vt_id == "i4":
        return int(value)
    if vt_id == "r8":
        return float(value)
    if vt_id == "filetime":
        # Naive datetime; python-docx treats it as UTC and serialises with Z.
        return _dt.datetime.strptime(value, "%Y-%m-%dT%H:%M:%S")
    if vt_id == "date":
        # Calendar date with no time/zone — serialised as vt:date YYYY-MM-DD.
        return _dt.datetime.strptime(value, "%Y-%m-%d").date()
    raise SystemExit(f"Unknown vt type id: {vt_id!r}")


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--type", dest="type_id", required=True)
    parser.add_argument("--value", required=True)
    parser.add_argument(
        "--out",
        default=str(_REPO_ROOT / "fixtures" / "docx" / "custom-properties-types.docx"),
    )
    args = parser.parse_args()

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

    doc = Document()
    doc.core_properties.created = _PINNED_CREATED
    doc.core_properties.modified = _PINNED_MODIFIED
    doc.custom_properties["TestProp"] = _coerce(args.type_id, args.value)
    doc.add_paragraph("Body content; custom property is the feature under test.")
    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/custom-properties-types",
  "kind": "parameterised",
  "title": "Custom document properties: one case per vt: type",
  "format": "docx",
  "category": "metadata",
  "summary": "The ``docProps/custom.xml`` part stores user-defined name/value pairs with a typed child from the ``vt:`` namespace. This family covers one case per type python-docx can emit: lpwstr, bool, i4, r8, filetime, and (as of 2026.05.7) date.",
  "spec": {
    "source": "ecma-376-5-part-2",
    "clause": "11.2",
    "notes": "ECMA-376 Part 2 / ISO 29500-2 section 11.2 defines the OPC custom-properties part. Each property must have a unique name, a fmtid, a pid >= 2, and exactly one typed child from the ``vt:`` (officeDocument/2006/docPropsVTypes) namespace. Supported authoring-side types in python-docx: ``str`` -> ``vt:lpwstr``, ``int`` -> ``vt:i4``, ``float`` -> ``vt:r8``, ``bool`` -> ``vt:bool``, ``datetime.datetime`` -> ``vt:filetime``, ``datetime.date`` -> ``vt:date`` (ECMA-376 Part 1 §22.4.2.7 — a calendar date with no time or zone, added in python-docx 2026.05.7 / Wave 8 W8-E)."
  },
  "fixtures": {
    "machine": "docx/custom-properties-types"
  },
  "generator": {
    "python": "scripts/gen_custom_properties_types.py",
    "arg_template": "--type {type.id} --value \"{type.value}\" --out fixtures/docx/custom-properties-types--{type.id}.docx"
  },
  "parameters": {
    "type": [
      {
        "id": "lpwstr",
        "value": "hello world",
        "vt_element": "lpwstr",
        "vt_value": "hello world"
      },
      {
        "id": "bool",
        "value": "true",
        "vt_element": "bool",
        "vt_value": "true"
      },
      {
        "id": "i4",
        "value": "42",
        "vt_element": "i4",
        "vt_value": "42"
      },
      {
        "id": "r8",
        "value": "3.14159",
        "vt_element": "r8",
        "vt_value": "3.14159"
      },
      {
        "id": "filetime",
        "value": "2026-01-15T12:30:45",
        "vt_element": "filetime",
        "vt_value": "2026-01-15T12:30:45Z"
      },
      {
        "id": "date",
        "value": "2026-01-15",
        "vt_element": "date",
        "vt_value": "2026-01-15"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "custom-{type.id}-present",
      "part": "docProps/custom.xml",
      "namespaces": {
        "op": "http://schemas.openxmlformats.org/officeDocument/2006/custom-properties",
        "vt": "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"
      },
      "xpath": "//op:property[@name='TestProp']/vt:{type.vt_element}",
      "must": "exist",
      "description": "TestProp must carry a <vt:{type.vt_element}> child."
    },
    {
      "id": "custom-{type.id}-value",
      "part": "docProps/custom.xml",
      "namespaces": {
        "op": "http://schemas.openxmlformats.org/officeDocument/2006/custom-properties",
        "vt": "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"
      },
      "xpath": "//op:property[@name='TestProp']/vt:{type.vt_element}",
      "must": "equal",
      "value": "{type.vt_value}",
      "description": "TestProp's <vt:{type.vt_element}> must carry the expected literal text."
    }
  ]
}