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/{part}:{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/punct``: punctuation, 

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

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

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

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

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

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

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

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

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

201 

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

203 `tb/message` 

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

205 

206 For highlighted tracebacks: 

207 

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

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

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

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

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

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

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

215 

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

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

218 

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

220 

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

222 level is lowercase name of logging level. 

223 

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

225 

226 .. seealso:: 

227 

228 :class:`yuio.io.Formatter`. 

229 

230.. color-path:: input widget 

231 

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

233 

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

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

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

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

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

239 

240.. color-path:: grid widgets 

241 

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

243 similar widgets: 

244 

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

246 decoration before a grid item, 

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

248 decoration around comments for a grid item, 

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

250 text of a grid item, 

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

252 comment for a grid item, 

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

254 prefix before the main text of a grid item 

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

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

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

258 suffix after the main text of a grid item 

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

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

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

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

263 

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

265 

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

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

268 

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

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

271 

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

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

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

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

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

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

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

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

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

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

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

283 

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

285 

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

287 

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

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

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

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

292 

293.. color-path:: inline help menu 

294 

295 Colors for help items rendered under a widget: 

296 

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

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

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

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

301 

302 

303.. _all-decorations: 

304 

305Decorations 

306----------- 

307 

308.. decoration-path:: `info` 

309 

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

311 

312.. decoration-path:: `warning` 

313 

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

315 

316.. decoration-path:: `error` 

317 

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

319 

320.. decoration-path:: `success` 

321 

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

323 

324.. decoration-path:: `failure` 

325 

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

327 

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

329 

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

331 

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

333 

334 First-level headings in CLI help. 

335 

336.. decoration-path:: `question` 

337 

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

339 

340.. decoration-path:: `list` 

341 

342 Bullets in markdown. 

343 

344.. decoration-path:: `quote` 

345 

346 Quote decorations in markdown. 

347 

348.. decoration-path:: `code` 

349 

350 Code decorations in markdown. 

351 

352.. decoration-path:: `thematic_break` 

353 

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

355 

356.. decoration-path:: `overflow` 

357 

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

359 

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

361 

362 Decorations for progress bars. 

363 

364 Available positions are: 

365 

366 :``start_symbol``: 

367 Start of the progress bar. 

368 :``done_symbol``: 

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

370 :``pending_symbol``: 

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

372 :``end_symbol``: 

373 End of the progress bar. 

374 :``transition_pattern``: 

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

376 parts of the progress bar. 

377 

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

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

380 must be one character wide. 

381 

382 .. raw:: html 

383 

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

385 <div class="highlight"> 

386 <pre class="ascii-graphics"> 

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

388 │└┬───┘│└┬───────┘│ 

389 │ │ │ │ end_symbol 

390 │ │ │ └ pending_symbol 

391 │ │ └ transition_pattern 

392 │ └ done_symbol 

393 └ start_symbol 

394 </pre> 

395 </div> 

396 </div> 

397 

398 **Example:** 

399 

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

401 

402 .. code-block:: python 

403 

404 class BlockProgressTheme(yuio.theme.DefaultTheme): 

405 msg_decorations = { 

406 "progress_bar/start_symbol": "|", 

407 "progress_bar/end_symbol": "|", 

408 "progress_bar/done_symbol": "█", 

409 "progress_bar/pending_symbol": " ", 

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

411 } 

412 

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

414 

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

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

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

418 

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

420 

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

422 

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

424 

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

426 

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

428 

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

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

431 

432 Default theme defines three weights: 

433 

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

435 - ``1`` prints normal ruler, 

436 - ``2`` prints bold ruler. 

437 

438 Available positions are: 

439 

440 :``left_start``: 

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

442 :``left_middle``: 

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

444 :``left_end``: 

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

446 :``middle``: 

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

448 :``right_start``: 

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

450 :``right_middle``: 

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

452 :``right_end``: 

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

454 

455 .. raw:: html 

456 

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

458 <div class="highlight"> 

459 <pre class="ascii-graphics"> 

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

461 │└┬───┘│ │└┬───┘│ 

462 │ │ │ │ │ right_end 

463 │ │ │ │ └ right_middle 

464 │ │ │ └ right_start 

465 │ │ └ left_end 

466 │ └ left_middle 

467 └ left_start 

468 

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

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

471 │ middle right_end 

472 └ left_start 

473 </pre> 

474 </div> 

475 </div> 

476 

477.. decoration-path:: input widget 

478 

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

480 

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

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

483 

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

485 

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

487 

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

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

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

491 

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

493 

494 Decorations for widget help: 

495 

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

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

498 

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

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

501 ``page_down``, ``arrow_up``, ``arrow_down``, ``arrow_left``, ``arrow_right``, 

502 ``space``, ``f1``...\\ ``f12``. 

503 

504""" 

505 

506from __future__ import annotations 

507 

508import dataclasses 

509import functools 

510import os 

511import pathlib 

512import warnings 

513from dataclasses import dataclass 

514from enum import IntFlag 

515 

516import yuio.color 

517import yuio.term 

518 

519from typing import TYPE_CHECKING 

520 

521if TYPE_CHECKING: 

522 import typing_extensions as _t 

523else: 

524 from yuio import _typing as _t 

525 

526__all__ = [ 

527 "BaseTheme", 

528 "DefaultTheme", 

529 "RecursiveThemeWarning", 

530 "TableJunction", 

531 "Theme", 

532 "ThemeWarning", 

533 "load", 

534] 

535 

536K = _t.TypeVar("K") 

537V = _t.TypeVar("V") 

538 

539 

540class ThemeWarning(yuio.YuioWarning): 

541 pass 

542 

543 

544class RecursiveThemeWarning(ThemeWarning): 

545 pass 

546 

547 

548_COLOR_NAMES = [ 

549 "background", 

550 "foreground", 

551 "black", 

552 "bright_black", 

553 "red", 

554 "bright_red", 

555 "green", 

556 "bright_green", 

557 "yellow", 

558 "bright_yellow", 

559 "blue", 

560 "bright_blue", 

561 "magenta", 

562 "bright_magenta", 

563 "cyan", 

564 "bright_cyan", 

565 "white", 

566 "bright_white", 

567] 

568 

569 

570@_t.final 

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

572 def __init__( 

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

574 ): 

575 self.__data = data 

576 self.__sources = sources 

577 self.__attr = attr 

578 

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

580 return self.__data.items() 

581 

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

583 return self.__data.keys() 

584 

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

586 return self.__data.values() 

587 

588 def __len__(self): 

589 return len(self.__data) 

590 

591 def __getitem__(self, key): 

592 return self.__data[key] 

593 

594 def __iter__(self): 

595 return iter(self.__data) 

596 

597 def __contains__(self, key): 

598 return key in self.__data 

599 

600 def __repr__(self): 

601 return repr(self.__data) 

602 

603 def __setitem__(self, key, item): 

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

605 

606 def __delitem__(self, key): 

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

608 

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

610 return self.__class__( 

611 self.__data.copy(), 

612 self.__sources.copy(), 

613 self.__attr, 

614 ) 

615 

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

617 self.__data[key] = value 

618 self.__sources[key] = source 

619 

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

621 if source is None: 

622 raise TypeError( 

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

624 "outside of __init__" 

625 ) 

626 prev_source = self.__sources.get(key) 

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

628 self._set(key, value, source) 

629 

630 

631@_t.final 

632class _ReadOnlyDescriptor: 

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

634 self.__attr = attr 

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

636 

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

638 if instance is None: # pragma: no cover 

639 return self 

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

641 return data 

642 else: 

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

644 instance.__dict__[self.__private_name] = data 

645 return data 

646 

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

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

649 

650 def __delete__(self, instance: object): 

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

652 

653 

654class _ThemeMeta(type): 

655 # BEWARE OF MAGIC! 

656 # 

657 # 

658 # Descriptors 

659 # ----------- 

660 # 

661 # _ThemeMeta.__dict__["colors"] 

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

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

664 # 

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

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

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

668 # 

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

670 # 

671 # Theme.__dict__["colors"] 

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

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

674 # 

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

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

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

678 # 

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

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

681 # 

682 # theme.__dict__["colors"] 

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

684 # by its descriptor. 

685 # 

686 # 

687 # Data 

688 # ---- 

689 # 

690 # Theme.__dict__["_Theme__colors"] 

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

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

693 # 

694 # Theme.__dict__["_Theme__colors__orig"] 

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

696 # 

697 # For example: 

698 # 

699 # class MyTheme(Theme): 

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

701 # 

702 # In this class: 

703 # 

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

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

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

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

708 # 

709 # theme.__dict__["_Theme__colors"] 

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

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

712 

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

714 for _attr in _managed_attrs: 

715 locals()[_attr] = _ReadOnlyDescriptor() 

716 del _attr # type: ignore 

717 

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

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

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

721 for attr in mcs._managed_attrs: 

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

723 ns[attr] = _ReadOnlyDescriptor() 

724 

725 # Create metaclass instance. 

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

727 

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

729 for attr in mcs._managed_attrs: 

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

731 

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

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

734 

735 @functools.wraps(init) 

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

737 prev_expected_source = self._Theme__expected_source 

738 self._Theme__expected_source = cls 

739 try: 

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

741 finally: 

742 self._Theme__expected_source = prev_expected_source 

743 

744 setattr(cls, "__init__", _wrapped_init) 

745 

746 return cls 

747 

748 def _collect_data(cls, attr): 

749 attr_orig = f"_Theme__{attr}__orig" 

750 data = {} 

751 sources = {} 

752 for base in reversed(cls.__mro__): 

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

754 data.update(base_data) 

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

756 return _ImmutableDict(data, sources, attr) 

757 

758 

759class Theme(metaclass=_ThemeMeta): 

760 """ 

761 Base class for Yuio themes. 

762 

763 .. warning:: 

764 

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

766 Otherwise there's a risc of race conditions. 

767 

768 """ 

769 

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

771 """ 

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

773 list items, etc. 

774 

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

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

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

778 

779 """ 

780 

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

782 """ 

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

784 

785 """ 

786 

787 progress_bar_width: int = 15 

788 """ 

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

790 

791 """ 

792 

793 spinner_update_rate_ms: int = 200 

794 """ 

795 How often the spinner pattern changes. 

796 

797 """ 

798 

799 separate_headings: bool = True 

800 """ 

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

802 

803 """ 

804 

805 fallback_width: int = 80 

806 """ 

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

808 to a file. 

809 

810 """ 

811 

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

813 """ 

814 Mapping of color paths to actual colors. 

815 

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

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

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

819 two parts separated by a colon. 

820 

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

822 

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

824 of an object that we're coloring. 

825 

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

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

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

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

830 

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

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

833 the final color will be bold green. 

834 

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

836 or with another path. 

837 

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

839 with that particular color. 

840 

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

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

843 

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

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

846 

847 For example: 

848 

849 .. code-block:: python 

850 

851 colors = { 

852 "heading_color": "bold", 

853 "error_color": "red", 

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

855 } 

856 

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

858 

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

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

861 in order of method resolution. 

862 

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

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

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

866 

867 """ 

868 

869 __expected_source: type[Theme] | None = None 

870 """ 

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

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

873 

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

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

876 

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

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

879 

880 """ 

881 

882 def __init__(self): 

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

884 

885 def _set_msg_decoration_unicode_if_not_overridden( 

886 self, 

887 name: str, 

888 msg_decoration: str, 

889 /, 

890 ): 

891 """ 

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

893 in a subclass. 

894 

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

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

897 if it was not overridden by any child class. 

898 

899 """ 

900 

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

902 proxy._set_if_not_overridden( 

903 name, 

904 msg_decoration, 

905 self.__expected_source, 

906 ) 

907 

908 def set_msg_decoration_unicode( 

909 self, 

910 name: str, 

911 msg_decoration: str, 

912 /, 

913 ): 

914 """ 

915 Set Unicode message decoration by name. 

916 

917 """ 

918 

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

920 proxy._set( 

921 name, 

922 msg_decoration, 

923 self.__expected_source or type(self), 

924 ) 

925 

926 def _set_msg_decoration_ascii_if_not_overridden( 

927 self, 

928 name: str, 

929 msg_decoration: str, 

930 /, 

931 ): 

932 """ 

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

934 in a subclass. 

935 

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

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

938 if it was not overridden by any child class. 

939 

940 """ 

941 

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

943 proxy._set_if_not_overridden( 

944 name, 

945 msg_decoration, 

946 self.__expected_source, 

947 ) 

948 

949 def set_msg_decoration_ascii( 

950 self, 

951 name: str, 

952 msg_decoration: str, 

953 /, 

954 ): 

955 """ 

956 Set ASCII message decoration by name. 

957 

958 """ 

959 

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

961 proxy._set( 

962 name, 

963 msg_decoration, 

964 self.__expected_source or type(self), 

965 ) 

966 

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

968 """ 

969 Get message decoration by name. 

970 

971 """ 

972 

973 msg_decorations = ( 

974 self.msg_decorations_unicode if is_unicode else self.msg_decorations_ascii 

975 ) 

976 return msg_decorations.get(key, "") 

977 

978 def _set_color_if_not_overridden( 

979 self, 

980 path: str, 

981 color: str | yuio.color.Color, 

982 /, 

983 ): 

984 """ 

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

986 

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

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

989 by any child class. 

990 

991 """ 

992 

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

994 proxy._set_if_not_overridden( 

995 path, 

996 color, 

997 self.__expected_source, 

998 ) 

999 self.__color_cache.clear() 

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

1001 

1002 def set_color( 

1003 self, 

1004 path: str, 

1005 color: str | yuio.color.Color, 

1006 /, 

1007 ): 

1008 """ 

1009 Set color by path. 

1010 

1011 """ 

1012 

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

1014 proxy._set( 

1015 path, 

1016 color, 

1017 self.__expected_source or type(self), 

1018 ) 

1019 self.__color_cache.clear() 

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

1021 

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

1023 class __ColorTree: 

1024 """ 

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

1026 

1027 """ 

1028 

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

1030 """ 

1031 Colors in this node. 

1032 

1033 """ 

1034 

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

1036 """ 

1037 Location part of the tree. 

1038 

1039 """ 

1040 

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

1042 """ 

1043 Context part of the tree. 

1044 

1045 """ 

1046 

1047 @functools.cached_property 

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

1049 root = self.__ColorTree() 

1050 

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

1052 loc, ctx = self.__parse_path(path) 

1053 

1054 node = root 

1055 

1056 for part in loc: 

1057 if part not in node.loc: 

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

1059 node = node.loc[part] 

1060 

1061 for part in ctx: 

1062 if part not in node.ctx: 

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

1064 node = node.ctx[part] 

1065 

1066 node.colors = colors 

1067 

1068 return root 

1069 

1070 @staticmethod 

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

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

1073 if len(path_parts) == 1: 

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

1075 else: 

1076 loc, ctx = path_parts 

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

1078 

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

1080 """ 

1081 Lookup a color by path. 

1082 

1083 """ 

1084 

1085 color = yuio.color.Color.NONE 

1086 for path in paths.split(): 

1087 color |= self.__get_color(path) 

1088 return color 

1089 

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

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

1092 path, yuio.MISSING 

1093 ) 

1094 if res is None: 

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

1096 return yuio.color.Color.NONE 

1097 elif res is not yuio.MISSING: 

1098 return res 

1099 

1100 self.__color_cache[path] = None 

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

1102 try: 

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

1104 except ValueError as e: 

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