Coverage for yuio / theme.py: 98%

1# Yuio project, MIT license. 

2# 

3# https://github.com/taminomara/yuio/ 

4# 

5# You're free to copy this file to your project and edit it for your needs, 

6# just keep this copyright line please :3 

7 

8""" 

9Controlling visual aspects of Yuio with themes. 

10 

11Theme base class 

12---------------- 

13 

14The overall look and feel of a Yuio application is declared 

15in a :class:`Theme` object: 

16 

17.. autoclass:: Theme 

18 

19 .. autoattribute:: progress_bar_width 

20 

21 .. autoattribute:: spinner_update_rate_ms 

22 

23 .. autoattribute:: msg_decorations 

24 

25 .. automethod:: set_msg_decoration 

26 

27 .. automethod:: _set_msg_decoration_if_not_overridden 

28 

29 .. autoattribute:: colors 

30 

31 .. automethod:: set_color 

32 

33 .. automethod:: _set_color_if_not_overridden 

34 

35 .. automethod:: get_color 

36 

37 .. automethod:: to_color 

38 

39 .. automethod:: check 

40 

41 

42Default theme 

43------------- 

44 

45Use the following loader to create an instance of the default theme: 

46 

47.. autofunction:: load 

48 

49.. autoclass:: DefaultTheme 

50 

51 

52.. _all-color-paths: 

53 

54Color paths 

55----------- 

56 

57common tags 

58 :class:`DefaultTheme` sets up commonly used colors that you can use 

59 in formatted messages: 

60 

61 - ``code``: inline code, 

62 - ``note``: inline highlighting, 

63 - ``path``: file paths, 

64 - ``flag``: CLI flags, 

65 - ``bold``, ``b``: font style, 

66 - ``dim``, ``d``: font style, 

67 - ``italic``, ``i``: font style, 

68 - ``underline``, ``u``: font style, 

69 - ``inverse``: swap foreground and background colors, 

70 - ``normal``: normal foreground, 

71 - ``normal_dim``: muted foreground (see :attr:`~yuio.color.Color.FORE_NORMAL_DIM`), 

72 - ``red``: foreground, 

73 - ``green``: foreground, 

74 - ``yellow``: foreground, 

75 - ``blue``: foreground, 

76 - ``magenta``: foreground, 

77 - ``cyan``: foreground, 

78 

79 .. note:: 

80 

81 We don't define ``black`` and ``white`` because they can be invisible 

82 with some terminal themes. Prefer ``normal_dim`` when you need a muted color. 

83 

84 We also don't define tags for backgrounds because there's no way to tell 

85 which foreground/background combination will be readable and which will not. 

86 Prefer ``inverse`` when you need to add a background. 

87 

88:samp:`msg/decoration:{tag}` 

89 Color for decorations in front of messages: 

90 

91 - ``msg/decoration:info``: messages from :mod:`yuio.io.info`, 

92 - ``msg/decoration:warning``: messages from :mod:`yuio.io.warning`, 

93 - ``msg/decoration:error``: messages from :mod:`yuio.io.error`, 

94 - ``msg/decoration:success``: messages from :mod:`yuio.io.success`, 

95 - ``msg/decoration:failure``: messages from :mod:`yuio.io.failure`, 

96 - :samp:`msg/decoration:heading/{level}`: messages from :mod:`yuio.io.heading` 

97 and headings in markdown, 

98 - ``msg/decoration:heading/section``: first-level headings in CLI help, 

99 - ``msg/decoration:question``: messages from :func:`yuio.io.ask`, 

100 - ``msg/decoration:list``: bullets in markdown, 

101 - ``msg/decoration:quote``: quote decorations in markdown, 

102 - ``msg/decoration:code``: code decorations in markdown, 

103 - ``msg/decoration:thematic_break``: thematic breaks 

104 (i.e. horizontal rulers) in markdown, 

105 - :samp:`msg/decoration:hr/{weight}`: horizontal rulers (see :func:`yuio.io.hr` 

106 and :func:`yuio.string.Hr`). 

107 

108:samp:`msg/text:{tag}` 

109 Color for the text part of messages: 

110 

111 - ``msg/text:info`` and all other tags from ``msg/decoration``, 

112 - ``msg/text:paragraph``: plain text in markdown, 

113 - :samp:`msg/text:code/{syntax}`: plain text in highlighted code blocks. 

114 

115:samp:`task/...:{status}` 

116 Running and finished tasks: 

117 

118 - :samp:`task/decoration`: decoration before the task, 

119 - ``task/progressbar/done``: filled portion of the progress bar, 

120 - ``task/progressbar/done/start``: gradient start for the filled 

121 portion of the progress bar, 

122 - ``task/progressbar/done/end``: gradient end for the filled 

123 portion of the progress bar, 

124 - ``task/progressbar/pending``: unfilled portion of the progress bar, 

125 - ``task/progressbar/pending/start``: gradient start for the unfilled 

126 portion of the progress bar, 

127 - ``task/progressbar/pending/end``: gradient end for the unfilled 

128 portion of the progress bar, 

129 - ``task/heading``: task title, 

130 - ``task/progress``: number that indicates task progress, 

131 - ``task/comment``: task comment. 

132 

133 ``status`` can be ``running``, ``done``, or ``error``. 

134 

135:samp:`hl/{part}:{syntax}` 

136 Color for highlighted part of code: 

137 

138 - ``hl/comment``: code comments, 

139 - ``hl/kwd``: keyword, 

140 - ``hl/lit``: non-string literals, 

141 - ``hl/punct``: punctuation, 

142 - ``hl/str``: string literals, 

143 - ``hl/str/esc``: escape sequences in strings, 

144 - ``hl/type``: type names, 

145 - ``hl/meta``: diff meta info for diff highlighting, 

146 - ``hl/added``: added lines in diff highlighting, 

147 - ``hl/removed``: removed lines in diff highlighting, 

148 - ``hl/prog``: program name in CLI usage and shell highlighting, 

149 - ``hl/flag``: CLI flags, 

150 - ``hl/metavar``: meta variables in CLI usage. 

151 

152``tb/heading``, ``tb/message``, :samp:`tb/frame/{location}/...` 

153 For highlighted tracebacks: 

154 

155 - ``tb/heading``: traceback heading, 

156 - ``tb/message``: error message, 

157 - :samp:`tb/frame/{location}/file/module`: module name, 

158 - :samp:`tb/frame/{location}/file/line`: line number, 

159 - :samp:`tb/frame/{location}/file/path`: file path, 

160 - :samp:`tb/frame/{location}/code`: code sample at the error line, 

161 - :samp:`tb/frame/{location}/highlight`: highlighting under the code sample. 

162 

163 ``location`` is either ``lib`` or ``usr`` depending on whether the code 

164 is located in site-packages or in user code. 

165 

166:samp:`log/{part}:{level}` 

167 Colors for log records. ``part`` is name of a `log record attribute`__, 

168 level is lowercase name of logging level. 

169 

170 __ https://docs.python.org/3/library/logging.html#logrecord-attributes 

171 

172 .. seealso:: 

173 

174 :class:`yuio.io.Formatter`. 

175 

176input widget 

177 Colors for :class:`yuio.widget.Input`: 

178 

179 - ``menu/decoration:input``: decoration before an input box, 

180 - ``menu/text:input``: entered text in an input box, 

181 - ``menu/text/esc:input``: highlights for invisible characters in an input box, 

182 - ``menu/text/placeholder:input``: placeholder text in an input box, 

183 

184grid widgets 

185 Colors for :class:`yuio.widget.Grid`, :class:`yuio.widget.Choice`, and other 

186 similar widgets: 

187 

188 - :samp:`menu/decoration:choice/{status}/{color_tag}`: 

189 decoration before a grid item, 

190 - :samp:`menu/decoration/comment:choice/{status}/{color_tag}`: 

191 decoration around comments for a grid item, 

192 - :samp:`menu/text:choice/{status}/{color_tag}`: 

193 text of a grid item, 

194 - :samp:`menu/text/comment:choice/{status}/{color_tag}`: 

195 comment for a grid item, 

196 - :samp:`menu/text/prefix:choice/{status}/{color_tag}`: 

197 prefix before the main text of a grid item 

198 (see :attr:`yuio.widget.Option.display_text_prefix` and 

199 :attr:`yuio.complete.Completion.dprefix`), 

200 - :samp:`menu/text/suffix:choice/{status}/{color_tag}`: 

201 suffix after the main text of a grid item 

202 (see :attr:`yuio.widget.Option.display_text_suffix` and 

203 :attr:`yuio.complete.Completion.dsuffix`), 

204 - ``menu/text:choice/status_line``: status line (i.e. "Page x of y"). 

205 - ``menu/text:choice/status_line/number``: page numbers in a status line. 

206 

207 ``status`` is either ``normal`` or ``active``: 

208 

209 - ``normal`` for regular grid items, 

210 - ``active`` for the currently selected item. 

211 

212 ``color_tag`` is whatever tag specified by :attr:`yuio.widget.Option.color_tag` 

213 and :attr:`yuio.complete.Completion.group_color_tag`. Currently supported tags: 

214 

215 - ``none``: color tag is not given, 

216 - ``selected``: items selected in :class:`yuio.widget.Multiselect`, 

217 - ``dir``: directory (in file completion), 

218 - ``exec``: executable file (in file completion), 

219 - ``symlink``: symbolic link (in file completion), 

220 - ``socket``: socket (in file completion), 

221 - ``pipe``: FIFO pipe (in file completion), 

222 - ``block_device``: block device (in file completion), 

223 - ``char_device``: character device (in file completion), 

224 - ``original``: original completion item before spelling correction, 

225 - ``corrected``: completion item that was found after spelling correction. 

226 

227full screen help menu 

228 Colors for help menu that appears when pressing :kbd:`F1`: 

229 

230 - ``menu/text/heading:help_menu``: section heading, 

231 - ``menu/text/help_key:help_menu``: key names, 

232 - ``menu/text/help_sep:help_menu``: separators between key names, 

233 - ``menu/decoration:help_menu``: decorations. 

234 

235inline help menu 

236 Colors for help items rendered under a widget: 

237 

238 - ``menu/text/help_info:help``: help items that aren't associated with any key, 

239 - ``menu/text/help_msg:help``: regular help items, 

240 - ``menu/text/help_key:help``: keybinding names, 

241 - ``menu/text/help_sep:help``: separator between items. 

242 

243 

244.. _all-decorations: 

245 

246Decorations 

247----------- 

248 

249``info`` 

250 Messages from :mod:`yuio.io.info`. 

251 

252``warning`` 

253 Messages from :mod:`yuio.io.warning`. 

254 

255``error`` 

256 Messages from :mod:`yuio.io.error`. 

257 

258``success`` 

259 Messages from :mod:`yuio.io.success`. 

260 

261``failure`` 

262 Messages from :mod:`yuio.io.failure`. 

263 

264:samp:`heading/{level}` 

265 Messages from :mod:`yuio.io.heading` and headings in markdown. 

266 

267``heading/section`` 

268 First-level headings in CLI help. 

269 

270``question`` 

271 Messages from :func:`yuio.io.ask`. 

272 

273``list`` 

274 Bullets in markdown. 

275 

276``quote`` 

277 Quote decorations in markdown. 

278 

279``code`` 

280 Code decorations in markdown. 

281 

282``thematic_break`` 

283 Thematic breaks (i.e. horizontal rulers) in markdown. 

284 

285``overflow`` 

286 Ellipsis symbol for lines that don't fit terminal width. Must be one character wide. 

287 

288:samp:`progress_bar/{position}` 

289 Decorations for progress bars. 

290 

291 Available positions are: 

292 

293 :``start_symbol``: 

294 Start of the progress bar. 

295 :``done_symbol``: 

296 Tiles finished portion of the progress bar, must be one character wide. 

297 :``pending_symbol``: 

298 Tiles unfinished portion of the progress bar, must be one character wide. 

299 :``end_symbol``: 

300 End of the progress bar. 

301 :``transition_pattern``: 

302 If this decoration is empty, there's no symbol between finished and unfinished 

303 parts of the progress bar. 

304 

305 Otherwise, this decoration defines a left-to-right gradient of transition 

306 characters, ordered from most filled to least filled. Each character 

307 must be one character wide. 

308 

309 .. raw:: html 

310 

311 <div class="highlight-text notranslate"> 

312 <div class="highlight"> 

313 <pre class="ascii-graphics"> 

314 <span class="k">[------> ]</span> 

315 │└┬───┘│└┬───────┘│ 

316 │ │ │ │ end_symbol 

317 │ │ │ └ pending_symbol 

318 │ │ └ transition_pattern 

319 │ └ done_symbol 

320 └ start_symbol 

321 </pre> 

322 </div> 

323 </div> 

324 

325 **Example:** 

326 

327 To get the classic blocky look, you can do the following: 

328 

329 .. code-block:: python 

330 

331 class BlockProgressTheme(yuio.theme.DefaultTheme): 

332 msg_decorations = { 

333 "progress_bar/start_symbol": "|", 

334 "progress_bar/end_symbol": "|", 

335 "progress_bar/done_symbol": "█", 

336 "progress_bar/pending_symbol": " ", 

337 "progress_bar/transition_pattern": "█▉▊▋▌▍▎▏ ", 

338 } 

339 

340``spinner/pattern`` 

341 Defines a sequence of symbols that will be used to show spinners for tasks 

342 without known progress. Next element of the sequence will be shown 

343 every :attr:`~Theme.spinner_update_rate_ms`. 

344 

345 You can find some pre-made patterns in py-spinners__ package. 

346 

347 __ https://github.com/ManrajGrover/py-spinners?tab=readme-ov-file 

348 

349``spinner/static_symbol`` 

350 Static spinner symbol, for sub-tasks that've finished running but'. 

351 

352:samp:`hr/{weight}/{position}` 

353 Decorations for horizontal rulers (see :func:`yuio.io.hr` 

354 and :func:`yuio.string.Hr`). 

355 

356 Default theme defines three weights: 

357 

358 - ``0`` prints no ruler (but still prints centered text), 

359 - ``1`` prints normal ruler, 

360 - ``2`` prints bold ruler. 

361 

362 Available positions are: 

363 

364 :``left_start``: 

365 Start of the ruler to the left of the message. 

366 :``left_middle``: 

367 Filler of the ruler to the left of the message. 

368 :``left_end``: 

369 End of the ruler to the left of the message. 

370 :``middle``: 

371 Filler of the ruler that's used if ``msg`` is empty. 

372 :``right_start``: 

373 Start of the ruler to the right of the message. 

374 :``right_middle``: 

375 Filler of the ruler to the right of the message. 

376 :``right_end``: 

377 End of the ruler to the right of the message. 

378 

379 .. raw:: html 

380 

381 <div class="highlight-text notranslate"> 

382 <div class="highlight"> 

383 <pre class="ascii-graphics"> 

384 <span class="k"><------>message<------></span> 

385 │└┬───┘│ │└┬───┘│ 

386 │ │ │ │ │ right_end 

387 │ │ │ │ └ right_middle 

388 │ │ │ └ right_start 

389 │ │ └ left_end 

390 │ └ left_middle 

391 └ left_start 

392 

393 <span class="k"><---------------------></span> 

394 │└┬──────────────────┘│ 

395 │ middle right_end 

396 └ left_start 

397 </pre> 

398 </div> 

399 </div> 

400 

401""" 

