Coverage for typer / _click / formatting.py: 100%

134 statements  

« prev     ^ index     » next       coverage.py v7.13.1, created at 2026-11-18 11:12 +0000

1from collections.abc import Generator, Iterable, Iterator, Sequence 1abcdefghij

2from contextlib import contextmanager 1abcdefghij

3 

4from ._compat import term_len 1abcdefghij

5from .parser import _split_opt 1abcdefghij

6 

7# Can force a width. This is used by the test system 

8FORCED_WIDTH: int | None = None 1abcdefghij

9 

10 

11def measure_table(rows: Iterable[tuple[str, str]]) -> tuple[int, ...]: 1abcdefghij

12 widths: dict[int, int] = {} 1abcdefghij

13 

14 for row in rows: 1abcdefghij

15 for idx, col in enumerate(row): 1abcdefghij

16 widths[idx] = max(widths.get(idx, 0), term_len(col)) 1abcdefghij

17 

18 return tuple(y for x, y in sorted(widths.items())) 1abcdefghij

19 

20 

21def iter_rows( 1abcdefghij

22 rows: Iterable[tuple[str, str]], col_count: int 

23) -> Iterator[tuple[str, ...]]: 

24 for row in rows: 1abcdefghij

25 yield row + ("",) * (col_count - len(row)) 1abcdefghij

26 

27 

28def wrap_text( 1abcdefghij

29 text: str, 

30 width: int = 78, 

31 initial_indent: str = "", 

32 subsequent_indent: str = "", 

33 preserve_paragraphs: bool = False, 

34) -> str: 

35 """A helper function that intelligently wraps text. By default, it 

36 assumes that it operates on a single paragraph of text but if the 

37 `preserve_paragraphs` parameter is provided it will intelligently 

38 handle paragraphs (defined by two empty lines). 

39 

40 If paragraphs are handled, a paragraph can be prefixed with an empty 

41 line containing the ``\\b`` character (``\\x08``) to indicate that 

42 no rewrapping should happen in that block. 

43 """ 

44 from ._textwrap import TextWrapper 1abcdefghij

45 

46 text = text.expandtabs() 1abcdefghij

47 wrapper = TextWrapper( 1abcdefghij

48 width, 

49 initial_indent=initial_indent, 

50 subsequent_indent=subsequent_indent, 

51 replace_whitespace=False, 

52 ) 

53 if not preserve_paragraphs: 1abcdefghij

54 return wrapper.fill(text) 1abcdefghij

55 

56 p: list[tuple[int, bool, str]] = [] 1abcdefghij

57 buf: list[str] = [] 1abcdefghij

58 indent = None 1abcdefghij

59 

60 def _flush_par() -> None: 1abcdefghij

61 if not buf: 1abcdefghij

62 return 1abcdefghij

63 if buf[0].strip() == "\b": 1abcdefghij

64 p.append((indent or 0, True, "\n".join(buf[1:]))) 1abcdefghij

65 else: 

66 p.append((indent or 0, False, " ".join(buf))) 1abcdefghij

67 del buf[:] 1abcdefghij

68 

69 for line in text.splitlines(): 1abcdefghij

70 if not line: 1abcdefghij

71 _flush_par() 1abcdefghij

72 indent = None 1abcdefghij

73 else: 

74 if indent is None: 1abcdefghij

75 orig_len = term_len(line) 1abcdefghij

76 line = line.lstrip() 1abcdefghij

77 indent = orig_len - term_len(line) 1abcdefghij

78 buf.append(line) 1abcdefghij

79 _flush_par() 1abcdefghij

80 

81 rv = [] 1abcdefghij

82 for indent, raw, text in p: 1abcdefghij

83 with wrapper.extra_indent(" " * indent): 1abcdefghij

84 if raw: 1abcdefghij

85 rv.append(wrapper.indent_only(text)) 1abcdefghij

86 else: 

