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:: separate_headings 

24 

25 .. autoattribute:: fallback_width 

26 

27 .. autoattribute:: msg_decorations_unicode 

28 

29 .. automethod:: set_msg_decoration_unicode 

30 

31 .. automethod:: _set_msg_decoration_unicode_if_not_overridden 

32 

33 .. autoattribute:: msg_decorations_ascii 

34 

35 .. automethod:: set_msg_decoration_ascii 

36 

37 .. automethod:: _set_msg_decoration_ascii_if_not_overridden 

38 

39 .. autoattribute:: colors 

40 

41 .. automethod:: set_color 

42 

43 .. automethod:: _set_color_if_not_overridden 

44 

45 .. automethod:: get_color 

46 

47 .. automethod:: to_color 

48 

49 .. automethod:: check 

50 

51 

52Default theme 

53------------- 

54 

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

56 

57.. autofunction:: load 

58 

59.. autoclass:: BaseTheme 

60 

61.. autoclass:: DefaultTheme 

62 

63 

64.. _all-color-paths: 

65 

66Color paths 

67----------- 

68 

69.. _common-tags: 

70 

71.. color-path:: common tags 

72 

73 :class:`BaseTheme` sets up commonly used colors that you can use 

74 in formatted messages: 

75 

76 - ``code``: inline code, 

77 - ``note``: inline highlighting, 

78 - ``path``: file paths, 

79 - ``flag``: CLI flags, 

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

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

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

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

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

85 - ``normal``: normal foreground, 

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

87 - ``red``: foreground, 

88 - ``green``: foreground, 

89 - ``yellow``: foreground, 

90 - ``blue``: foreground, 

91 - ``magenta``: foreground, 

92 - ``cyan``: foreground, 

93 

94 .. note:: 

95 

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

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

98 

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

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

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

102 

103.. _main-colors: 

104 

105.. color-path:: main colors 

106 

107 :class:`DefaultTheme` defines *main colors*, which you can override by subclassing. 

108 

109 - ``heading_color``: for headings, 

110 - ``primary_color``: for main text, 

111 - ``accent_color``, ``accent_color_2``: for visually highlighted elements, 

112 - ``secondary_color``: for visually dimmed elements, 

113 - ``error_color``: for everything that indicates an error, 

114 - ``warning_color``: for everything that indicates a warning, 

115 - ``success_color``: for everything that indicates a success, 

116 - ``critical_color``: for critical or internal errors, 

117 - ``low_priority_color_a``: for auxiliary elements such as help widget, 

118 - ``low_priority_color_b``: for auxiliary elements such as help widget, 

119 even lower priority. 

120 

121.. _term-colors: 

122 

123.. color-path:: `term/{color}` 

124 

125 :class:`DefaultTheme` will export default colors for the attached terminal 

126 as :samp:`term/{color}`. This is useful when defining gradients for progress bars, 

127 as they require exact color values for interpolation. 

128 

129 ``color`` can be one ``background``, ``foreground``, ``black``, ``bright_black``, 

130 ``red``, ``bright_red``, ``green``, ``bright_green``, ``yellow``, ``bright_yellow``, 

131 ``blue``, ``bright_blue``, ``magenta``, ``bright_magenta``, 

132 ``cyan``, ``bright_cyan``, ``white``, or ``bright_white``. 

133 

134.. color-path:: `msg/decoration:{tag}` 

135 

136 Color for decorations in front of messages: 

137 

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

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

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

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

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

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

144 and headings in markdown, 

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

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

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

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

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

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

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

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

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

154 

155.. color-path:: `msg/text:{tag}` 

156 

157 Color for the text part of messages: 

158 

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

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

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

162 

163.. color-path:: `task/...:{status}` 

164 

165 Running and finished tasks: 

166 

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

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

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

170 portion of the progress bar, 

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

172 portion of the progress bar, 

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

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

175 portion of the progress bar, 

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

