docx/character-style-builtin

Parameter axes

• style (17 values): strong, emphasis, subtle-emphasis, intense-emphasis, subtle-reference, intense-reference, book-title, header-char, footer-char, heading-1-char, heading-2-char, heading-3-char, title-char, subtitle-char, body-text-char, quote-char, intense-quote-char

Spec notes

Generator source

scripts/gen_character_style_builtin.py — runs with --arg_template --style-id {style.style_id} --out fixtures/docx/character-style-builtin--{style.id}.docx

#!/usr/bin/env python3
"""Generate ``fixtures/docx/character-style-builtin--<style-id>.docx`` fixtures.

Parameterised generator driven by
``features/docx/character-style-builtin.json``. For each built-in Word
**character** style (``WD_STYLE_TYPE.CHARACTER``), produce a
single-paragraph document containing one run whose ``w:rPr`` carries
``<w:rStyle w:val="<StyleId>"/>``.

This is the character-style companion to ``gen_style_builtin.py``
(which handles paragraph-type styles). Character styles differ from
paragraph styles in that they apply to a run of text rather than a
whole paragraph, and are encoded as ``<w:rPr><w:rStyle w:val=...>``
rather than ``<w:pPr><w:pStyle w:val=...>``.

The manifest passes the pascal-case ``--style-id`` (e.g.
``IntenseEmphasis``, ``BookTitle``, ``Heading1Char``). The script
looks up the matching ``Style`` object by scanning ``doc.styles`` so
the deprecated ``doc.styles[style_id]`` lookup is avoided, then
assigns it to a freshly added run via ``run.style = style``.
"""

from __future__ import annotations

import argparse
from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent


def _write(style_id: str, out: Path) -> None:
    doc = Document()
    style = None
    for candidate in doc.styles:
        if getattr(candidate, "style_id", None) == style_id:
            style = candidate
            break
    if style is None:
        raise SystemExit(
            f"Built-in character style {style_id!r} not found in the default template"
        )
    paragraph = doc.add_paragraph()
    run = paragraph.add_run("Styled character run")
    run.style = style
    out.parent.mkdir(parents=True, exist_ok=True)
    doc.save(out, reproducible=True)


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--style-id",
        required=True,
        help="Built-in character style identifier (e.g. 'Emphasis', 'BookTitle').",
    )
    parser.add_argument("--out", required=True, help="Output .docx path.")
    args = parser.parse_args()

    out_path = Path(args.out)
    if not out_path.is_absolute():
        out_path = _REPO_ROOT / out_path
    _write(args.style_id, out_path)
    print(out_path)
    return 0


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

Manifest (parent, unexpanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/character-style-builtin",
  "kind": "parameterised",
  "title": "Built-in character styles",
  "format": "docx",
  "category": "styles",
  "summary": "Apply each built-in Word character style (Emphasis, Strong, Book Title, Subtle/Intense Emphasis/Reference, linked *Char companions) to a run via <w:rPr><w:rStyle w:val=\"<StyleId>\"/></w:rPr>.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.7",
    "element": "w:rStyle",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "Character-type styles (ST_StyleType 'character') ship in Word's default styles.xml and are referenced from a run via <w:rPr><w:rStyle w:val=\"<StyleId>\"/></w:rPr>. The style_id is the whitespace-collapsed pascal-case identifier ('Emphasis', 'SubtleEmphasis', 'IntenseReference', 'BookTitle', 'Heading1Char', ...) while the display name shown in Word's UI may include spaces ('Subtle Emphasis', 'Book Title', 'Heading 1 Char'). This manifest is the character-style companion to docx/style-builtin (paragraph styles) and enumerates a representative sample of every character-type style that ships in python-docx's default document template. Excluded: (1) 'DefaultParagraphFont' — the default character style, which is never emitted as an explicit <w:rStyle> (runs without an explicit style inherit from it silently); (2) less-common linked *Char companions for Heading4-9, BodyText2, BodyText3, and MacroText, kept off the axis to keep the family within the 10-20 case guideline. Clause 17.7 of ECMA-376 Part 1 covers style definitions in general; 17.7.4.19 specifies w:rStyle specifically, and 17.9.21 lists the reserved built-in style identifiers including the *Char linked variants Word emits alongside paragraph styles that declare w:link."
  },
  "fixtures": {
    "machine": "docx/character-style-builtin"
  },
  "generator": {
    "python": "scripts/gen_character_style_builtin.py",
    "arg_template": "--style-id {style.style_id} --out fixtures/docx/character-style-builtin--{style.id}.docx"
  },
  "parameters": {
    "style": [
      {
        "id": "strong",
        "style_id": "Strong",
        "display": "Strong"
      },
      {
        "id": "emphasis",
        "style_id": "Emphasis",
        "display": "Emphasis"
      },
      {
        "id": "subtle-emphasis",
        "style_id": "SubtleEmphasis",
        "display": "Subtle Emphasis"
      },
      {
        "id": "intense-emphasis",
        "style_id": "IntenseEmphasis",
        "display": "Intense Emphasis"
      },
      {
        "id": "subtle-reference",
        "style_id": "SubtleReference",
        "display": "Subtle Reference"
      },
      {
        "id": "intense-reference",
        "style_id": "IntenseReference",
        "display": "Intense Reference"
      },
      {
        "id": "book-title",
        "style_id": "BookTitle",
        "display": "Book Title"
      },
      {
        "id": "header-char",
        "style_id": "HeaderChar",
        "display": "Header Char"
      },
      {
        "id": "footer-char",
        "style_id": "FooterChar",
        "display": "Footer Char"
      },
      {
        "id": "heading-1-char",
        "style_id": "Heading1Char",
        "display": "Heading 1 Char"
      },
      {
        "id": "heading-2-char",
        "style_id": "Heading2Char",
        "display": "Heading 2 Char"
      },
      {
        "id": "heading-3-char",
        "style_id": "Heading3Char",
        "display": "Heading 3 Char"
      },
      {
        "id": "title-char",
        "style_id": "TitleChar",
        "display": "Title Char"
      },
      {
        "id": "subtitle-char",
        "style_id": "SubtitleChar",
        "display": "Subtitle Char"
      },
      {
        "id": "body-text-char",
        "style_id": "BodyTextChar",
        "display": "Body Text Char"
      },
      {
        "id": "quote-char",
        "style_id": "QuoteChar",
        "display": "Quote Char"
      },
      {
        "id": "intense-quote-char",
        "style_id": "IntenseQuoteChar",
        "display": "Intense Quote Char"
      }
    ]
  },
  "assertions_template": [
    {
      "id": "rstyle-present-{style.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:r/w:rPr/w:rStyle",
      "must": "exist",
      "description": "The sample run must carry a <w:rStyle> inside its <w:rPr>."
    },
    {
      "id": "rstyle-is-{style.id}",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:r/w:rPr/w:rStyle/@w:val",
      "must": "equal",
      "value": "{style.style_id}",
      "description": "The rStyle value must equal the built-in character style identifier '{style.style_id}' (display name: '{style.display}')."
    }
  ]
}