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

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.""" 

4 

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 

12 

13from typing_extensions import TypedDict 

14 

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 

24 

25__all__ = ["Code"] 

26 

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 

35 

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") 

40 

41type CodeStyle = Literal["vim"] 

42 

43 

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.""" 

48 

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 

54 

55 

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} 

105 

106 

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.""" 

110 

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).""" 

123 

124 

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 ) 

137 

138 

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] 

145 

146 

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 

222 

223 

224class Code(VMobject): 

225 r"""A listing of source code, highlighted: its lines, their numbers, and a rectangle 

226 or a window behind them. 

227 

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. 

234 

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`. 

256 

257 Examples: 

258 ```python 

259 import manimgx as m 

260 

261 

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 """ 

277 

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.""" 

294 

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) 

323 

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.""" 

333 

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) 

350 

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) 

372 

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)