177 portion of the progress bar, 

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

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

180 - ``task/comment``: task comment. 

181 

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

183 

184.. color-path:: `hl/{token}:{syntax}` 

185 

186 Color for highlighted part of code: 

187 

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

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

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

191 - ``hl/lit/builtin``: built-in literals, i.e. ``None``, ``True``, ``False``, 

192 - ``hl/lit/num``: numeric literals, 

193 - ``hl/lit/num/bin``: binary numeric literals, 

194 - ``hl/lit/num/oct``: octal numeric literals, 

195 - ``hl/lit/num/dec``: decimal numeric literals, 

196 - ``hl/lit/num/hex``: hexadecimal numeric literals, 

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

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

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

200 - ``hl/str/prefix``: string prefix, i.e. ``f`` in ``f"str"``, 

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

202 - ``hl/type/builtin``: type names for builtin types, 

203 - ``hl/type/user``: type names for user-defined types, 

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

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

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

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

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

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

210 

211.. color-path:: `tb/heading` 

212 `tb/message` 

213 `tb/frame/{location}/...` 

214 

215 For highlighted tracebacks: 

216 

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

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

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

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

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

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

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

224 

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

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

227 

228.. color-path:: `log/{part}:{level}` 

229 

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

231 level is lowercase name of logging level. 

232 

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

234 

235 .. seealso:: 

236 

237 :class:`yuio.io.Formatter`. 

238 

239.. color-path:: input widget 

240 

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

242 

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

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

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

246 - ``menu/text/error:input``: highlights for error region reported by a parser, 

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

248 

249.. color-path:: grid widgets 

250 

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

252 similar widgets: 

253 

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

255 decoration before a grid item, 

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

257 decoration around comments for a grid item, 

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

259 text of a grid item, 

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

261 comment for a grid item, 

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

263 prefix before the main text of a grid item 

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

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

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

267 suffix after the main text of a grid item 

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

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

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

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

272 

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

274 

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

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

277 

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

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

280 

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

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

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

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

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

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

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

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

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

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

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

292 

293.. color-path:: full screen help menu 

294 

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

296 

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

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

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

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

301 

302.. color-path:: inline help menu 

303 

304 Colors for help items rendered under a widget: 

305 

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

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

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

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

310 

311 

312.. _all-decorations: 

313 

314Decorations 

315----------- 

316 

317.. decoration-path:: `info` 

318 

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

320 

321.. decoration-path:: `warning` 

322 

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

324 

325.. decoration-path:: `error` 

326 

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

328 

329.. decoration-path:: `success` 

330 

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

332 

333.. decoration-path:: `failure` 

334 

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

336 

337.. decoration-path:: `heading/{level}` 

338 

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

340 

341.. decoration-path:: `heading/section` 

342 

343 First-level headings in CLI help. 

344 

345.. decoration-path:: `question` 

346 

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

348 

349.. decoration-path:: `list` 

350 

351 Bullets in markdown. 

352 

353.. decoration-path:: `quote` 

354 

355 Quote decorations in markdown. 

356 

357.. decoration-path:: `code` 

358 

359 Code decorations in markdown. 

360 

361.. decoration-path:: `thematic_break` 

362 

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

364 

365.. decoration-path:: `overflow` 

366 

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

368 

369.. decoration-path:: `progress_bar/{position}` 

370 

371 Decorations for progress bars. 

372 

373 Available positions are: 

374 

375 :``start_symbol``: 

376 Start of the progress bar. 

377 :``done_symbol``: 

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

379 :``pending_symbol``: 

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

381 :``end_symbol``: 

382 End of the progress bar. 

383 :``transition_pattern``: 

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

385 parts of the progress bar. 

386 

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

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

389 must be one character wide. 

390 

391 .. raw:: html 

392 

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

394 <div class="highlight"> 

395 <pre class="ascii-graphics"> 

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

