docx/core-properties-full

Parameter axes

• field (12 values): title, subject, creator, description, language, keywords, last-modified-by, revision, category, content-status, created, modified

Spec notes

Generator source

scripts/gen_core_properties_full.py — runs with --arg_template --field {field.id} --value "{field.value}" --out fixtures/docx/core-properties-full--{field.id}.docx

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

A parameterised generator: one call per field under test, each producing a
separate .docx with *only that* Dublin-Core / dcterms / cp-core field set.
Drives the ``features/docx/core-properties-full.json`` parameterised manifest.

All fixtures are byte-reproducible: the archive uses the fixed 1980-01-01
entry timestamps, and ``dcterms:created`` / ``dcterms:modified`` are always
pinned to fixed ISO-8601 timestamps (even for the field-under-test cases that
don't exercise the timestamp fields — the default-initialised part otherwise
embeds ``datetime.now()`` which would break byte-reproducibility).
"""

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 timestamps used for *every* fixture -- ensures byte-reproducibility
# regardless of which field a given case targets. The "created" / "modified"
# cases overwrite one of these with their own case-specific value below.
_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:
    cp = doc.core_properties
    # Always pin timestamps first; individual fields may override below.
    cp.created = _PINNED_CREATED
    cp.modified = _PINNED_MODIFIED

    if field == "title":
        cp.title = value
    elif field == "subject":
        cp.subject = value
    elif field == "creator":
        # python-docx exposes dc:creator via the `author` attribute.
        cp.author = value
    elif field == "description":
        # python-docx exposes dc:description via the `comments` attribute.
        cp.comments = value
    elif field == "language":
        cp.language = value
    elif field == "keywords":
        cp.keywords = value
    elif field == "last-modified-by":
        cp.last_modified_by = value
    elif field == "revision":
        cp.revision = int(value)
    elif field == "category":
        cp.category = value
    elif field == "content-status":
        cp.content_status = value
    elif field == "created":
        cp.created = _dt.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(
            tzinfo=_dt.timezone.utc
        )
    elif field == "modified":
        cp.modified = _dt.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(
            tzinfo=_dt.timezone.utc
        )
    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" / "core-properties-full.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.add_paragraph("Body content; 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/core-properties-full",
  "kind": "parameterised",
  "title": "Core properties (full DC + dcterms field set)",
  "format": "docx",
  "category": "metadata",
  "summary": "Every Dublin Core and dcterms field exposed by docProps/core.xml, one field isolated per expanded case. Each case round-trips through python-docx's Document.core_properties API.",
  "spec": {
    "source": "ecma-376-5-part-2",
    "clause": "11.1",
    "notes": "ECMA-376 Part 2 / ISO 29500-2 section 11 defines the OPC 'core-properties' part. It carries a mix of Dublin Core (dc:title, dc:subject, dc:creator, dc:description, dc:language), Dublin Core Terms (dcterms:created, dcterms:modified), and MS-authored OPC-core (cp:keywords, cp:lastModifiedBy, cp:revision, cp:category, cp:contentStatus) elements. This manifest isolates each one in turn so the XPath assertion proves that particular field round-trips. dcterms:created / dcterms:modified are set to a fixed ISO-8601 UTC timestamp in the generator so the fixtures are byte-reproducible."
  },
  "fixtures": {
    "machine": "docx/core-properties-full"
  },
  "generator": {
    "python": "scripts/gen_core_properties_full.py",
    "arg_template": "--field {field.id} --value \"{field.value}\" --out fixtures/docx/core-properties-full--{field.id}.docx"
  },
  "parameters": {
    "field": [
      {
        "id": "title",
        "value": "Core Title",
        "xpath": "//dc:title",
        "ns": "dc"
      },
      {
        "id": "subject",
        "value": "Core Subject",
        "xpath": "//dc:subject",
        "ns": "dc"
      },
      {
        "id": "creator",
        "value": "Alice Author",
        "xpath": "//dc:creator",
        "ns": "dc"
      },
      {
        "id": "description",
        "value": "Description text",
        "xpath": "//dc:description",
        "ns": "dc"
      },
      {
        "id": "language",
        "value": "en-US",
        "xpath": "//dc:language",
        "ns": "dc"
      },
      {
        "id": "keywords",
        "value": "alpha, beta, gamma",
        "xpath": "//cp:keywords",
        "ns": "cp"
      },
      {
        "id": "last-modified-by",
        "value": "Bob Reviewer",
        "xpath": "//cp:lastModifiedBy",
        "ns": "cp"
      },
      {
        "id": "revision",
        "value": "7",
        "xpath": "//cp:revision",
        "ns": "cp"
      },
      {
        "id": "category",
        "value": "Reports",
        "xpath": "//cp:category",
        "ns": "cp"
      },
      {
        "id": "content-status",
        "value": "Draft",
        "xpath": "//cp:contentStatus",
        "ns": "cp"
      },
      {
        "id": "created",
        "value": "2026-01-01T00:00:00Z",
        "xpath": "//dcterms:created",
        "ns": "dcterms"
      },
      {
        "id": "modified",
        "value": "2026-01-02T00:00:00Z",
        "xpath": "//dcterms:modified",
        "ns": "dcterms"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "core-{field.id}-present",
      "part": "docProps/core.xml",
      "namespaces": {
        "cp": "http://schemas.openxmlformats.org/package/2006/metadata/core-properties",
        "dc": "http://purl.org/dc/elements/1.1/",
        "dcterms": "http://purl.org/dc/terms/"
      },
      "xpath": "{field.xpath}",
      "must": "exist",
      "description": "The {field.id} element must be present in docProps/core.xml."
    },
    {
      "id": "core-{field.id}-value",
      "part": "docProps/core.xml",
      "namespaces": {
        "cp": "http://schemas.openxmlformats.org/package/2006/metadata/core-properties",
        "dc": "http://purl.org/dc/elements/1.1/",
        "dcterms": "http://purl.org/dc/terms/"
      },
      "xpath": "{field.xpath}",
      "must": "equal",
      "value": "{field.value}",
      "description": "The {field.id} element's text must equal the supplied value."
    }
  ]
}