87 rv.append(wrapper.fill(text)) 1abcdefghij

88 

89 return "\n\n".join(rv) 1abcdefghij

90 

91 

92class HelpFormatter: 1abcdefghij

93 """This class helps with formatting text-based help pages. It's 

94 usually just needed for very special internal cases, but it's also 

95 exposed so that developers can write their own fancy outputs. 

96 

97 At present, it always writes into memory. 

98 """ 

99 

100 def __init__( 1abcdefghij

101 self, 

102 indent_increment: int = 2, 

103 width: int | None = None, 

104 max_width: int | None = None, 

105 ) -> None: 

106 self.indent_increment = indent_increment 1abcdefghij

107 if max_width is None: 1abcdefghij

108 max_width = 80 1abcdefghij

109 if width is None: 1abcdefghij

110 import shutil 1abcdefghij

111 

112 width = FORCED_WIDTH 1abcdefghij

113 if width is None: 1abcdefghij

114 width = max(min(shutil.get_terminal_size().columns, max_width) - 2, 50) 1abcdefghij

115 self.width = width 1abcdefghij

116 self.current_indent: int = 0 1abcdefghij

117 self.buffer: list[str] = [] 1abcdefghij

118 

119 def write(self, string: str) -> None: 1abcdefghij

120 """Writes a unicode string into the internal buffer.""" 

121 self.buffer.append(string) 1abcdefghij

122 

123 def indent(self) -> None: 1abcdefghij

124 """Increases the indentation.""" 

125 self.current_indent += self.indent_increment 1abcdefghij

126 

127 def dedent(self) -> None: 1abcdefghij

128 """Decreases the indentation.""" 

129 self.current_indent -= self.indent_increment 1abcdefghij

130 

131 def write_usage(self, prog: str, args: str = "", prefix: str | None = None) -> None: 1abcdefghij

132 """Writes a usage line into the buffer.""" 

133 if prefix is None: 1abcdefghij

134 prefix = "Usage: " 1abcdefghij

135 

136 usage_prefix = f"{prefix:>{self.current_indent}}{prog} " 1abcdefghij

137 text_width = self.width - self.current_indent 1abcdefghij

138 

139 if text_width >= (term_len(usage_prefix) + 20): 1abcdefghij

140 # The arguments will fit to the right of the prefix. 

141 indent = " " * term_len(usage_prefix) 1abcdefghij

142 self.write( 1abcdefghij

143 wrap_text( 

144 args, 

145 text_width, 

146 initial_indent=usage_prefix, 

147 subsequent_indent=indent, 

148 ) 

149 ) 

150 else: 

151 # The prefix is too long, put the arguments on the next line. 

152 self.write(usage_prefix) 1abcdefghij

153 self.write("\n") 1abcdefghij

154 indent = " " * (max(self.current_indent, term_len(prefix)) + 4) 1abcdefghij

155 self.write( 1abcdefghij

156 wrap_text( 

157 args, text_width, initial_indent=indent, subsequent_indent=indent 

158 ) 

159 ) 

160 

161 self.write("\n") 1abcdefghij

162 

163 def write_heading(self, heading: str) -> None: 1abcdefghij

164 """Writes a heading into the buffer.""" 

165 self.write(f"{'':>{self.current_indent}}{heading}:\n") 1abcdefghij

166 

167 def write_paragraph(self) -> None: 1abcdefghij

168 """Writes a paragraph into the buffer.""" 

169 if self.buffer: 1abcdefghij

170 self.write("\n") 1abcdefghij

171 

172 def write_text(self, text: str) -> None: 1abcdefghij

173 """Writes re-indented text into the buffer. This rewraps and 

174 preserves paragraphs. 

175 """ 

176 indent = " " * self.current_indent 1abcdefghij

177 self.write( 1abcdefghij

178 wrap_text( 

179 text, 

180 self.width, 

181 initial_indent=indent, 

182 subsequent_indent=indent, 

183 preserve_paragraphs=True, 

184 ) 

185 ) 