402 

403from __future__ import annotations 

404 

405import dataclasses 

406import functools 

407import os 

408import pathlib 

409import warnings 

410from dataclasses import dataclass 

411from enum import IntFlag 

412 

413import yuio.color 

414import yuio.term 

415from yuio import _typing as _t 

416 

417__all__ = [ 

418 "DefaultTheme", 

419 "RecursiveThemeWarning", 

420 "TableJunction", 

421 "Theme", 

422 "ThemeWarning", 

423 "load", 

424] 

425 

426K = _t.TypeVar("K") 

427V = _t.TypeVar("V") 

428 

429 

430class ThemeWarning(yuio.YuioWarning): 

431 pass 

432 

433 

434class RecursiveThemeWarning(ThemeWarning): 

435 pass 

436 

437 

438class _ImmutableDictProxy(_t.Mapping[K, V], _t.Generic[K, V]): # pragma: no cover 

439 def __init__(self, data: dict[K, V], /, *, attr: str): 

440 self.__data = data 

441 self.__attr = attr 

442 

443 def items(self) -> _t.ItemsView[K, V]: 

444 return self.__data.items() 

445 

446 def keys(self) -> _t.KeysView[K]: 

447 return self.__data.keys() 

448 

449 def values(self) -> _t.ValuesView[V]: 

