Coverage for src/manimgx/mobjects/code.py: 97%
146 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1"""Code: a highlighted listing set by Typst's `raw`. Its grammars find the tokens; a theme
2colors each scope as the pygments style colors the token there. With a monospaced font and
3one glyph per character, column advances are rounded to whole Pango units."""
5import math
6import re
7from collections.abc import Mapping
8from dataclasses import dataclass
9from functools import cache
10from pathlib import Path
11from typing import ClassVar, Literal
13from typing_extensions import TypedDict
15from manimgx.caches import forgets
16from manimgx.constants import LEFT, ORIGIN, RIGHT, SCALE_FACTOR_PER_FONT_POINT, UP
17from manimgx.drawing.paint import WHITE, ManimColor
18from manimgx.drawing.typesetting import typst_string
19from manimgx.mobject import Mobject, VGroup, VMobject
20from manimgx.mobjects.annotations import FrameOptions, SurroundingRectangle
21from manimgx.mobjects.shapes import Dot, Line
22from manimgx.mobjects.text import Typst
23from manimgx.typing import StrPath
25__all__ = ["Code"]
27# CE's Text asks Pango for font_size / 4.8 points, set at 96 dpi, and its line spacing / 4.8 in
28# Pango's units; CE takes 0.05 scene units for one. Typst sets the code in points that stand for
29# Pango's units: a Typst mobject's scene units per point are its font_size / 960.
30_PANGO_PER_FONT_SIZE = 1 / 4.8
31_UNITS_PER_POINT = 96 / 72
32_SCENE_PER_UNIT = 0.05
33_POINT = _SCENE_PER_UNIT / SCALE_FACTOR_PER_FONT_POINT
34_LINE_SPACING = 0.3 # CE's Text's, for a line_spacing of -1
36_PYTHON = frozenset({"python", "py", "python3", "py3"})
37_LINE = "line" # a line's label: "line1" the first
38# pygments' Python lexer: these are builtins wherever they stand, parameters too
39_PSEUDO_BUILTINS = re.compile(r"(?<![.\w])(?:self|cls)\b")
41type CodeStyle = Literal["vim"]
44@dataclass(frozen=True, slots=True)
45class _Style:
46 """A pygments style for Typst: its background, text and line-number colors, and a theme
47 coloring each grammar scope as the style colors the token there."""
49 background: str
50 foreground: str
51 line_numbers: str
52 builtins: str # pygments' pseudo-builtins (Python's self and cls)
53 theme: Mapping[str, str] # scope selector: color
56_STYLES: dict[CodeStyle, _Style] = {
57 "vim": _Style(
58 background="#000000",
59 foreground="#cccccc",
60 line_numbers="#cccccc", # the style's "inherit": the text's color
61 builtins="#cd00cd",
62 theme={
63 # Comment
64 "comment": "#000080",
65 # Keyword, Keyword.Constant, Operator.Word
66 "keyword": "#cdcd00",
67 "storage.modifier": "#cdcd00",
68 "constant.language": "#cdcd00",
69 "keyword.operator.logical": "#cdcd00",
70 "keyword.control.import.as": "#cdcd00",
71 # Keyword.Namespace
72 "keyword.control.import": "#cd00cd",
73 # Operator ("." and "->" among them, but for a module's path)
74 "keyword.operator": "#3399cc",
75 "punctuation.accessor": "#3399cc",
76 "punctuation.separator.annotation.return": "#3399cc",
77 "meta.statement.import punctuation.accessor": "#cccccc",
78 # Name.Class, Name.Variable.Magic
79 "entity.name.class": "#00cdcd",
80 "support.variable.magic": "#00cdcd",
81 # Name.Builtin, Name.Exception
82 "support.function.builtin": "#cd00cd",
83 "support.type": "#cd00cd",
84 "support.type.exception": "#666699",
85 # Name.Decorator: a decorator is plain text, builtin or not
86 "meta.annotation support.function.builtin": "#cccccc",
87 "meta.annotation support.type": "#cccccc",
88 # String: its prefix, escapes, placeholders, a regex's syntax, a docstring, and
89 # an f-string's braces, conversion and format
90 "string": "#cd0000",
91 "string keyword": "#cd0000",
92 "string keyword.operator": "#cd0000",
93 "string constant": "#cd0000",
94 "storage.type.string": "#cd0000",
95 "constant.character.escape": "#cd0000",
96 "comment.block.documentation": "#cd0000",
97 "punctuation.section.interpolation": "#cd0000",
98 "storage.modifier.conversion": "#cd0000",
99 "constant.other.format-spec": "#cd0000",
100 # Number
101 "constant.numeric": "#cd00cd",
102 },
103 ),
104}
107class CodeText(TypedDict, total=False):
108 """The text of a [Code][manimgx.Code] listing: its `paragraph_config`, the text
109 keywords that apply to a listing."""
111 font: str
112 """The font family: "Monospace", the default, is the bundled DejaVu Sans Mono on
113 every platform; any other family is one manimgx ships, or else the system's."""
114 font_size: float
115 """The size of the text: an em is `font_size / 72` scene units (default 24)."""
116 line_spacing: float
117 """How far apart the lines are, beyond the font size: their baselines are
118 `(1 + line_spacing) * font_size / 96` scene units apart (default 0.5; -1 for
119 0.3)."""
120 disable_ligatures: bool
121 """Whether every character is a glyph of its own, with no ligatures (default
122 True)."""
125def _theme(style: _Style) -> str:
126 """The style as a TextMate theme (Typst takes only the scopes' colors from it)."""
127 rules = "".join(
128 f"<dict><key>scope</key><string>{scope}</string><key>settings</key><dict>"
129 f"<key>foreground</key><string>{color}</string></dict></dict>"
130 for scope, color in style.theme.items()
131 )
132 return (
133 '<?xml version="1.0" encoding="UTF-8"?><plist version="1.0"><dict>'
134 "<key>settings</key><array><dict><key>settings</key><dict><key>foreground</key>"
135 f"<string>{style.foreground}</string></dict></dict>{rules}</array></dict></plist>"
136 )
139@forgets
140@cache
141def _advance(face: str) -> float:
142 """A character's advance in `face`, in scene units, as Typst sets it: the font's own."""
143 first, second = Typst(f"#set text({face})\n00", font_size=_POINT).submobjects
144 return second.get_left()[0] - first.get_left()[0]
147def _typeset(
148 lines: list[str],
149 text: CodeText,
150 color: str,
151 *,
152 style: _Style | None = None,
153 language: str | None = None,
154 suffix: str = "",
155) -> list[VGroup]:
156 """Each line's glyphs, with fixed baseline spacing and adjusted monospaced columns,
157 highlighted in `style` if given; `suffix` closes the first and last lines.
158 """
159 size = text.get("font_size", 24)
160 spacing = text.get("line_spacing", -1)
161 em = size * _PANGO_PER_FONT_SIZE * _UNITS_PER_POINT
162 pitch = size * (1 + (_LINE_SPACING if spacing == -1 else spacing))
163 pitch *= _PANGO_PER_FONT_SIZE
164 font = text.get("font", "Monospace")
165 family = "DejaVu Sans Mono" if font == "Monospace" else font
166 face = f"font: {typst_string(family)}, size: {em}pt"
167 ligatures = "false" if text.get("disable_ligatures", True) else "true"
168 closing = (
169 f"; if it.number in (1, it.count) {{ {typst_string(suffix)} }}"
170 if suffix
171 else ""
172 )
173 highlighting = (
174 f"lang: {typst_string(language) if language else 'none'},"
175 f" theme: {f'bytes({typst_string(_theme(style))})' if style else 'none'}"
176 )
177 source = (
178 f'#set text({face}, fill: rgb("{color}"), ligatures: {ligatures},'
179 ' top-edge: "baseline", bottom-edge: "baseline")\n'
180 f"#set par(leading: {pitch}pt)\n"
181 f"#show raw: set text({face})\n"
182 # each line labelled, its glyphs a group of their own
183 f"#show raw.line: it => [#box({{ it.body{closing} }})"
184 f'#label("{_LINE}" + str(it.number))]\n'
185 f"#raw({typst_string(chr(10).join(lines))}, block: true, {highlighting})"
186 )
187 groups = Typst(source, font_size=_POINT, color=color).labels
188 empty = VGroup()
189 rows = [
190 VGroup(*groups.get(f"{_LINE}{n}", empty).submobjects)
191 for n in range(1, len(lines) + 1)
192 ]
193 # Typst advances a character by the font's own width, Pango by that rounded to a whole
194 # unit: each column moves by the difference, times the columns before it. A line whose
195 # glyphs are not one a character (a ligature, a cluster) stays as Typst set it.
196 advance = _advance(face)
197 step = math.floor(advance / _SCENE_PER_UNIT + 0.5) * _SCENE_PER_UNIT
198 at: dict[int, list[Mobject]] = {}
199 plain = ManimColor(color)
200 python = language is not None and language.lower() in _PYTHON
201 builtins = style.builtins if style is not None and python else None
202 last = len(lines) - 1
203 for i, (line, row) in enumerate(zip(lines, rows)):
204 closed = line + suffix if i in (0, last) else line
205 columns = [c for c, ch in enumerate(closed) if not ch.isspace()]
206 if len(columns) != len(row.submobjects):
207 continue
208 glyph_at = dict(zip(columns, row.submobjects))
209 for column, glyph in glyph_at.items():
210 at.setdefault(column, []).append(glyph)
211 if builtins is None:
212 continue
213 for match in _PSEUDO_BUILTINS.finditer(line):
214 word = VGroup(*(glyph_at[c] for c in range(*match.span())))
215 if all(glyph.get_fill_color() == plain for glyph in word):
216 word.set_fill(builtins) # not in a string or a comment
217 for column, placed in at.items():
218 offset = RIGHT * column * (step - advance)
219 for glyph in placed:
220 glyph._geometry = glyph._geometry.translated(offset)
221 return rows
224class Code(VMobject):
225 r"""A listing of source code, highlighted: its lines, their numbers, and a rectangle
226 or a window behind them.
228 The code is highlighted by Typst's grammars, in the colors of `formatter_style`, with
229 a monospaced font by default. The parts are
230 [background][manimgx.Code.background], [line_numbers][manimgx.Code.line_numbers] (if
231 the lines are numbered) and [code_lines][manimgx.Code.code_lines], whose i-th part is
232 the i-th line, a group of its glyphs, spaces excluded. Tabs are expanded, and empty
233 lines at the start and at the end are dropped.
235 Args:
236 code_file: A file to read the code from (UTF-8); its extension names the
237 language unless `language` does.
238 code_string: The code, when there is no `code_file`; one of the two is needed
239 (ValueError otherwise).
240 language: The language to highlight the code as, by name or file extension
241 ("python", "rust", "cpp", "js", …: those Typst's `raw` knows); None, or a
242 language it doesn't know, for plain text.
243 formatter_style: The colors: "vim", the only style, on a black background.
244 tab_width: How many columns apart the tab stops are.
245 add_line_numbers: Whether the lines are numbered, on their left.
246 line_numbers_from: The first line's number.
247 background: "rectangle", or "window": a rectangle with a window's three buttons
248 at its top.
249 background_config: [Surrounding rectangle
250 keywords][manimgx.mobjects.annotations.FrameOptions] for the
251 background, over `default_background_config`: a margin of 0.3, round
252 corners, a thin white outline, and the style's background color.
253 paragraph_config: [Code text
254 keywords][manimgx.mobjects.code.CodeText] for the text, over
255 `default_paragraph_config`.
257 Examples:
258 ```python
259 import manimgx as m
262 class CodeExample(m.Scene):
263 def construct(self) -> None:
264 python = m.Code(
265 code_string='def greet(name):\n return f"Hello, {name}!"\n',
266 language="python",
267 )
268 rust = m.Code(
269 code_string='fn main() {\n println!("Hello!");\n}\n',
270 language="rust",
271 background="window",
272 add_line_numbers=False,
273 )
274 self.add(m.VGroup(python, rust).arrange(m.DOWN, buff=0.5).scale(1.4))
275 ```
276 """
278 default_background_config: ClassVar[FrameOptions] = {
279 "buff": 0.3,
280 "stroke_color": WHITE,
281 "corner_radius": 0.2,
282 "stroke_width": 1,
283 "fill_opacity": 1,
284 } # and the style's background, unless a fill_color is given
285 """The background's keywords unless `background_config` changes them; its fill is
286 the style's background color unless a `fill_color` is given."""
287 default_paragraph_config: ClassVar[CodeText] = {
288 "font": "Monospace",
289 "font_size": 24,
290 "line_spacing": 0.5,
291 "disable_ligatures": True,
292 }
293 """The text's keywords unless `paragraph_config` changes them."""
295 def __init__(
296 self,
297 code_file: StrPath | None = None,
298 code_string: str | None = None,
299 language: str | None = None,
300 formatter_style: CodeStyle = "vim",
301 tab_width: int = 4,
302 add_line_numbers: bool = True,
303 line_numbers_from: int = 1,
304 background: Literal["rectangle", "window"] = "rectangle",
305 background_config: FrameOptions | None = None,
306 paragraph_config: CodeText | None = None,
307 ) -> None:
308 super().__init__()
309 if code_file is not None:
310 code_string = Path(code_file).read_text(encoding="utf-8")
311 language = language or Path(code_file).suffix.removeprefix(".") or None
312 elif code_string is None:
313 raise ValueError("Either a code file or a code string must be specified.")
314 style = _STYLES[formatter_style]
315 text = self.default_paragraph_config | (paragraph_config or {})
316 # tabs expanded, empty lines trimmed off
317 code = (
318 code_string.expandtabs(tab_width).replace("\r\n", "\n").replace("\r", "\n")
319 )
320 lines = code.strip("\n").split("\n")
321 if not any(line.strip() for line in lines):
322 lines = [""] * len(lines)
324 # CE closes the first and last lines with an ascender, a descender and the first line
325 # number, so that a listing's height depends on its lines alone, then takes them away
326 suffix = f" pA{line_numbers_from}"
327 closing = len(suffix) - 1 # its glyphs: all but the space
328 rows = _typeset(
329 lines, text, style.foreground, style=style, language=language, suffix=suffix
330 )
331 self.code_lines = VGroup(*rows).move_to(ORIGIN)
332 """The lines, a part: its i-th part is the i-th line, a group of its glyphs."""
334 if add_line_numbers:
335 numbers = range(line_numbers_from, line_numbers_from + len(lines))
336 self.line_numbers = VGroup(
337 *_typeset([str(n) for n in numbers], text, style.line_numbers)
338 ).move_to(ORIGIN)
339 """The line numbers, a part (if the lines are numbered): its i-th part is
340 the i-th line's number, lined up on the right."""
341 right = self.line_numbers.get_right()[0]
342 for row in self.line_numbers.submobjects:
343 row.shift(RIGHT * (right - row.get_right()[0]))
344 self.line_numbers.next_to(self.code_lines, LEFT)
345 first = VGroup(*rows[0].submobjects[-len(str(line_numbers_from)) :])
346 self.line_numbers.shift(
347 UP * (first.get_y() - self.line_numbers.submobjects[0].get_y())
348 )
349 self.add(self.line_numbers)
351 # what CE keeps of the closings: their height, on the left edge of their glyphs and of
352 # the space before each, which CE's Text puts on the glyph before it
353 boundary = sorted({0, len(rows) - 1})
354 glyphs = [glyph for row in rows for glyph in row.submobjects]
355 closings = [g for i in boundary for g in rows[i].submobjects[-closing:]]
356 spaces = []
357 for i in boundary:
358 before = sum(len(row.submobjects) for row in rows[: i + 1]) - closing
359 spaces.append(
360 glyphs[before - 1] if before else rows[i].submobjects[-closing]
361 )
362 edge = min(
363 [g.get_center()[0] for g in spaces] + [g.get_left()[0] for g in closings]
364 )
365 extent = Line(
366 [edge, min(g.get_bottom()[1] for g in closings), 0],
367 [edge, max(g.get_top()[1] for g in closings), 0],
368 )
369 for i in boundary:
370 rows[i].remove(*rows[i].submobjects[-closing:])
371 self.add(self.code_lines)
373 config = self.default_background_config | (background_config or {})
374 if config.get("fill_color") is None:
375 config["fill_color"] = style.background
376 listing = VGroup(*self.submobjects, extent)
377 if background == "rectangle":
378 self.background = SurroundingRectangle(listing, **config)
379 """The rectangle behind the listing, its first part; a window's buttons are
380 its submobjects."""
381 elif background == "window":
382 buttons = VGroup(
383 *(
384 Dot(radius=0.1, stroke_width=0, color=c)
385 for c in ["#ff5f56", "#ffbd2e", "#27c93f"]
386 )
387 ).arrange(RIGHT, buff=0.1)
388 buttons.next_to(listing, UP, buff=0.1).align_to(listing, LEFT).shift(
389 LEFT * 0.1
390 )
391 self.background = SurroundingRectangle(listing, buttons, **config)
392 buttons.shift(UP * 0.1 + LEFT * 0.1)
393 self.background.add(buttons)
394 else:
395 raise ValueError(f"Unknown background type: {background}")
396 self.add_to_back(self.background)