API Reference

Rendering

render(text, *, spans=(), font=None, size=12.0, weight=Weight.NORMAL, style=Style.NORMAL, variations=None, width=None, alignment=Alignment.LEFT, line_spacing=None, justify=False, indent=0.0, disable_ligatures=False)

Render literal plain text to SVG and structured layout metadata.

text is never interpreted as markup. Use render_markup() for Pango markup, or use spans to style ranges of plain text in the same native layout.

Parameters:

  • text (str) – Literal Unicode text to render, without embedded NUL characters.

  • spans (Sequence[TextSpan]) – TextSpan instances for half-open code-point ranges of text. Compatible overlaps compose; conflicting values raise ValueError.

  • font (str | None) – Font family name without embedded NUL characters, or None for Pango’s default family. To use a font file that is not installed system-wide, register it first with register_font().

  • size (float) – Positive absolute font size in SVG user-space units.

  • weight (Weight | int) – Base Weight/integer and Style for text not overridden by a span.

  • style (Style) – Base Weight/integer and Style for text not overridden by a span.

  • variations (Mapping[str, float] | None) – Mapping of four-printable-ASCII-character OpenType variation-axis tags to finite numeric values. Settings are forwarded to Pango; visible effects depend on the selected font, axis, and renderer backend.

  • width (float | None) – Positive wrapping width in SVG user-space units, or None for no width constraint.

  • alignment (Alignment) – Horizontal alignment within width.

  • line_spacing (float | None) – Positive Pango line-spacing multiplier, or None for Pango’s default line spacing.

  • justify (bool) – Whether Pango justifies wrapped lines.

  • indent (float) – Pango indentation in SVG user-space units; negative values create a hanging indentation.

  • disable_ligatures (bool) – Disable Pango’s standard, discretionary, contextual, historical, and contextual-alternate features (liga, dlig, clig, hlig, and calt). This setting takes precedence over conflicting feature declarations in spans or markup.

Returns:

SVG output plus viewport, bounds, baseline, and per-line metadata.

Return type:

RenderedText

Raises:
render_markup(markup, *, font=None, size=12.0, weight=Weight.NORMAL, style=Style.NORMAL, variations=None, width=None, alignment=Alignment.LEFT, line_spacing=None, justify=False, indent=0.0, disable_ligatures=False)

Render Pango markup to SVG and structured layout metadata.

markup is parsed by Pango; do not pass markup to render(). The layout options have the same meanings as in render(), except range styling is expressed in markup rather than with TextSpan. Line offsets in the returned RenderedText refer to Pango’s parsed text, not character offsets in the markup source.

Parameters:
Return type:

RenderedText

Notes

All remaining options have the same contracts as in render(); markup expresses range styling instead of accepting TextSpan objects.

Returns:

SVG output plus viewport, bounds, baseline, and per-line metadata.

Return type:

RenderedText

Raises:
Parameters:
validate_markup(markup)

Validate a Pango markup string without rendering it.

Returns an empty string when markup is valid. Otherwise returns a diagnostic explaining why it is invalid. render_markup() turns that diagnostic into MarkupError. Embedded NUL characters are rejected before Pango parses the source.

Raises:

TypeError – If markup is not a string.

Parameters:

markup (str)

Return type:

str

Text Models

class TextSpan(start, end, font=None, size=None, weight=None, style=None, foreground=None, features=None, variations=None)

Style attributes for a half-open code-point range of plain text.

Pass spans to manimpango.render(); markup has its own styling syntax and is rendered with manimpango.render_markup(). Overlap is supported when spans set different attributes. Overlapping spans may not give different values to the same scalar attribute or OpenType tag.

Parameters:
start, end

Python code-point offsets satisfying 0 <= start <= end <= len(text). The range includes start and excludes end, matching slicing.

font

Font family name without embedded NUL characters for the range, or None to inherit the render call’s font.

Type:

str | None

size

Positive absolute size in SVG user-space units, or None to inherit the render call’s size.

Type:

float | None

weight

A Weight member or integer from 1 through 1000.

Type:

manimpango.enums.Weight | int | None

style

A Style member.

Type:

manimpango.enums.Style | None

foreground

A Pango foreground-color specification without embedded NUL characters, such as "#3366cc".

Type:

str | None

features

Mapping of four-printable-ASCII-character OpenType feature tags to integer or boolean values. Boolean values are converted to 0 or 1. When manimpango.render() is called with disable_ligatures=True, that setting overrides values for its ligature-related tags.

Type:

collections.abc.Mapping[str, int | bool] | None

variations

Mapping of four-printable-ASCII-character OpenType variation-axis tags to finite numeric values. Settings are forwarded to Pango; visible effects depend on the selected font, axis, and renderer backend.

Type:

collections.abc.Mapping[str, float] | None

class Bounds(x, y, width, height)

A rectangle in the rendered SVG coordinate system.

Parameters:
x, y

Position of the rectangle’s upper-left corner in SVG user-space units.

width, height

Non-negative dimensions in the same coordinate system.

class LineInfo(text, start, end, bounds, baseline)

Text and geometry for one rendered line.