450 return self.__data.values() 

451 

452 def __len__(self): 

453 return len(self.__data) 

454 

455 def __getitem__(self, key): 

456 return self.__data[key] 

457 

458 def __iter__(self): 

459 return iter(self.__data) 

460 

461 def __contains__(self, key): 

462 return key in self.__data 

463 

464 def __repr__(self): 

465 return repr(self.__data) 

466 

467 def __setitem__(self, key, item): 

468 raise RuntimeError(f"Theme.{self.__attr} is immutable") 

469 

470 def __delitem__(self, key): 

471 raise RuntimeError(f"Theme.{self.__attr} is immutable") 

472 

473 

474class Theme: 

475 """ 

476 Base class for Yuio themes. 

477 

478 .. warning:: 

479 

480 Do not change theme contents after it was passed to :func:`yuio.io.setup`. 

481 Otherwise there's a risc of race conditions. 

482 

483 """ 

484 

485 msg_decorations: _t.Mapping[str, str] = {} 

486 """ 

487 Decorative symbols for certain text elements, such as headings, 

488 list items, etc. 

489 

490 This mapping becomes immutable once a theme class is created. The only possible 

491 way to modify it is by using :meth:`~Theme.set_msg_decoration` 

492 or :meth:`~Theme._set_msg_decoration_if_not_overridden`. 

493 

494 """ 