186 self.write("\n") 1abcdefghij

187 

188 def write_dl( 1abcdefghij

189 self, 

190 rows: Sequence[tuple[str, str]], 

191 col_max: int = 30, 

192 col_spacing: int = 2, 

193 ) -> None: 

194 """Writes a definition list into the buffer. This is how options 

195 and commands are usually formatted. 

196 """ 

197 rows = list(rows) 1abcdefghij

198 widths = measure_table(rows) 1abcdefghij

199 if len(widths) != 2: # pragma: no cover 1abcdefghij

200 raise TypeError("Expected two columns for definition list") 

201 

202 first_col = min(widths[0], col_max) + col_spacing 1abcdefghij

203 

204 for first, second in iter_rows(rows, len(widths)): 1abcdefghij

205 self.write(f"{'':>{self.current_indent}}{first}") 1abcdefghij

206 if not second: 1abcdefghij

207 self.write("\n") 1abcdefghij

208 continue 1abcdefghij

209 if term_len(first) <= first_col - col_spacing: 1abcdefghij

210 self.write(" " * (first_col - term_len(first))) 1abcdefghij

211 else: 

212 self.write("\n") 1abcdefghij

213 self.write(" " * (first_col + self.current_indent)) 1abcdefghij

214 

215 text_width = max(self.width - first_col - 2, 10) 1abcdefghij

216 wrapped_text = wrap_text(second, text_width, preserve_paragraphs=True) 1abcdefghij

217 lines = wrapped_text.splitlines() 1abcdefghij

218 

219 if lines: 1abcdefghij

220 self.write(f"{lines[0]}\n") 1abcdefghij

221 

222 for line in lines[1:]: 1abcdefghij

223 self.write(f"{'':>{first_col + self.current_indent}}{line}\n") 1abcdefghij

224 else: # pragma: no cover 

225 self.write("\n") 

226 

227 @contextmanager 1abcdefghij

228 def section(self, name: str) -> Generator[None]: 1abcdefghij

229 """Helpful context manager that writes a paragraph, a heading, 

230 and the indents. 

231 """ 

232 self.write_paragraph() 1abcdefghij

233 self.write_heading(name) 1abcdefghij

234 self.indent() 1abcdefghij

235 try: 1abcdefghij

236 yield 1abcdefghij

237 finally: 

238 self.dedent() 1abcdefghij

239 

240 @contextmanager 1abcdefghij

241 def indentation(self) -> Generator[None]: 1abcdefghij

242 """A context manager that increases the indentation.""" 

243 self.indent() 1abcdefghij

244 try: 1abcdefghij

245 yield 1abcdefghij

246 finally: 

247 self.dedent() 1abcdefghij

248 

249 def getvalue(self) -> str: 1abcdefghij

250 """Returns the buffer contents.""" 

251 return "".join(self.buffer) 1abcdefghij

252 

253 

254def join_options(options: Sequence[str]) -> tuple[str, bool]: 1abcdefghij

255 """Given a list of option strings this joins them in the most appropriate 

256 way and returns them in the form ``(formatted_string, 

257 any_prefix_is_slash)`` where the second item in the tuple is a flag that 

258 indicates if any of the option prefixes was a slash. 

259 """ 

260 rv = [] 1abcdefghij

261 any_prefix_is_slash = False 1abcdefghij

262 

263 for opt in options: 1abcdefghij

264 prefix = _split_opt(opt)[0] 1abcdefghij

265 

266 if prefix == "/": 1abcdefghij

267 any_prefix_is_slash = True 1abcdefghij

268 

269 rv.append((len(prefix), opt)) 1abcdefghij

270 

271 rv.sort(key=lambda x: x[0]) 1abcdefghij

272 return ", ".join(x[1] for x in rv), any_prefix_is_slash 1abcdefghij