Skip to content

Fonts and shaping

Matching and fallback

FontQuery(families, weight=400, width=100, slant='normal', axes=())

Describes preferred families, weight, width, slant, and variation coordinates for font matching.

FontMatch(face, coordinates=(), diagnostics=())

The recorded result of a query, including the selected face and resolved variation coordinates.

FontFace(
    id,
    family,
    subfamily,
    full_name,
    postscript_name,
    weight,
    width,
    slant,
    metrics,
    coverage,
    axes,
    embedding,
    has_math,
    names,
    _data,
)

A snapshot of one usable face, with stable identity, names, metrics, character coverage, and font-table access.

from glyphkit import FontLibrary, FontSource, Paragraph, TextSpan, TextStyle

library = FontLibrary.from_sources(
    (
        FontSource.path("fonts/SourceSans3-Regular.ttf"),
        FontSource.path("fonts/NotoSansTC-Regular.otf"),
    ),
    generic_families={"sans-serif": ("Source Sans 3", "Noto Sans TC")},
)
layout = library.layout(
    Paragraph((TextSpan("效用 U(x)", TextStyle(("sans-serif",), 18)),))
)

The examples use Source Sans 3 and Noto Sans TC, both open-source families available from Google Fonts. The mathematics chapter uses the openly licensed STIX Two Math family.

Face identity comes from the font content's SHA-256 digest and collection index, not its filename. FontManifest records the sources and faces needed to reproduce a layout. Glyph selection, positioning, and variation data use the structures defined by the OpenType specification {Microsoft} (2025).

Unicode shaping

ShapingStyle(
    families,
    size,
    weight=400,
    width=100,
    slant='normal',
    axes=(),
    features=(),
    letter_spacing=0.0,
    word_spacing=0.0,
)

The script, direction, language, OpenType features, and spacing options applied during shaping.

GlyphRun(
    face_id,
    family,
    size,
    direction,
    script,
    language,
    source_range,
    text,
    glyphs,
    diagnostics=(),
    variation_coordinates=(),
    bidi_level=0,
)

A visually ordered run sharing one face and shaping context, with source range and positioned glyphs.

PositionedGlyph(
    face_id,
    glyph_id,
    cluster,
    x,
    y,
    x_advance,
    y_advance,
    x_offset,
    y_offset,
    ink_bounds=None,
    variation_coordinates=(),
)

One glyph id plus its cluster, advance, offsets, and resolved font-face identity.

shape_text(library, text, style, *, language=None, script=None, direction=None) → tuple[GlyphRun, ...]

Shapes Unicode text with explicit fallback and returns backend-neutral glyph ids and positions.

Mixed left-to-right and right-to-left text keeps logical source ranges even when visual runs are reordered, following the logical-versus-visual distinction in the Unicode Bidirectional Algorithm {Unicode Consortium} (2026). A missing glyph raises MissingGlyphError; GlyphKit never swaps in an unconfigured system font silently.

System fonts

discover_system_fonts(provider=None) → FontManifest

Opt-in discovery of installed fonts. For reproducible builds, prefer explicit files or bytes and save the resulting manifest.

Comments