Skip to content

theme

theme

The Theme object, the document's theme fonts and colours.

_ThemeFont 

_ThemeFont(fontCollection: object)

One font collection of a theme — its major or minor fonts.

Source code in src/docx/theme.py 
33
34
def __init__(self, fontCollection: object):
    self._fontCollection = fontCollection

latin property 

latin: str | None

The Latin typeface of this collection, e.g. "Calibri".

This is what a minorHAnsi or majorHAnsi theme token resolves to, and the one that matters for a Western document.

east_asian property 

east_asian: str | None

The East Asian typeface of this collection, or None when it sets none.

The default Office theme leaves this empty and relies on the a:font script entries instead, so None here is ordinary rather than exceptional.

complex_script property 

complex_script: str | None

The complex-script typeface of this collection, or None when it sets none.

Theme 

Theme(
    theme: CT_OfficeStyleSheet, part: XmlPart | None = None
)

Bases: ElementProxy

The document's theme: its major and minor fonts and its twelve theme colours.

Reached through Document.theme, which is None for a document carrying no theme part.

The point of exposing it is Font.theme_typeface: a run whose font is set only by a theme token reports None for Font.name, and this is where the concrete typeface behind that token lives.

Source code in src/docx/theme.py 
74
75
76
def __init__(self, theme: CT_OfficeStyleSheet, part: XmlPart | None = None):
    super().__init__(theme, part)  # pyright: ignore[reportArgumentType]
    self._element = theme

name property 

name: str | None

The theme's name, e.g. "Office Theme", or None when it has none.

major_font property 

major_font: _ThemeFont

The theme's major fonts, which Word applies to headings.

minor_font property 

minor_font: _ThemeFont

The theme's minor fonts, which Word applies to body text.

colors property 

colors: dict[str, RGBColor | str | None]

The twelve theme colours, keyed by slot name, in schema order.

typeface 

typeface(theme_token: str) -> str | None

The concrete typeface theme_token names, or None when there is none.

theme_token is a w:rFonts/@w:asciiTheme-style value such as "minorHAnsi". An unrecognised token, and a token whose slot the theme leaves empty, both give None.

Source code in src/docx/theme.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def typeface(self, theme_token: str) -> str | None:
    """The concrete typeface `theme_token` names, or |None| when there is none.

    `theme_token` is a `w:rFonts/@w:asciiTheme`-style value such as ``"minorHAnsi"``.
    An unrecognised token, and a token whose slot the theme leaves empty, both give
    |None|.
    """
    try:
        collection, script = _THEME_TOKENS[theme_token]
    except KeyError:
        return None
    font = self.major_font if collection == "major" else self.minor_font
    return {"latin": font.latin, "ea": font.east_asian, "cs": font.complex_script}[script]

color 

color(name: str) -> RGBColor | str | None

The RGB value of theme colour name, or None when the theme has none.

name is one of dk1, lt1, dk2, lt2, accent1 through accent6, hlink and folHlink — the slot names as they appear in the XML. A MSO_THEME_COLOR member's own spelling differs; this takes the XML one because that is what the theme part is keyed on.

A system colour such as dk1 reports the RGB value the producing application last resolved it to, which is the only concrete value available outside that operating system.

Source code in src/docx/theme.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def color(self, name: str) -> RGBColor | str | None:
    """The RGB value of theme colour `name`, or |None| when the theme has none.

    `name` is one of ``dk1``, ``lt1``, ``dk2``, ``lt2``, ``accent1`` through
    ``accent6``, ``hlink`` and ``folHlink`` — the slot names as they appear in the
    XML. A |MSO_THEME_COLOR| member's own spelling differs; this takes the XML one
    because that is what the theme part is keyed on.

    A system colour such as ``dk1`` reports the RGB value the producing application
    last resolved it to, which is the only concrete value available outside that
    operating system.
    """
    clrScheme = self._element.themeElements.clrScheme
    if name not in clrScheme.slots:
        raise ValueError(
            "no theme color %r; must be one of %s" % (name, ", ".join(clrScheme.slots))
        )
    color = clrScheme.color(name)
    return None if color is None else color.rgb