Coverage for devtools/ansi.py: 98.06%
87 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-11 17:56 +0000
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-11 17:56 +0000
1from __future__ import annotations 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
3from collections.abc import Mapping 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
4from enum import IntEnum 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
5from typing import Any, TextIO 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
7from .utils import auto_highlight 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
9__all__ = 'sformat', 'sprint' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
12def strip_ansi(value: str) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
13 import re 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
15 return re.sub('\033\\[((?:\\d|;)*)([a-zA-Z])', '', value) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
18class Style(IntEnum): 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
19 reset = 0 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
21 bold = 1 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
22 not_bold = 22 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
24 dim = 2 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
25 not_dim = 22 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
27 italic = 3 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
28 not_italic = 23 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
30 underline = 4 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
31 not_underline = 24 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
33 blink = 5 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
34 not_blink = 25 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
36 reverse = 7 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
37 not_reverse = 27 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
39 strike_through = 9 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
40 not_strike_through = 29 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
42 # foreground colours
43 black = 30 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
44 red = 31 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
45 green = 32 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
46 yellow = 33 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
47 blue = 34 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
48 magenta = 35 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
49 cyan = 36 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
50 white = 37 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
52 # background colours
53 bg_black = 40 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
54 bg_red = 41 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
55 bg_green = 42 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
56 bg_yellow = 43 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
57 bg_blue = 44 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
58 bg_magenta = 45 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
59 bg_cyan = 46 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
60 bg_white = 47 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
62 # this is a meta value used for the "Style" instance which is the "style" function
63 function = -1 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
65 def __call__(self, input: Any, *styles: Style | int | str, reset: bool = True, apply: bool = True) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
66 """
67 Styles text with ANSI styles and returns the new string.
69 By default the styling is cleared at the end of the string, this can be prevented with``reset=False``.
71 Examples::
73 print(sformat('Hello World!', sformat.green))
74 print(sformat('ATTENTION!', sformat.bg_magenta))
75 print(sformat('Some things', sformat.reverse, sformat.bold))
77 :param input: the object to style with ansi codes.
78 :param *styles: zero or more styles to apply to the text, should be either style instances or strings
79 matching style names.
80 :param reset: if False the ansi reset code is not appended to the end of the string
81 :param: apply: if False no ansi codes are applied
82 """
83 text = str(input) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
84 if not apply: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
85 return text 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
86 codes: list[str] = [] 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
87 for s in styles: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
88 # raw ints are allowed
89 if isinstance(s, str): 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
90 try: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
91 s = self.styles[s] 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
92 except KeyError: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
93 raise ValueError(f'invalid style "{s}"') from None 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
94 codes.append(_style_as_int(s)) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
96 if codes: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
97 r = _as_ansi(';'.join(codes)) + text 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
98 else:
99 r = text 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
101 if reset: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
102 r += _as_ansi(_style_as_int(self.reset)) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
103 return r 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
105 @property 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
106 def styles(self) -> Mapping[str, Style]: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
107 return self.__class__.__members__ 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
109 def __repr__(self) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
110 if self == self.function: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
111 return '<pseudo function sformat(text, *styles)>' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
112 else:
113 return super().__repr__() 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
115 def __str__(self) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
116 if self == self.function: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
117 return repr(self) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
118 else:
119 # this matches `super().__str__()` in python 3.7 - 3.10
120 # required since IntEnum.__str__ was changed in 3.11,
121 # see https://docs.python.org/3/library/enum.html#enum.IntEnum
122 return f'{self.__class__.__name__}.{self._name_}' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
125def _style_as_int(v: Style | int) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
126 if isinstance(v, Style): 126 ↛ 129line 126 didn't jump to line 129 because the condition on line 126 was always true1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
127 return str(v.value) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
128 else:
129 return str(v)
132def _as_ansi(s: str) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
133 return f'\033[{s}m' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
136sformat = Style(-1) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
139class StylePrint: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
140 """
141 Annoyingly enums do not allow inheritance, a lazy design mistake, this is an ugly work around
142 for that mistake.
143 """
145 def __call__( 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
146 self,
147 input: str,
148 *styles: Style | int | str,
149 reset: bool = True,
150 flush: bool = True,
151 file: TextIO | None = None,
152 **print_kwargs: Any,
153 ) -> None:
154 text = sformat(input, *styles, reset=reset, apply=auto_highlight(file)) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
155 print(text, flush=flush, file=file, **print_kwargs) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
157 def __getattr__(self, item: str) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
158 return getattr(sformat, item) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
160 def __repr__(self) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
161 return '<pseudo function sprint(text, *styles)>' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ
164sprint = StylePrint() 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