495 

496 __msg_decorations: dict[str, str] 

497 """ 

498 An actual mutable version of :attr:`~Theme.msg_decorations` 

499 is kept here, because ``__init_subclass__`` will replace 

500 :attr:`~Theme.msg_decorations` with an immutable proxy. 

501 

502 """ 

503 

504 __msg_decoration_sources: dict[str, type | None] = {} 

505 """ 

506 Keeps track of where a message decoration was inherited from. This var is used 

507 to avoid ``__init__``-ing message decorations that were overridden in a subclass. 

508 

509 """ 

510 

511 table_drawing_symbols: _t.Mapping[int, str] = {} 

512 """ 

513 TODO! 

514 """ 

515 

516 __table_drawing_symbols: dict[int, str] = {} 

517 """ 

518 An actual mutable version of :attr:`~Theme.table_drawing_symbols` 

519 is kept here, because ``__init_subclass__`` will replace 

520 :attr:`~Theme.table_drawing_symbols` with an immutable proxy. 

521 

522 """ 

523 

524 __table_drawing_symbol_sources: dict[int, type | None] = {} 

525 """ 

526 Keeps track of where a table drawing symbol was inherited from. This var is used 

527 to avoid ``__init__``-ing table drawing symbols that were overridden in a subclass. 

528 

529 """ 