397 │└┬───┘│└┬───────┘│ 

398 │ │ │ │ end_symbol 

399 │ │ │ └ pending_symbol 

400 │ │ └ transition_pattern 

401 │ └ done_symbol 

402 └ start_symbol 

403 </pre> 

404 </div> 

405 </div> 

406 

407 **Example:** 

408 

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

410 

411 .. code-block:: python 

412 

413 class BlockProgressTheme(yuio.theme.DefaultTheme): 

414 msg_decorations = { 

415 "progress_bar/start_symbol": "|", 

416 "progress_bar/end_symbol": "|", 

417 "progress_bar/done_symbol": "█", 

418 "progress_bar/pending_symbol": " ", 

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

420 } 

421 

422.. decoration-path:: `spinner/pattern` 

423 

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

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

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

427 

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

429 

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

431 

432.. decoration-path:: `spinner/static_symbol` 

433 

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

435 

436.. decoration-path:: `hr/{weight}/{position}` 

437 

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

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

440 

441 Default theme defines three weights: 

442 

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

444 - ``1`` prints normal ruler, 

445 - ``2`` prints bold ruler. 

446 

447 Available positions are: 

448 

449 :``left_start``: 

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

451 :``left_middle``: 

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

453 :``left_end``: 

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

455 :``middle``: 

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

457 :``right_start``: 

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

459 :``right_middle``: 

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

461 :``right_end``: 

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

463 

464 .. raw:: html 

465 

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

467 <div class="highlight"> 

468 <pre class="ascii-graphics"> 

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

470 │└┬───┘│ │└┬───┘│ 

471 │ │ │ │ │ right_end 

472 │ │ │ │ └ right_middle 

473 │ │ │ └ right_start 

474 │ │ └ left_end 

475 │ └ left_middle 

476 └ left_start 

477 

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

479 │└┬──────────────────┘│ 

480 │ middle right_end 

481 └ left_start 

482 </pre> 

483 </div> 

484 </div> 

485 

486.. decoration-path:: input widget 

487 

488 Decorations for :class:`yuio.widget.Input`: 

489 

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

491 - ``menu/input/decoration_search``: decoration before a search input box. 

492 

493.. decoration-path:: choice and multiselect widget 

494 

495 Decorations for :class:`yuio.widget.Choice` and :class:`yuio.widget.Multiselect`: 

496 

497 - ``menu/choice/decoration/active_item``: current item, 

498 - ``menu/choice/decoration/selected_item``: selected item in multiselect widget, 

499 - ``menu/choice/decoration/deselected_item``: deselected item in multiselect widget. 

500 

501.. decoration-path:: inline help and help menu 

502 

503 Decorations for widget help: 

504 

505 - ``menu/help/decoration``: decoration at the bottom of the help menu, 

506 - :samp:`menu/help/key/{key}`: text for functional keys. 

507 

508 ``key`` can be one of ``ctrl``, ``shift``, ``enter``, ``escape``, ``insert``, 

509 ``delete``, ``backspace``, ``tab``, ``home``, ``end``, ``page_up``, 

510 ``page_down``, ``arrow_up``, ``arrow_down``, ``arrow_left``, ``arrow_right``, 

511 ``space``, ``f1``...\\ ``f12``. 

512 

