register_font ¶

register_font(
    path: str | PathLike[str], family: str | None = None
) -> list[str]

Register a font file so plots can draw with it.

Every face in the file is registered: a .ttf or .otf holds one, a .ttc/.otc collection several. The family name and the face (plain, bold, italic, bold italic) are read from the font. Register one file per face (or use register_font_dir). A later registration of the same family and face replaces the earlier one. Names match case-insensitively, and a registered family wins over the built-in aliases ("Arial", "sans", ...), which otherwise draw with Liberation Sans.

Parameters:

path (str or PathLike) –

A TrueType or OpenType font file (.ttf, .otf, .ttc, .otc).
family (str or None, default: None ) –

Family name to register the faces under, instead of the name in the file.

Returns:

list of str –

The family names registered, in file order.

Raises:

FontNotFoundError –

If path does not exist.
FontError –

If the file is not a usable font or family is empty.

Notes

A family without the requested face draws its nearest registered face and warns. Characters a font lacks draw as its missing-glyph box. SVG and HTML embed a subset without ligatures; PNG and PDF are exact.

Examples:

>>> from ggrust import *
>>> register_font("fonts/Arial.ttf")
['Arial']
>>> register_font("fonts/Arial Bold.ttf")
['Arial']
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> arial = theme(text=element_text(family="Arial"))
>>> plot = ggplot(data, aes("weight", "mpg")) + geom_point()
>>> plot = plot + arial