530 

531 progress_bar_width: int = 15 

532 """ 

533 Width of a progress bar for :class:`yuio.io.Task`. 

534 

535 """ 

536 

537 spinner_update_rate_ms: int = 200 

538 """ 

539 How often the spinner pattern changes. 

540 

541 """ 

542 

543 colors: _t.Mapping[str, str | yuio.color.Color] = {} 

544 """ 

545 Mapping of color paths to actual colors. 

546 

547 Themes use color paths to describe styles and colors for different 

548 parts of an application. Color paths are similar to file paths, 

549 they use snake case identifiers separated by slashes, and consist of 

550 two parts separated by a colon. 

551 

552 The first part represents an object, i.e. what we're coloring. 

553 

554 The second part represents a context, i.e. what is the state or location 

555 of an object that we're coloring. 

556 

557 For example, a color for the filled part of the task's progress bar 

558 has path ``"task/progressbar/done"``, a color for a text of an error 

559 log record has path ``"log/message:error"``, and a color for a string escape 

560 sequence in a highlighted python code has path ``"hl/str/esc:python"``. 

561 

562 A color at a certain path is propagated to all sub-paths. For example, 

563 if ``"task/progressbar"`` is bold, and ``"task/progressbar/done"`` is green, 

564 the final color will be bold green. 

565 

566 Each color path can be associated with an instance of :class:`~yuio.color.Color` 

567 or with another path. 

568 

569 If path is mapped to a :class:`~yuio.color.Color`, then the path is associated 

570 with that particular color. 

571 

572 If path is mapped to another path, then the path is associated with 

573 the color value for that other path (please don't create recursions here). 

574 

575 You can combine multiple paths within the same mapping by separating them with 

576 whitespaces. In this case colors for those paths are combined. 

577 

578 For example: 

579 

580 .. code-block:: python 

581 

582 colors = { 

583 "heading_color": "bold", 

584 "error_color": "red", 

585 "tb/heading": "heading_color error_color", 

586 } 

587 

588 Here, color of traceback's heading ``"tb/heading"`` will be bold and red. 

589 

590 When deriving from a theme, you can override this mapping. When looking up 

591 colors via :meth:`~Theme.get_color`, base classes will be tried for color, 

592 in order of method resolution. 

593 

594 This mapping becomes immutable once a theme class is created. The only possible 

595 way to modify it is by using :meth:`~Theme.set_color` 

596 or :meth:`~Theme._set_color_if_not_overridden`. 

597 

598 """ 

599 

600 __colors: dict[str, str | yuio.color.Color] 

601 """ 

602 An actual mutable version of :attr:`~Theme.colors` 

603 is kept here, because ``__init_subclass__`` will replace 

604 :attr:`~Theme.colors` with an immutable proxy. 

605 

606 """ 

607 

608 __color_sources: dict[str, type | None] = {} 

609 """ 

610 Keeps track of where a color was inherited from. This var is used 

611 to avoid ``__init__``-ing colors that were overridden in a subclass. 

612 

613 """ 

614 

615 __expected_source: type | None = None 

616 """ 

617 When running an ``__init__`` function, this variable will be set to the class 

618 that implemented it, regardless of type of ``self``. 

619 

620 That is, inside ``DefaultTheme.__init__``, ``__expected_source`` is set 

621 to ``DefaultTheme``, in ``MyTheme.__init__`` it is ``MyTheme``, etc. 

622 

623 This is possible because ``__init_subclass__`` wraps any implementation 

624 of ``__init__`` into a wrapper that sets this variable. 

625 

626 """ 

627 

628 def __init__(self): 

629 self.__color_cache: dict[str, yuio.color.Color | None] = {} 

630 

631 def __init_subclass__(cls, **kwargs): 

632 super().__init_subclass__(**kwargs) 

633 

634 colors = {} 

635 color_sources = {} 

636 for base in reversed(cls.__mro__): 

637 base_colors = getattr(base, "_Theme__colors", {}) 

638 colors.update(base_colors) 

639 base_color_sources = getattr(base, "_Theme__color_sources", {}) 