513""" 

514 

515from __future__ import annotations 

516 

517import dataclasses 

518import functools 

519import os 

520import pathlib 

521import warnings 

522from dataclasses import dataclass 

523from enum import IntFlag 

524 

525import yuio.color 

526import yuio.term 

527 

528from typing import TYPE_CHECKING 

529 

530if TYPE_CHECKING: 

531 import typing_extensions as _t 

532else: 

533 from yuio import _typing as _t 

534 

535__all__ = [ 

536 "BaseTheme", 

537 "DefaultTheme", 

538 "RecursiveThemeWarning", 

539 "TableJunction", 

540 "Theme", 

541 "ThemeWarning", 

542 "load", 

543] 

544 

545K = _t.TypeVar("K") 

546V = _t.TypeVar("V") 

547 

548 

549class ThemeWarning(yuio.YuioWarning): 

550 pass 

551 

552 

553class RecursiveThemeWarning(ThemeWarning): 

554 pass 

555 

556 

557_COLOR_NAMES = [ 

558 "background", 

559 "foreground", 

560 "black", 

561 "bright_black", 

562 "red", 

563 "bright_red", 

564 "green", 

565 "bright_green", 

566 "yellow", 

567 "bright_yellow", 

568 "blue", 

569 "bright_blue", 

570 "magenta", 

571 "bright_magenta", 

572 "cyan", 

573 "bright_cyan", 

574 "white", 

575 "bright_white", 

576] 

577 

578 

579@_t.final 

580class _ImmutableDict(_t.Mapping[K, V], _t.Generic[K, V]): 

581 def __init__( 

582 self, data: dict[K, V], sources: dict[K, type[Theme] | None], attr: str 

583 ): 

584 self.__data = data 

585 self.__sources = sources 

586 self.__attr = attr 

587 

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

589 return self.__data.items() 

590 

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

592 return self.__data.keys() 

593 

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

595 return self.__data.values() 

596 

597 def __len__(self): 

598 return len(self.__data) 

599 

600 def __getitem__(self, key): 

601 return self.__data[key] 

602 

603 def __iter__(self): 

604 return iter(self.__data) 

605 

606 def __contains__(self, key): 

607 return key in self.__data 

608 

609 def __repr__(self): 

610 return repr(self.__data) 

611 

612 def __setitem__(self, key, item): 

613 raise TypeError(f"Theme.{self.__attr} is immutable") 

614 

615 def __delitem__(self, key): 

616 raise TypeError(f"Theme.{self.__attr} is immutable") 

617 

618 def copy(self) -> _t.Self: 

619 return self.__class__( 

620 self.__data.copy(), 

621 self.__sources.copy(), 

622 self.__attr, 

623 ) 

624 

625 def _set(self, key: K, value: V, source: type[Theme]): 

626 self.__data[key] = value 

627 self.__sources[key] = source 

628 

629 def _set_if_not_overridden(self, key: K, value: V, source: type[Theme] | None): 

630 if source is None: 

631 raise TypeError( 

632 f"Theme._set_{self.__attr}_if_not_overridden can't be called " 

633 "outside of __init__" 

634 ) 

635 prev_source = self.__sources.get(key) 

636 if prev_source is None or issubclass(source, prev_source): 

637 self._set(key, value, source) 

638 

639 

640@_t.final 

641class _ReadOnlyDescriptor: 

642 def __set_name__(self, owner: object, attr: str): 

643 self.__attr = attr 

644 self.__private_name = f"_Theme__{attr}" 

645 

646 def __get__(self, instance: object | None, owner: type[object] | None = None): 

647 if instance is None: # pragma: no cover 

648 return self 

649 elif (data := instance.__dict__.get(self.__private_name)) is not None: 

650 return data 

651 else: 

652 data = owner.__dict__[self.__private_name].copy() 

653 instance.__dict__[self.__private_name] = data 

654 return data 

655 

656 def __set__(self, instance: object, value: _t.Any): 

657 raise TypeError(f"Theme.{self.__attr} is immutable") 

658 

659 def __delete__(self, instance: object): 

660 raise TypeError(f"Theme.{self.__attr} is immutable") 

661 

662 

663class _ThemeMeta(type): 

664 # BEWARE OF MAGIC! 

665 # 

666 # 

667 # Descriptors 

668 # ----------- 

669 # 

670 # _ThemeMeta.__dict__["colors"] 

671 # this is a `_ReadOnlyDescriptor` that handles access to `Theme.colors`, 

672 # proxying it to `Theme.__dict__["_Theme__colors"]`. 

673 # 

674 # Accessing `Theme.colors` is equivalent to calling 

675 # `_ThemeMeta.__dict__["colors"].__get__(Theme)`, 

676 # which in turn will return `Theme.__dict__["_Theme__colors"]`. 

677 # 

678 # Value for `Theme.__dict__["_Theme__colors"]` is assigned by this metaclass. 

679 # 

680 # Theme.__dict__["colors"] 

681 # this is a `_ReadOnlyDescriptor` that handles access to `theme.colors`, 

682 # proxying it to `theme.__dict__["_Theme__colors"]`. 

683 # 

684 # Accessing `theme.colors` is equivalent to calling 

685 # `Theme.__dict__["colors"].__get__(theme)`, 

686 # which in turn will return `theme.__dict__["_Theme__colors"]`. 

687 # 

688 # If `theme.__dict__` does not contain `"_Theme__colors"`, then it will assign 

689 # `theme.__dict__["_Theme__colors"] = Theme.__dict__["_Theme__colors"].copy()`. 

690 # 

691 # theme.__dict__["colors"] 

692 # this attribute does not exist. Accessing `theme.colors` is handled 

693 # by its descriptor. 

694 # 

695 # 

696 # Data 

697 # ---- 

698 # 

699 # Theme.__dict__["_Theme__colors"] 

700 # this is the data returned when accessing `Theme.colors`. It contains 

701 # an `_ImmutableDict` with combination of all colors from all bases. 

702 # 

703 # Theme.__dict__["_Theme__colors__orig"] 

704 # this is original data assigned to `colors` variable in `Theme`'s namespace. 

705 # 

706 # For example: 

707 # 

708 # class MyTheme(Theme): 

709 # colors = {"foo": "#000000"} 

710 # 

711 # In this class: 

712 # 

713 # - `MyTheme.__dict__["_Theme__colors"]` will contain combination of 

714 # colors defined in `Theme` and in `MyTheme`. 

715 # - `MyTheme.__dict__["_Theme__colors__orig"]` will contain initial dict 

716 # `{"foo": "#000000"}`. 

717 # 

718 # theme.__dict__["_Theme__colors"] 

719 # this is lazily initialized copy of `Theme.__dict__["_Theme__colors"]`; 

720 # `Theme.set_color` will mutate this value. 

721 

722 _managed_attrs = ["msg_decorations_ascii", "msg_decorations_unicode", "colors"] 

723 for _attr in _managed_attrs: 

724 locals()[_attr] = _ReadOnlyDescriptor() 

725 del _attr # type: ignore 

726 

727 def __new__(mcs, name, bases, ns, **kwargs): 

728 # Pop any overrides from class' namespace and save them in `_Theme__attr__orig`. 

729 # Set up read-only descriptors for managed attributes. 

730 for attr in mcs._managed_attrs: 

731 ns[f"_Theme__{attr}__orig"] = ns.pop(attr, {}) 

732 ns[attr] = _ReadOnlyDescriptor() 

733 

734 # Create metaclass instance. 

735 cls = super().__new__(mcs, name, bases, ns, **kwargs) 

736 

737 # Set up class-level data for managed attributes. 

738 for attr in mcs._managed_attrs: 

739 setattr(cls, f"_Theme__{attr}", mcs._collect_data(cls, attr)) 

740 

741 # Patch `__init__` so that it handles `__expected_source`. 

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

743 

744 @functools.wraps(init) 

745 def _wrapped_init(self, *args, **kwargs): 

746 prev_expected_source = self._Theme__expected_source 

747 self._Theme__expected_source = cls 

748 try: 

749 return init(self, *args, **kwargs) 

750 finally: 

751 self._Theme__expected_source = prev_expected_source 

752 

753 setattr(cls, "__init__", _wrapped_init) 

754 

755 return cls 

756 

757 def _collect_data(cls, attr): 

758 attr_orig = f"_Theme__{attr}__orig" 

759 data = {} 

760 sources = {} 

761 for base in reversed(cls.__mro__): 

762 if base_data := base.__dict__.get(attr_orig): 

763 data.update(base_data) 

764 sources.update(dict.fromkeys(base_data, base)) 

765 return _ImmutableDict(data, sources, attr) 

766 

767 

768class Theme(metaclass=_ThemeMeta): 

769 """ 

