Font Utilities

Custom fonts bundled in asset/font are registered with matplotlib on import, so they are available without manual configuration. Scaling helpers fs, fw, and lw offset the global rcParams base values; plot_fonts previews every installed family.

Tip

For detailed usage examples, weight reference tables, and best practices see Font Utilities.

Quick API

fs(n) — font size + n points.

fw(n) — font weight + 100×*n* (string weights auto-converted).

lw(n) — line width + n.

plot_fonts(font_dir=None, ncols=3, font_size=11)

— returns a Figure with a preview grid of all available families.

Example

import matplotlib.pyplot as plt
import dartwork_mpl as dm

fig, ax = plt.subplots()
ax.set_title("Paper-ready", fontsize=dm.fs(2), fontweight=dm.fw(1))
ax.plot(x, y, lw=dm.lw(0.5))       # base linewidth + 0.5
dm.plot_fonts(ncols=4, font_size=12)  # inspect available families

Font management utilities for Matplotlib.

Registers custom fonts from the package’s asset/font directory with matplotlib’s internal font manager.

class dartwork_mpl.font.FontFamily(name: str, role: Literal['body', 'display', 'kr-body', 'serif', 'mono', 'mono-kr', 'fallback-tail'], job: str, alternates: tuple[str, ...] = (), quirks: tuple[str, ...] = (), weight_exceptions: tuple[int, ...] = ())

Bases: object

Curated job record for a bundled matplotlib font family.

alternates: tuple[str, ...] = ()

property chart_glyphs: tuple[str, ...]

Chart symbols the family’s combined cmap covers, in probe order.

The probe set is minus, times, plus-minus, right arrow, degree, mu, sigma and Delta; a missing symbol falls back to another font.

property hangul: bool

Whether the family’s combined cmap covers the Hangul probe text.

property italic: bool

Whether any bundled file of the family is an italic face.

job: str

property licenses: tuple[str, ...]

Sorted license tags of the bundled files.

Each file is classified from its name table as "Apache-2.0", "OFL-1.1" or "unknown".

property mono: bool

Whether any bundled file is fixed-pitch.

True when the post table flags it or the probe glyphs 0123456789ilW share one advance width.

name: str

property numeric_axes: bool

Whether tick labels line up without OpenType features.

True when the default face (upright, normal width, weight closest to 400) has equal-advance digits, or the family is fixed-pitch.

quirks: tuple[str, ...] = ()

role: Literal['body', 'display', 'kr-body', 'serif', 'mono', 'mono-kr', 'fallback-tail']

property tnum: bool

Alias of tnum_available, kept for backward compatibility.

property tnum_available: bool

Whether any bundled file declares the OpenType tnum feature.

This is browser (CSS) tabular-numeral support; matplotlib does not apply OpenType features, so see numeric_axes for charts.

weight_exceptions: tuple[int, ...] = ()

property weights: tuple[int, ...]

Sorted distinct OS/2 weight classes across the bundled files.

Every measured property reads the bundled font files with fontTools on first access (cached per family) and raises KeyError when the family has no bundled files.

dartwork_mpl.font.css_font_face_name(font_file: str | Path) → str

Return the CSS @font-face family name for a bundled font file.

dartwork_mpl.font.ensure_loaded() → None

Ensure custom fonts are loaded and registered.

Thread-safe: uses double-checked locking to avoid duplicate font registration when called concurrently from multiple threads.

dartwork_mpl.font.font_families() → Mapping[str, FontFamily]

Return the curated bundled-font family registry.

dartwork_mpl.font.get_font_dir() → Path

Return the resolved bundled font asset directory.

dartwork_mpl.font.list_registered() → list[str]

Return sorted bundled font family names registered in matplotlib.

dartwork_mpl.fs(n: int | float) → float

Return the base font size plus n.

Parameters:

n (int | float) – Offset to add to rcParams['font.size']. Positive values increase, negative values decrease.

Returns:

Scaled font size.

Return type:

float

dartwork_mpl.fw(n: int | float) → int

Return the base font weight plus 100 * n.

String weight names (e.g., 'normal', 'bold') are automatically converted to their numeric equivalents (e.g., 400, 700) before computation.

Parameters:

n (int | float) – Number of weight steps to add (each step = 100). For example, n=1 selects one step bolder than the base weight. Fractional steps are allowed but the result is rounded to an int, since matplotlib font weights are integers (0-1000).

Returns:

Computed numeric font weight (always an int — a fractional n is rounded, so the -> int contract holds).

Return type:

int

dartwork_mpl.lw(n: int | float) → float

Return the base line width plus n.

Parameters:

n (int | float) – Offset to add to rcParams['lines.linewidth']. Positive values thicken, negative values thin.

Returns:

Scaled line width.

Return type:

float