640 color_sources.update(base_color_sources) 

641 

642 colors.update(cls.colors) 

643 color_sources.update(dict.fromkeys(cls.colors.keys(), cls)) 

644 

645 cls.__colors = colors 

646 cls.__color_sources = color_sources 

647 cls.colors = _ImmutableDictProxy(cls.__colors, attr="colors") 

648 

649 msg_decorations = {} 

650 msg_decoration_sources = {} 

651 for base in reversed(cls.__mro__): 

652 base_msg_decorations = getattr(base, "_Theme__msg_decorations", {}) 

653 msg_decorations.update(base_msg_decorations) 

654 base_msg_decoration_sources = getattr( 

655 base, "_Theme__msg_decoration_sources", {} 

656 ) 

657 msg_decoration_sources.update(base_msg_decoration_sources) 

658 

659 msg_decorations.update(cls.msg_decorations) 

660 msg_decoration_sources.update(dict.fromkeys(cls.msg_decorations.keys(), cls)) 

661 

662 cls.__msg_decorations = msg_decorations 

663 cls.__msg_decoration_sources = msg_decoration_sources 

664 cls.msg_decorations = _ImmutableDictProxy( 

665 cls.__msg_decorations, attr="msg_decorations" 

666 ) 

667 

668 table_drawing_symbols = {} 

669 table_drawing_symbol_sources = {} 

670 for base in reversed(cls.__mro__): 

671 base_table_drawing_symbols = getattr( 

672 base, "_Theme__table_drawing_symbols", {} 

673 ) 

674 table_drawing_symbols.update(base_table_drawing_symbols) 

675 base_table_drawing_symbol_sources = getattr( 

676 base, "_Theme__table_drawing_symbol_sources", {} 

677 ) 

678 table_drawing_symbol_sources.update(base_table_drawing_symbol_sources) 

679 

680 table_drawing_symbols.update(cls.table_drawing_symbols) 

681 table_drawing_symbol_sources.update( 

682 dict.fromkeys(cls.table_drawing_symbols.keys(), cls) 

683 ) 

684 

685 cls.__table_drawing_symbols = table_drawing_symbols 

686 cls.__table_drawing_symbol_sources = table_drawing_symbol_sources 

687 cls.table_drawing_symbols = _ImmutableDictProxy( 

688 cls.__table_drawing_symbols, attr="table_drawing_symbols" 

689 ) 

690 

691 if init := cls.__dict__.get("__init__", None): 

692 

693 @functools.wraps(init) 

694 def _wrapped_init(_self, *args, **kwargs): 

695 prev_expected_source = _self._Theme__expected_source 

696 _self._Theme__expected_source = cls 

697 try: 

698 return init(_self, *args, **kwargs) 

699 finally: 

700 _self._Theme__expected_source = prev_expected_source 

701 

702 cls.__init__ = _wrapped_init # type: ignore 

703 

704 def _set_msg_decoration_if_not_overridden( 

705 self, 

706 name: str, 

707 msg_decoration: str, 

708 /, 

709 ): 

710 """ 

711 Set message decoration by name, but only if it wasn't overridden 

712 in a subclass. 

713 

714 This method should be called from ``__init__`` implementations 

715 to dynamically set message decorations. It will only set the decoration 

716 if it was not overridden by any child class. 

717 

718 """ 

719 

720 if self.__expected_source is None: 

721 raise RuntimeError( 

722 "_set_msg_decoration_if_not_overridden should only be called from __init__" 

723 ) 

724 source = self.__msg_decoration_sources.get(name, Theme) 

725 # The class that's `__init__` is currently running should be a parent 

726 # of the msg_decoration's source. This means that the msg_decoration was assigned by a parent. 

727 if source is not None and issubclass(self.__expected_source, source): 

728 self.set_msg_decoration(name, msg_decoration) 

729 

730 def set_msg_decoration( 

731 self, 

732 name: str, 

733 msg_decoration: str, 

734 /, 

735 ): 

736 """ 

737 Set message decoration by name. 

738 

739 """ 

740 

741 if "_Theme__msg_decorations" not in self.__dict__: 

742 self.__msg_decorations = self.__class__.__msg_decorations.copy() 

743 self.__msg_decoration_sources = ( 

744 self.__class__.__msg_decoration_sources.copy() 

745 ) 

746 self.msg_decorations = _ImmutableDictProxy( 

747 self.__msg_decorations, attr="msg_decorations" 

748 ) 

749 self.__msg_decorations[name] = msg_decoration 

750 self.__msg_decoration_sources[name] = self.__expected_source 

751 

752 def _set_table_drawing_symbol_if_not_overridden( 

753 self, 

754 code: int, 

755 table_drawing_symbol: str, 

756 /, 

757 ): 