770 Base class for Yuio themes. 

771 

772 .. warning:: 

773 

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

775 Otherwise there's a risc of race conditions. 

776 

777 """ 

778 

779 msg_decorations_unicode: _t.Mapping[str, str] = {} 

780 """ 

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

782 list items, etc. 

783 

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

785 way to modify it is by using :meth:`~Theme.set_msg_decoration_ascii` 

786 or :meth:`~Theme._set_msg_decoration_ascii_if_not_overridden`. 

787 

788 """ 

789 

790 msg_decorations_ascii: _t.Mapping[str, str] = {} 

791 """ 

792 Like :attr:`~Theme.msg_decorations_unicode`, but suitable for non-unicode terminals. 

793 

794 """ 

795 

796 progress_bar_width: int = 15 

797 """ 

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

799 

800 """ 

801 

802 spinner_update_rate_ms: int = 200 

803 """ 

804 How often the spinner pattern changes. 

805 

806 """ 

807 

808 separate_headings: bool = True 

809 """ 

810 Whether to print newlines before and after :func:`yuio.io.heading`. 

811 

812 """ 

813 

814 fallback_width: int = 80 

815 """ 

816 Preferred width that will be used if printing to a stream that's redirected 

817 to a file. 

818 

819 """ 

820 

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

822 """ 