For manimpango.render(), start and end are half-open Python code-point offsets into the input text. For manimpango.render_markup(), they index Pango’s parsed text rather than the markup source. Pango line separators are excluded from every line range.

Parameters:
text

Parsed text rendered on this line, without a trailing Pango line separator.

Type:

str

start, end

Half-open Python code-point offsets for text in the appropriate rendered-text source.

bounds

Logical bounds of this line in SVG user-space coordinates.

Type:

manimpango._text.Bounds

baseline

Baseline position in SVG user-space coordinates.

Type:

float

class RenderedText(svg, width, height, baseline, lines, ink_bounds, logical_bounds)

Immutable SVG output and layout metadata from one render operation.

All geometry uses the same SVG user-space coordinate system as svg. The object is frozen and lines is always a tuple.

Parameters:
svg

Complete SVG document as a Unicode string.

Type:

str

width, height

Dimensions of the SVG viewport in user-space units.

baseline

Baseline of the first layout line in user-space units.

Type:

float

lines

Per-line text and geometry, in rendering order.

Type:

tuple[manimpango._text.LineInfo, …]

ink_bounds

Union of the Pango ink extents: the area touched by glyph drawing.

Type:

manimpango._text.Bounds

logical_bounds

Union of the Pango logical extents, including layout advances such as whitespace.

Type:

manimpango._text.Bounds

property line_count: int

Number of lines in the result.

save(path)

Write the SVG as UTF-8.

Existing files are overwritten. The destination parent must already exist; filesystem errors are propagated to the caller.

Parameters:

path (str | Path)

Return type:

None

Font Management

register_font(font_path)

Register a font file and return an explicit lifetime handle.

Each call returns a distinct handle. The file path is expanded and resolved strictly before entering the native backend. The font becomes visible to this renderer’s font map immediately and remains available until the final handle for that normalized path is closed.

Use the returned handle as a context manager for temporary registrations. Multiple handles for the same file are reference-counted, so closing one cannot remove a font still used by another.

Raises:
Parameters:

font_path (str | Path)

Return type:

FontRegistration

class FontRegistration(path, *, _token=None)

An explicit, reference-counted registration of a font file.

Instances are returned by register_font(). Closing one handle does not affect other handles for the same normalized path; native unregistration occurs only after the final handle closes. Use the handle as a context manager when the font is needed only for a bounded operation. Unclosed handles intentionally remain active until process exit.

Do not instantiate this class directly; obtain it from register_font().

Parameters:

  • path (Path)

  • _token (object | None)

close()

Release this handle’s registration reference, idempotently.

The font remains available while another handle for the same path is open. The final close removes it from subsequent renderer-owned font maps and can raise FontRegistrationError if the native backend cannot complete that transition.

Return type:

None

property closed: bool

Whether this handle has released its registration reference.

property path: Path

The absolute, normalized font-file path.

list_fonts()

Return sorted unique family names visible to the renderer’s font map.

The result includes currently registered custom fonts and is a snapshot; closing a FontRegistration can change later calls.

Return type:

list[str]

Enumerations

class Style(value)

Font slant style.

NORMAL

The font is upright.

ITALIC

The font uses its italic face when available.

OBLIQUE

The font is slanted from its upright face when available.

class Weight(value)

Font weight (boldness).

This enum inherits from both int and Enum to allow arbitrary integer values (1-1000) for variable font support. The named members are convenience aliases for standard CSS/OpenType weight values.

Examples

Using named weights:

Weight.NORMAL   # 400
Weight.BOLD    # 700

Using arbitrary integer values (useful for variable fonts):

Weight(450)    # 450
550            # directly passed to render()
THIN

Weight 100 (Since: Pango 1.24)

Type:

int

ULTRALIGHT

Weight 200

Type:

int

LIGHT

Weight 300

Type:

int

SEMILIGHT

Weight 350 (Since: Pango 1.36.7)

Type:

int

BOOK

Weight 380 (Since: Pango 1.24)

Type:

int

NORMAL

Weight 400

Type:

int

MEDIUM

Weight 500 (Since: Pango 1.24)

Type:

int

SEMIBOLD

Weight 600

Type:

int

BOLD

Weight 700

Type:

int

ULTRABOLD

Weight 800

Type:

int

HEAVY

Weight 900

Type:

int

ULTRAHEAVY

Weight 1000 (Since: Pango 1.24)

Type:

int

class Alignment(value)

Text alignment within a layout.

LEFT

Align text to the left.

CENTER

Align text to the center.

RIGHT

Align text to the right.

Exceptions

exception ManimPangoError

Base class for ManimPango-specific failures.

exception RenderError

Raised when Pango or Cairo fails during a native render operation.

Invalid public arguments continue to raise TypeError or ValueError, and invalid markup raises MarkupError.

exception MarkupError

Raised when Pango markup is malformed.

exception FontError

Base class for font-related failures.

exception FontNotFoundError

Raised when a requested font file does not exist.

exception FontRegistrationError

Raised when a font backend rejects a font registration.

Version Information

get_version_info()

Return version strings for ManimPango and its linked libraries.

Returns:

A mapping with the stable keys "manimpango", "pango", and "cairo".

Return type:

dict[str, str]

__version__

The installed ManimPango version string.