758 """ 

759 Set table drawing symbol by code, but only if it wasn't overridden 

760 in a subclass. 

761 

762 This method should be called from ``__init__`` implementations 

763 to dynamically set table drawing symbols. It will only set the symbol 

764 if it was not overridden by any child class. 

765 

766 """ 

767 

768 if self.__expected_source is None: 

769 raise RuntimeError( 

770 "_set_table_drawing_symbol_if_not_overridden should only be called from __init__" 

771 ) 

772 source = self.__table_drawing_symbol_sources.get(code, Theme) 

773 # The class that's `__init__` is currently running should be a parent 

774 # of the table_drawing_symbol's source. This means that the table_drawing_symbol was assigned by a parent. 

775 if source is not None and issubclass(self.__expected_source, source): 

776 self.set_table_drawing_symbol(code, table_drawing_symbol) 

777 

778 def set_table_drawing_symbol( 

779 self, 

780 code: int, 

781 table_drawing_symbol: str, 

782 /, 

783 ): 

784 """ 

785 Set table drawing symbol by code. 

786 

787 """ 

788 

789 if "_Theme__table_drawing_symbols" not in self.__dict__: 

790 self.__table_drawing_symbols = self.__class__.__table_drawing_symbols.copy() 

791 self.__table_drawing_symbol_sources = ( 

792 self.__class__.__table_drawing_symbol_sources.copy() 

793 ) 

794 self.table_drawing_symbols = _ImmutableDictProxy( 

795 self.__table_drawing_symbols, attr="table_drawing_symbols" 

796 ) 

797 self.__table_drawing_symbols[code] = table_drawing_symbol 

798 self.__table_drawing_symbol_sources[code] = self.__expected_source 

799 

800 def _set_color_if_not_overridden( 

801 self, 

802 path: str, 

803 color: str | yuio.color.Color, 

804 /, 

805 ): 

806 """ 

807 Set color by path, but only if the color was not overridden in a subclass. 

808 

809 This method should be called from ``__init__`` implementations 

810 to dynamically set colors. It will only set the color if it was not overridden 

811 by any child class. 

812 

813 """ 

814 

815 if self.__expected_source is None: 

816 raise RuntimeError( 

817 "_set_color_if_not_overridden should only be called from __init__" 

818 ) 

819 source = self.__color_sources.get(path, Theme) 

820 # The class who's `__init__` is currently running should be a parent 

821 # of the color's source. This means that the color was assigned by a parent. 

822 if source is not None and issubclass(self.__expected_source, source): 

823 self.set_color(path, color) 

824 

825 def set_color( 

826 self, 

827 path: str, 

828 color: str | yuio.color.Color, 

829 /, 

830 ): 

831 """ 

832 Set color by path. 

833 

834 """ 

835 

836 if "_Theme__colors" not in self.__dict__: 

837 self.__colors = self.__class__.__colors.copy() 

838 self.__color_sources = self.__class__.__color_sources.copy() 

839 self.colors = _ImmutableDictProxy(self.__colors, attr="colors") 

840 self.__colors[path] = color 

841 self.__color_sources[path] = self.__expected_source 

842 self.__color_cache.clear() 

843 self.__dict__.pop("_Theme__color_tree", None) 

844 

845 @dataclass(kw_only=True, slots=True) 

846 class __ColorTree: 

847 """ 

848 Prefix-like tree that contains all of the theme's colors. 

849 

850 """ 

851 

852 colors: str | yuio.color.Color = yuio.color.Color.NONE 

853 """ 

854 Colors in this node. 

855 

856 """ 

857 

858 loc: dict[str, Theme.__ColorTree] = dataclasses.field(default_factory=dict) 

859 """ 

860 Location part of the tree. 

861 

862 """ 

863 

864 ctx: dict[str, Theme.__ColorTree] = dataclasses.field(default_factory=dict) 

865 """ 

866 Context part of the tree. 

867 

868 """ 

869 

870 @functools.cached_property 

871 def __color_tree(self) -> Theme.__ColorTree: 

872 root = self.__ColorTree() 

873 

874 for path, colors in self.__colors.items(): 

875 loc, ctx = self.__parse_path(path) 

876 

877 node = root 

878 

879 for part in loc: 

880 if part not in node.loc: 

881 node.loc[part] = self.__ColorTree() 

882 node = node.loc[part] 

883 

884 for part in ctx: 

885 if part not in node.ctx: 

886 node.ctx[part] = self.__ColorTree() 

887 node = node.ctx[part] 

888 

889 node.colors = colors 

890 

891 return root 

892 

893 @staticmethod 

894 def __parse_path(path: str, /) -> tuple[list[str], list[str]]: 

895 path_parts = path.split(":", maxsplit=1) 

896 if len(path_parts) == 1: 

897 loc, ctx = path_parts[0], "" 

