Skip to content

font

font

Font-related proxy objects.

Font 

Font(r: CT_R, parent: Any | None = None)

Bases: ElementProxy

Proxy object for parent of a <w:rPr> element and providing access to character properties such as font name, font size, bold, and subscript.

Source code in src/docx/text/font.py 
22
23
24
25
def __init__(self, r: CT_R, parent: Any | None = None):
    super().__init__(r, parent)
    self._element = r
    self._r = r

all_caps property writable 

all_caps: bool | None

Read/write.

Causes text in this font to appear in capital letters.

bold property writable 

bold: bool | None

Read/write.

Causes text in this font to appear in bold.

color property 

color

A ColorFormat object providing a way to get and set the text color for this font.

complex_script property writable 

complex_script: bool | None

Read/write tri-state value.

When True, causes the characters in the run to be treated as complex script regardless of their Unicode values.

cs_bold property writable 

cs_bold: bool | None

Read/write tri-state value.

When True, causes the complex script characters in the run to be displayed in bold typeface.

cs_italic property writable 

cs_italic: bool | None

Read/write tri-state value.

When True, causes the complex script characters in the run to be displayed in italic typeface.

cs_name property writable 

cs_name: str | None

The typeface name applied to complex-script characters in this run.

w:rFonts has four independent typeface slots and Word chooses between them per character, according to the script that character belongs to. This is the slot used for Arabic, Hebrew and other complex scripts. None indicates the typeface is inherited from the style hierarchy.

cs_size property writable 

cs_size: Length | None

The font size applied to complex-script characters in this run.

Word tracks this separately from .size, in w:szCs. None indicates the size is inherited from the style hierarchy.

east_asia_name property writable 

east_asia_name: str | None

The typeface name applied to East Asian characters in this run.

This is the slot that carries the meaningful typeface for Chinese, Japanese and Korean text; see .cs_name for the four-slot arrangement. None indicates the typeface is inherited from the style hierarchy.

hint property writable 

hint: WD_FONT_HINT | None

Member of WdFontHint, or None when no hint is specified.

Tells Word which typeface slot to prefer for a character that belongs to no particular script, such as a space or a digit. This matters for correct East Asian rendering, where an unhinted run mixes typefaces mid-word.

double_strike property writable 

double_strike: bool | None

Read/write tri-state value.

When True, causes the text in the run to appear with double strikethrough.

emboss property writable 

emboss: bool | None

Read/write tri-state value.

When True, causes the text in the run to appear as if raised off the page in relief.

hidden property writable 

hidden: bool | None

Read/write tri-state value.

When True, causes the text in the run to be hidden from display, unless applications settings force hidden text to be shown.

highlight_color property writable 

highlight_color: WD_COLOR_INDEX | None

Color of highlighing applied or None if not highlighted.

italic property writable 

italic: bool | None

Read/write tri-state value.

When True, causes the text of the run to appear in italics. None indicates the effective value is inherited from the style hierarchy.

imprint property writable 

imprint: bool | None

Read/write tri-state value.

When True, causes the text in the run to appear as if pressed into the page.

math property writable 

math: bool | None

Read/write tri-state value.

When True, specifies this run contains WML that should be handled as though it was Office Open XML Math.

name property writable 

name: str | None

The typeface name for this Font.

Causes the text it controls to appear in the named font, if a matching font is found. None indicates the typeface is inherited from the style hierarchy.

This is the w:ascii slot of w:rFonts, and assigning to it also sets w:hAnsi, which is what Word does. It deliberately does not fall back to the other slots: a run can name a different typeface for East Asian (.east_asia_name) and complex-script (.cs_name) characters, Word picks between them per character, and reporting one of them as "the" font would be an approximation dressed up as an answer. A run with only w:eastAsia set therefore reports None here and its typeface through .east_asia_name.

theme property writable 

theme: str | None

The theme typeface slot for this Font, e.g. "minorHAnsi".

The named slot is resolved against the document theme, so the text follows the theme font rather than a font named outright. None indicates no theme typeface is assigned and the typeface is inherited from the style hierarchy.

theme_typeface property 

theme_typeface: str | None

The concrete typeface this font's theme slot resolves to, or None.

theme gives the token — "minorHAnsi" — and this gives the font name it stands for, by looking the token up in the document's theme part:

>>> run.font.theme
'minorHAnsi'
>>> run.font.theme_typeface
'Calibri'

