docx/tab-stop-custom

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_tab_stop_custom.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/tab-stop-custom.docx``.

A minimal document exercising the ``w:tabs`` / ``w:tab`` elements.
One paragraph declares a custom left-aligned tab stop at 2 inches
(2880 twips) and a single run emits a tab character followed by
visible text. Uses python-docx's stock
``ParagraphFormat.tab_stops.add_tab_stop`` API.
Satisfies the assertions in ``features/docx/tab-stop-custom.json``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document
from docx.enum.text import WD_TAB_ALIGNMENT
from docx.shared import Inches

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "tab-stop-custom.docx"


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph()
    paragraph.paragraph_format.tab_stops.add_tab_stop(
        Inches(2), WD_TAB_ALIGNMENT.LEFT
    )
    paragraph.add_run("\tTab-stopped text")
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


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

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/tab-stop-custom",
  "title": "Custom tab stop",
  "format": "docx",
  "category": "paragraph-layout",
  "summary": "Define a custom left-aligned tab stop at 2 inches on a paragraph.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.1.37",
    "element": "w:tabs",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "<w:tabs> on <w:pPr> holds one or more <w:tab> children, each with w:val (alignment), w:pos (position in twips), and optional w:leader. 1 inch = 1440 twips, so 2 inches = 2880 twips. A tab character ('\\t') in the run text advances to the next defined tab stop."
  },
  "fixtures": {
    "machine": "docx/tab-stop-custom",
    "office": "docx/tab-stop-custom"
  },
  "generator": {
    "python": "scripts/gen_tab_stop_custom.py"
  },
  "assertions": [
    {
      "id": "tabs-element-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[contains(normalize-space(), 'Tab-stopped text')]]/w:pPr/w:tabs",
      "must": "exist",
      "description": "The paragraph must have a <w:tabs> child inside <w:pPr>."
    },
    {
      "id": "tab-left-at-2880",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[contains(normalize-space(), 'Tab-stopped text')]]/w:pPr/w:tabs/w:tab[@w:val='left' and @w:pos='2880']",
      "must": "exist",
      "description": "A left-aligned tab stop at position 2880 twips (2 inches) must be defined."
    }
  ],
  "render_assertions": [
    {
      "id": "tab-stop-text-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper [style*='white-space: pre'], .docx-wrapper [style*='white-space:pre'], .docx-wrapper [data-tab-stop], .docx-wrapper span",
      "must": "match-text",
      "value": "Tab-stopped text",
      "description": "A DOM node preserving tab whitespace or marked [data-tab-stop] must contain the fixture text."
    }
  ]
}