pptx/hyperlink-target-modes

Parameter axes

• scheme (3 values): http, mailto, file-uri

Spec notes

Generator source

scripts/gen_pptx_hyperlink_target_modes.py — runs with --arg_template --scheme {scheme.id} --url "{scheme.url}" --out fixtures/pptx/hyperlink-target-modes--{scheme.id}.pptx

#!/usr/bin/env python3
"""Generate ``fixtures/pptx/hyperlink-target-modes--<scheme>.pptx``.

Parameterised across the 3 external-URL schemes described by
``features/pptx/hyperlink-target-modes.json``: http, mailto, file-uri.

Each fixture is a one-slide presentation containing a textbox whose
single run is hyperlinked to the requested URL via the python-pptx
``run.hyperlink.address = <url>`` high-level API.

.. versionadded:: 2026.05.0
"""

from __future__ import annotations

import argparse
import datetime as _dt
from pathlib import Path

from pptx import Presentation
from pptx.util import Inches

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


def _write(url: str, out: Path) -> None:
    prs = Presentation()
    slide = prs.slides.add_slide(prs.slide_layouts[5])  # Title Only
    textbox = slide.shapes.add_textbox(Inches(1), Inches(2), Inches(6), Inches(1))
    run = textbox.text_frame.paragraphs[0].add_run()
    run.text = "Click me"
    run.hyperlink.address = url

    out.parent.mkdir(parents=True, exist_ok=True)
    prs.save(out, zip_date_time=_REPRODUCIBLE_DT)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--scheme", required=True)
    parser.add_argument("--url", required=True)
    parser.add_argument("--out", required=True)
    args = parser.parse_args()

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

    _write(args.url, out_path)
    print(out_path)
    return 0


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "pptx/hyperlink-target-modes",
  "kind": "parameterised",
  "title": "Hyperlink relationship TargetMode matrix (pptx)",
  "format": "pptx",
  "category": "references",
  "summary": "A pptx run-level a:hlinkClick with an external URL must produce a per-slide relationship carrying the correct Target URI and TargetMode='External'. Exercised schemes: http, mailto, file://.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "21.1.2.3.5",
    "element": "a:hlinkClick",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/DrawingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/dml-main.xsd",
    "notes": "Sibling of docx/hyperlink-target-modes. PowerPoint emits a <Relationship Type='.../hyperlink' Target='<url>' TargetMode='External' Id='rIdN'/> in the OWNING slide's rels file, not at presentation.xml.rels level. The run-level a:hlinkClick then carries @r:id pointing at that rel. Exercised schemes align with docx: http(s), mailto, file://. Slide-jump is a separate family (pptx/hyperlink-slide-jump) because it uses an internal .../slide rel rather than an external hyperlink rel."
  },
  "fixtures": {
    "machine": "pptx/hyperlink-target-modes"
  },
  "generator": {
    "python": "scripts/gen_pptx_hyperlink_target_modes.py",
    "arg_template": "--scheme {scheme.id} --url \"{scheme.url}\" --out fixtures/pptx/hyperlink-target-modes--{scheme.id}.pptx"
  },
  "parameters": {
    "scheme": [
      {
        "id": "http",
        "url": "https://example.com/path"
      },
      {
        "id": "mailto",
        "url": "mailto:someone@example.com?subject=Hi"
      },
      {
        "id": "file-uri",
        "url": "file:///C:/docs/other.pptx"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "slide-rel-target-{scheme.id}",
      "part": "ppt/slides/_rels/slide1.xml.rels",
      "namespaces": {
        "pr": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "string(//pr:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink']/@Target)",
      "must": "equal",
      "value": "{scheme.url}",
      "description": "The slide's rels file must carry exactly one external-hyperlink relationship whose @Target equals the generated URL."
    },
    {
      "id": "slide-rel-mode-external-{scheme.id}",
      "part": "ppt/slides/_rels/slide1.xml.rels",
      "namespaces": {
        "pr": "http://schemas.openxmlformats.org/package/2006/relationships"
      },
      "xpath": "string(//pr:Relationship[@Type='http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink']/@TargetMode)",
      "must": "equal",
      "value": "External",
      "description": "External hyperlink relationships on a slide must carry TargetMode='External'."
    },
    {
      "id": "hlinkclick-has-rid-{scheme.id}",
      "part": "ppt/slides/slide1.xml",
      "namespaces": {
        "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
        "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
      },
      "xpath": "//a:hlinkClick[@r:id]",
      "must": "exist",
      "description": "The run's rPr must carry an a:hlinkClick with an r:id pointing at the external relationship."
    },
    {
      "id": "hlinkclick-no-sldjump-action-{scheme.id}",
      "part": "ppt/slides/slide1.xml",
      "namespaces": {
        "a": "http://schemas.openxmlformats.org/drawingml/2006/main"
      },
      "xpath": "//a:hlinkClick[@action='ppaction://hlinksldjump']",
      "must": "absent",
      "description": "An external-URL hyperlink must not carry the slide-jump action URI. If this fails the library is emitting a slide-jump click-action on a run that should be an external URL."
    }
  ]
}