823 Mapping of color paths to actual colors. 

824 

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

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

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

828 two parts separated by a colon. 

829 

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

831 

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

833 of an object that we're coloring. 

834 

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

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

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

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

839 

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

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

842 the final color will be bold green. 

843 

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

845 or with another path. 

846 

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

848 with that particular color. 

849 

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

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

852 

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

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

855 

856 For example: 

857 

858 .. code-block:: python 

859 

860 colors = { 

861 "heading_color": "bold", 

862 "error_color": "red", 

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

864 } 

865 

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

867 

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

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

870 in order of method resolution. 

871 

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

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

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

875 

876 """ 

877 

878 __expected_source: type[Theme] | None = None 

879 """ 

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

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

882 

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

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

885 

886 This is possible because ``_ThemeMeta`` wraps any implementation 

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

888 

889 """ 

890 

891 def __init__(self): 

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

893 

894 def _set_msg_decoration_unicode_if_not_overridden( 

895 self, 

896 name: str, 

897 msg_decoration: str, 

898 /, 

899 ): 

900 """ 

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

902 in a subclass. 

903 

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

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

906 if it was not overridden by any child class. 

907 

908 """ 

909 

910 proxy = _t.cast(_ImmutableDict[str, str], self.msg_decorations_unicode) 

911 proxy._set_if_not_overridden( 

912 name, 

913 msg_decoration, 

914 self.__expected_source, 

915 ) 

916 

917 def set_msg_decoration_unicode( 

918 self, 

919 name: str, 

920 msg_decoration: str, 

921 /, 

922 ): 

923 """ 

924 Set Unicode message decoration by name. 

925 

926 """ 

927 

928 proxy = _t.cast(_ImmutableDict[str, str], self.msg_decorations_unicode) 

929 proxy._set( 

930 name, 

931 msg_decoration, 

932 self.__expected_source or type(self), 

933 ) 

934 

935 def _set_msg_decoration_ascii_if_not_overridden( 

936 self, 

937 name: str, 

938 msg_decoration: str, 

939 /, 

940 ): 

941 """ 

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

943 in a subclass. 

944 

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

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

947 if it was not overridden by any child class. 

948 