None when the run has no theme slot, when the document carries no theme part, or when the theme leaves that slot empty. This resolves the run's own theme token only; it does not walk the style hierarchy, so a run whose theme font comes from its style reads None here as it does from theme.

scaling property writable 

scaling: int | None

Horizontal character scaling, as a whole percentage of normal width.

100 is normal width, 200 stretches each glyph to double width and 50 condenses it to half. Valid values run from 1 to 600. None indicates the value is inherited from the style hierarchy.

Note this scales glyphs horizontally only; use .size to change font height.

shading_fill property writable 

shading_fill: RGBColor | str | None

Background shading color behind the text of this run.

An RGBColor value, the string "auto", or None when no shading is applied. Assigning a hex string such as "FF0000" or "#FF0000" is also accepted.

This is distinct from .highlight_color, which takes a WD_COLOR_INDEX member and is limited to Word's fixed highlighter palette. Shading accepts any RGB value. Word renders both, with highlighting drawn over shading.

shading_pattern property writable 

shading_pattern: WD_SHADING_PATTERN | None

The pattern drawn over the shading behind the text of this run.

A WD_SHADING_PATTERN member, or None when no shading is applied. Word writes |WD_SHADING_PATTERN.CLEAR| for an ordinary background color, which is what .shading_fill produces on its own.

Assigning None removes the shading entirely, the same as assigning None to .shading_fill.

shading_color property writable 

shading_color: RGBColor | str | None

The foreground color of the shading pattern behind the text of this run.

An RGBColor value, the string "auto", or None. This is the color the .shading_pattern is drawn in; .shading_fill is the color behind it. For the usual |WD_SHADING_PATTERN.CLEAR| pattern nothing is drawn and this has no visible effect.

no_proof property writable 

no_proof: bool | None

Read/write tri-state value.

When True, specifies that the contents of this run should not report any errors when the document is scanned for spelling and grammar.

outline property writable 

outline: bool | None

Read/write tri-state value.

When True causes the characters in the run to appear as if they have an outline, by drawing a one pixel wide border around the inside and outside borders of each character glyph.

rtl property writable 

rtl: bool | None

Read/write tri-state value.

When True causes the text in the run to have right-to-left characteristics.

shadow property writable 

shadow: bool | None

Read/write tri-state value.

When True causes the text in the run to appear as if each character has a shadow.

size property writable 

size: Length | None

Font height in English Metric Units (EMU).

None indicates the font size should be inherited from the style hierarchy. Length is a subclass of int having properties for convenient conversion into points or other length units. The docx.shared.Pt class allows convenient specification of point values:

>>> font.size = Pt(24)
>>> font.size
304800
>>> font.size.pt
24.0

small_caps property writable 

small_caps: bool | None

Read/write tri-state value.

When True causes the lowercase characters in the run to appear as capital letters two points smaller than the font size specified for the run.

snap_to_grid property writable 

snap_to_grid: bool | None

Read/write tri-state value.

When True causes the run to use the document grid characters per line settings defined in the docGrid element when laying out the characters in this run.

spec_vanish property writable 

spec_vanish: bool | None

Read/write tri-state value.

When True, specifies that the given run shall always behave as if it is hidden, even when hidden text is being displayed in the current document. The property has a very narrow, specialized use related to the table of contents. Consult the spec (§17.3.2.36) for more details.

strike property writable 

strike: bool | None

Read/write tri-state value.

When True causes the text in the run to appear with a single horizontal line through the center of the line.

subscript property writable 

subscript: bool | None

Boolean indicating whether the characters in this Font appear as subscript.

None indicates the subscript/subscript value is inherited from the style hierarchy.

superscript property writable 

superscript: bool | None

Boolean indicating whether the characters in this Font appear as superscript.

None indicates the subscript/superscript value is inherited from the style hierarchy.

underline property writable 

underline: bool | WD_UNDERLINE | None

The underline style for this Font.

The value is one of None, True, False, or a member of WdUnderline.

None indicates the font inherits its underline value from the style hierarchy. False indicates no underline. True indicates single underline. The values from WdUnderline are used to specify other outline styles such as double, wavy, and dotted.

web_hidden property writable 

web_hidden: bool | None

Read/write tri-state value.

When True, specifies that the contents of this run shall be hidden when the document is displayed in web page view.