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

1from __future__ import annotations 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

2 

3from collections.abc import Mapping 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

4from enum import IntEnum 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

5from typing import Any, TextIO 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

6 

7from .utils import auto_highlight 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

8 

9__all__ = 'sformat', 'sprint' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

10 

11 

12def strip_ansi(value: str) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

13 import re 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

14 

15 return re.sub('\033\\[((?:\\d|;)*)([a-zA-Z])', '', value) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

16 

17 

18class Style(IntEnum): 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

19 reset = 0 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

20 

21 bold = 1 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

22 not_bold = 22 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

23 

24 dim = 2 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

25 not_dim = 22 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

26 

27 italic = 3 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

28 not_italic = 23 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

29 

30 underline = 4 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

31 not_underline = 24 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

32 

33 blink = 5 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

34 not_blink = 25 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

35 

36 reverse = 7 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

37 not_reverse = 27 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

38 

39 strike_through = 9 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

40 not_strike_through = 29 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

41 

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

51 

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

61 

62 # this is a meta value used for the "Style" instance which is the "style" function 

63 function = -1 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

64 

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. 

68 

69 By default the styling is cleared at the end of the string, this can be prevented with``reset=False``. 

70 

71 Examples:: 

72 

73 print(sformat('Hello World!', sformat.green)) 

74 print(sformat('ATTENTION!', sformat.bg_magenta)) 

75 print(sformat('Some things', sformat.reverse, sformat.bold)) 

76 

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

95 

96 if codes: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

97 r = _as_ansi(';'.join(codes)) + text 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

98 else: 

99 r = text 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

100 

101 if reset: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

102 r += _as_ansi(_style_as_int(self.reset)) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

103 return r 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

104 

105 @property 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

106 def styles(self) -> Mapping[str, Style]: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

107 return self.__class__.__members__ 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

108 

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

114 

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

123 

124 

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) 

130 

131 

132def _as_ansi(s: str) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

133 return f'\033[{s}m' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

134 

135 

136sformat = Style(-1) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

137 

138 

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

144 

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

156 

157 def __getattr__(self, item: str) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

158 return getattr(sformat, item) 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

159 

160 def __repr__(self) -> str: 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

161 return '<pseudo function sprint(text, *styles)>' 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ

162 

163 

164sprint = StylePrint() 1abcdefghijklmnopqrstuvwxyzABCDEFGHIJ