949 """ 

950 

951 proxy = _t.cast(_ImmutableDict[str, str], self.msg_decorations_ascii) 

952 proxy._set_if_not_overridden( 

953 name, 

954 msg_decoration, 

955 self.__expected_source, 

956 ) 

957 

958 def set_msg_decoration_ascii( 

959 self, 

960 name: str, 

961 msg_decoration: str, 

962 /, 

963 ): 

964 """ 

965 Set ASCII message decoration by name. 

966 

967 """ 

968 

969 proxy = _t.cast(_ImmutableDict[str, str], self.msg_decorations_ascii) 

970 proxy._set( 

971 name, 

972 msg_decoration, 

973 self.__expected_source or type(self), 

974 ) 

975 

976 def get_msg_decoration(self, key: str, /, *, is_unicode: bool) -> str: 

977 """ 

978 Get message decoration by name. 

979 

980 """ 

981 

982 msg_decorations = ( 

983 self.msg_decorations_unicode if is_unicode else self.msg_decorations_ascii 

984 ) 

985 return msg_decorations.get(key, "") 

986 

987 def _set_color_if_not_overridden( 

988 self, 

989 path: str, 

990 color: str | yuio.color.Color, 

991 /, 

992 ): 

993 """ 

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

995 

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

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

998 by any child class. 

999 

1000 """ 

1001 

1002 proxy = _t.cast(_ImmutableDict[str, str | yuio.color.Color], self.colors) 

1003 proxy._set_if_not_overridden( 

1004 path, 

1005 color, 

1006 self.__expected_source, 

1007 ) 

1008 self.__color_cache.clear() 

1009 self.__dict__.pop("_Theme__color_tree", None) # type: ignore 

1010 

1011 def set_color( 

1012 self, 

1013 path: str, 

1014 color: str | yuio.color.Color, 

1015 /, 

1016 ): 

1017 """ 

1018 Set color by path. 

1019 

1020 """ 

1021 

1022 proxy = _t.cast(_ImmutableDict[str, str | yuio.color.Color], self.colors) 

1023 proxy._set( 

1024 path, 

1025 color, 

1026 self.__expected_source or type(self), 

1027 ) 

1028 self.__color_cache.clear() 

1029 self.__dict__.pop("_Theme__color_tree", None) # type: ignore 

1030 

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

1032 class __ColorTree: 

1033 """ 

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

1035 

1036 """ 

1037 

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

1039 """ 

1040 Colors in this node. 

1041 

1042 """ 

1043 

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

1045 """ 

1046 Location part of the tree. 

1047 

1048 """ 

1049 

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

1051 """ 

1052 Context part of the tree. 

1053 

1054 """ 

1055 

1056 @functools.cached_property 

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

1058 root = self.__ColorTree() 

1059 

1060 for path, colors in self.colors.items(): 

1061 loc, ctx = self.__parse_path(path) 

1062 

1063 node = root 

1064 

1065 for part in loc: 

1066 if part not in node.loc: 

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

1068 node = node.loc[part] 

1069 

1070 for part in ctx: 

1071 if part not in node.ctx: 

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

1073 node = node.ctx[part] 

1074 

1075 node.colors = colors 

1076 

1077 return root 

1078 

1079 @staticmethod 

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

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

1082 if len(path_parts) == 1: 

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

1084 else: 

1085 loc, ctx = path_parts 

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

1087 

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

1089 """ 

1090 Lookup a color by path. 

1091 

1092 """ 

1093 

1094 color = yuio.color.Color.NONE 

1095 for path in paths.split(): 

1096 color |= self.__get_color(path) 

1097 return color 

1098 

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

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

1101 path, yuio.MISSING 

1102 ) 

1103 if res is None: 

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

1105 return yuio.color.Color.NONE 

1106 elif res is not yuio.MISSING: 

1107 return res 

1108 

1109 self.__color_cache[path] = None 

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