898 else: 

899 loc, ctx = path_parts 

900 return loc.split("/") if loc else [], ctx.split("/") if ctx else [] 

901 

902 @_t.final 

903 def get_color(self, paths: str, /) -> yuio.color.Color: 

904 """ 

905 Lookup a color by path. 

906 

907 """ 

908 

909 color = yuio.color.Color.NONE 

910 for path in paths.split(): 

911 color |= self.__get_color(path) 

912 return color 

913 

914 def __get_color(self, path: str, /) -> yuio.color.Color: 

915 res: yuio.color.Color | None | yuio.Missing = self.__color_cache.get( 

916 path, yuio.MISSING 

917 ) 

918 if res is None: 

919 warnings.warn(f"recursive color path {path!r}", RecursiveThemeWarning) 

920 return yuio.color.Color.NONE 

921 elif res is not yuio.MISSING: 

922 return res 

923 

924 self.__color_cache[path] = None 

925 if path.startswith("#") and len(path) == 7: 

926 try: 

927 res = yuio.color.Color.fore_from_hex(path) 

928 except ValueError as e: 

929 warnings.warn(f"invalid color code {path!r}: {e}", ThemeWarning) 

930 res = yuio.color.Color.NONE 

931 elif path[:3].lower() == "bg#" and len(path) == 9: 

932 try: 

933 res = yuio.color.Color.back_from_hex(path[2:]) 

934 except ValueError as e: 

935 warnings.warn(f"invalid color code {path!r}: {e}", ThemeWarning) 

936 res = yuio.color.Color.NONE 

937 else: 

938 loc, ctx = self.__parse_path(path) 

939 res = self.__get_color_in_loc(self.__color_tree, loc, ctx) 

940 self.__color_cache[path] = res 

941 return res 

942 

943 def __get_color_in_loc( 

944 self, node: Theme.__ColorTree, loc: list[str], ctx: list[str] 

945 ): 

946 color = yuio.color.Color.NONE 

947 

948 for part in loc: 

949 if part not in node.loc: 

950 break 

951 color |= self.__get_color_in_ctx(node, ctx) 

952 node = node.loc[part] 

953 

954 return color | self.__get_color_in_ctx(node, ctx) 

955 

956 def __get_color_in_ctx(self, node: Theme.__ColorTree, ctx: list[str]): 

957 color = yuio.color.Color.NONE 

958 

959 for part in ctx: 

960 if part not in node.ctx: 

961 break 

962 color |= self.__get_color_in_node(node) 

963 node = node.ctx[part] 

964 

965 return color | self.__get_color_in_node(node) 

966 

967 def __get_color_in_node(self, node: Theme.__ColorTree) -> yuio.color.Color: 

968 color = yuio.color.Color.NONE 

969 

970 if isinstance(node.colors, str): 

971 color |= self.get_color(node.colors) 

972 else: 

973 color |= node.colors 

974 

975 return color 

976 

977 def to_color( 

978 self, color_or_path: yuio.color.Color | str | None, / 

979 ) -> yuio.color.Color: 

980 """ 

981 Convert color or color path to color. 

982 

983 """ 

984 

985 if color_or_path is None: 

986 return yuio.color.Color.NONE 

987 elif isinstance(color_or_path, yuio.color.Color): 

988 return color_or_path 

989 else: 

990 return self.get_color(color_or_path) 

991 

992 def check(self): 

993 """ 

994 Check theme for recursion. 

995 

996 This method is slow, and should be called from unit tests of your application. 

997 

998 """ 

999 

1000 if "" in self.colors: 

1001 warnings.warn("colors map contains an empty key", ThemeWarning) 

1002 

1003 for k, v in self.colors.items(): 

1004 if not v: 

1005 warnings.warn(f"color value for path {k!r} is empty", ThemeWarning) 

1006 

1007 err_path = None 

1008 with warnings.catch_warnings(): 

1009 warnings.simplefilter("error", category=RecursiveThemeWarning) 

1010 for k in self.colors: 

1011 try: 

1012 self.get_color(k) 

1013 except RecursiveThemeWarning: 

1014 err_path = k 

1015 if err_path is None: 

1016 return 

1017 

1018 self.__color_cache.clear() 

1019 recursive_path = [] 

1020 get_color_inner = self.__get_color 

1021 

1022 def get_color(path: str): 

1023 recursive_path.append(path) 

1024 return get_color_inner(path) 

1025 

1026 self.__get_color = get_color 

1027 

1028 try: 

1029 with warnings.catch_warnings(): 

1030 warnings.simplefilter("error", category=RecursiveThemeWarning) 

1031 self.get_color(err_path) 

1032 except RecursiveThemeWarning: 

1033 self.__get_color = get_color_inner 

1034 else: