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

289 statements  

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

1""" 

2To keep the import times down, some infrequently used termui functionality 

3is placed here and only imported as needed. 

4""" 

5 

6import contextlib 1abcdhijefg

7import math 1abcdhijefg

8import os 1abcdhijefg

9import sys 1abcdhijefg

10import time 1abcdhijefg

11from collections.abc import Callable, Generator, Iterable, Iterator 1abcdhijefg

12from io import StringIO 1abcdhijefg

13from types import TracebackType 1abcdhijefg

14from typing import Generic, TextIO, TypeVar, cast 1abcdhijefg

15 

16from ._compat import ( 1abcdhijefg

17 CYGWIN, 

18 WIN, 

19 _default_text_stdout, 

20 get_best_encoding, 

21 isatty, 

22 term_len, 

23) 

24from .utils import echo 1abcdhijefg

25 

26V = TypeVar("V") 1abcdhijefg

27 

28if os.name == "nt": 1abcdhijefg

29 BEFORE_BAR = "\r" 1hij

30 AFTER_BAR = "\n" 1hij

31else: 

32 BEFORE_BAR = "\r\033[?25l" 1abcdefg

33 AFTER_BAR = "\033[?25h\n" 1abcdefg

34 

35 

36class ProgressBar(Generic[V]): 1abcdhijefg

37 def __init__( 1abcdhijefg

38 self, 

39 iterable: Iterable[V] | None, 

40 length: int | None = None, 

41 fill_char: str = "#", 

42 empty_char: str = " ", 

43 bar_template: str = "%(bar)s", 

44 info_sep: str = " ", 

45 hidden: bool = False, 

46 show_eta: bool = True, 

47 show_percent: bool | None = None, 

48 show_pos: bool = False, 

49 item_show_func: Callable[[V | None], str | None] | None = None, 

50 label: str | None = None, 

51 file: TextIO | None = None, 

52 color: bool | None = None, 

53 update_min_steps: int = 1, 

54 width: int = 30, 

55 ) -> None: 

56 self.fill_char = fill_char 1abcdhijefg

57 self.empty_char = empty_char 1abcdhijefg

58 self.bar_template = bar_template 1abcdhijefg

59 self.info_sep = info_sep 1abcdhijefg

60 self.hidden = hidden 1abcdhijefg

61 self.show_eta = show_eta 1abcdhijefg

62 self.show_percent = show_percent 1abcdhijefg

63 self.show_pos = show_pos 1abcdhijefg

64 self.item_show_func = item_show_func 1abcdhijefg

65 self.label: str = label or "" 1abcdhijefg

66 

67 if file is None: 1abcdhijefg

68 file = _default_text_stdout() 1abcdhijefg

69 

70 # There are no standard streams attached to write to. For example, 

71 # pythonw on Windows. 

72 if file is None: # pragma: no cover 1abcdhijefg

73 file = StringIO() 

74 

75 self.file = file 1abcdhijefg

76 self.color = color 1abcdhijefg

77 self.update_min_steps = update_min_steps 1abcdhijefg

78 self._completed_intervals = 0 1abcdhijefg

79 self.width: int = width 1abcdhijefg

80 self.autowidth: bool = width == 0 1abcdhijefg

81 

82 if length is None: 1abcdhijefg

83 from operator import length_hint 1abcdhijefg

84 

85 length = length_hint(iterable, -1) 1abcdhijefg

86 

87 if length == -1: # pragma: no cover 1abcdhijefg

88 length = None 1abcdhijefg

89 if iterable is None: 1abcdhijefg

90 if length is None: # pragma: no cover 1abcdhijefg

91 raise TypeError("iterable or length is required") 

92 iterable = cast("Iterable[V]", range(length)) 1abcdhijefg

93 self.iter: Iterable[V] = iter(iterable) 1abcdhijefg

94 self.length = length 1abcdhijefg

95 self.pos: int = 0 1abcdhijefg

96 self.avg: list[float] = [] 1abcdhijefg

97 self.last_eta: float 1abcdhijefg

98 self.start: float 1abcdhijefg

99 self.start = self.last_eta = time.time() 1abcdhijefg

100 self.eta_known: bool = False 1abcdhijefg

101 self.finished: bool = False 1abcdhijefg

102 self.max_width: int | None = None 1abcdhijefg

103 self.entered: bool = False 1abcdhijefg

104 self.current_item: V | None = None 1abcdhijefg

105 self._is_atty = isatty(self.file) 1abcdhijefg

106 self._last_line: str | None = None 1abcdhijefg

107 

108 def __enter__(self) -> "ProgressBar[V]": 1abcdhijefg

109 self.entered = True 1abcdhijefg

110 self.render_progress() 1abcdhijefg

111 return self 1abcdhijefg

112 

113 def __exit__( 1abcdhijefg

114 self, 

115 exc_type: type[BaseException] | None, 

116 exc_value: BaseException | None, 

117 tb: TracebackType | None, 

118 ) -> None: 

119 self.render_finish() 1abcdhijefg

120 

121 def __iter__(self) -> Iterator[V]: 1abcdhijefg

122 if not self.entered: 1abcdhijefg

123 raise RuntimeError("You need to use progress bars in a with block.") 1abcdhijefg

124 self.render_progress() 1abcdhijefg

125 return self.generator() 1abcdhijefg

126 

127 def __next__(self) -> V: 1abcdhijefg

128 # Iteration is defined in terms of a generator function, 

129 # returned by iter(self); use that to define next(). This works 

130 # because `self.iter` is an iterable consumed by that generator, 

131 # so it is re-entry safe. Calling `next(self.generator())` 

132 # twice works and does "what you want". 

133 return next(iter(self)) 1abcdhijefg

134 

135 def render_finish(self) -> None: 1abcdhijefg

136 if self.hidden or not self._is_atty: 1abcdhijefg

137 return 1abcdhijefg

138 self.file.write(AFTER_BAR) 1abcdhijefg

139 self.file.flush() 1abcdhijefg

140 

141 @property 1abcdhijefg

142 def pct(self) -> float: 1abcdhijefg

143 if self.finished: 1abcdhijefg

144 return 1.0 1abcdhijefg

145 return min(self.pos / (float(self.length or 1) or 1), 1.0) 1abcdhijefg

146 

147 @property 1abcdhijefg

148 def time_per_iteration(self) -> float: 1abcdhijefg

149 if not self.avg: 1abcdhijefg

150 return 0.0 1abcdhijefg

151 return sum(self.avg) / float(len(self.avg)) 1abcdhijefg

152 

153 @property 1abcdhijefg

154 def eta(self) -> float: 1abcdhijefg

155 if self.length is not None and not self.finished: 1abcdhijefg

156 return self.time_per_iteration * (self.length - self.pos) 1abcdhijefg

157 return 0.0 1abcdhijefg

158 

159 def format_eta(self) -> str: 1abcdhijefg

160 if self.eta_known: 1abcdhijefg

161 t = int(self.eta) 1abcdhijefg

162 seconds = t % 60 1abcdhijefg

163 t //= 60 1abcdhijefg

164 minutes = t % 60 1abcdhijefg

165 t //= 60 1abcdhijefg

166 hours = t % 24 1abcdhijefg

167 t //= 24 1abcdhijefg

168 if t > 0: 1abcdhijefg

169 return f"{t}d {hours:02}:{minutes:02}:{seconds:02}" 1abcdhijefg

170 else: 

171 return f"{hours:02}:{minutes:02}:{seconds:02}" 1abcdhijefg

172 return "" 1abcdhijefg

173 

174 def format_pos(self) -> str: 1abcdhijefg

175 pos = str(self.pos) 1abcdhijefg

176 if self.length is not None: 1abcdhijefg

177 pos += f"/{self.length}" 1abcdhijefg

178 return pos 1abcdhijefg

179 

180 def format_pct(self) -> str: 1abcdhijefg

181 return f"{int(self.pct * 100): 4}%"[1:] 1abcdhijefg

182 

183 def format_bar(self) -> str: 1abcdhijefg

184 if self.length is not None: 1abcdhijefg

185 bar_length = int(self.pct * self.width) 1abcdhijefg

186 bar = self.fill_char * bar_length 1abcdhijefg

187 bar += self.empty_char * (self.width - bar_length) 1abcdhijefg

188 elif self.finished: 1abcdhijefg

189 bar = self.fill_char * self.width 1abcdhijefg

190 else: 

191 chars = list(self.empty_char * (self.width or 1)) 1abcdhijefg

192 if self.time_per_iteration != 0: 1abcdhijefg

193 chars[ 1abcdhijefg

194 int( 

195 (math.cos(self.pos * self.time_per_iteration) / 2.0 + 0.5) 

196 * self.width 

197 ) 

198 ] = self.fill_char 

199 bar = "".join(chars) 1abcdhijefg

200 return bar 1abcdhijefg

201 

202 def format_progress_line(self) -> str: 1abcdhijefg

203 show_percent = self.show_percent 1abcdhijefg

204 

205 info_bits = [] 1abcdhijefg

206 if self.length is not None and show_percent is None: 1abcdhijefg

207 show_percent = not self.show_pos 1abcdhijefg

208 

209 if self.show_pos: 1abcdhijefg

210 info_bits.append(self.format_pos()) 1abcdhijefg

211 if show_percent: 1abcdhijefg

212 info_bits.append(self.format_pct()) 1abcdhijefg

213 if self.show_eta and self.eta_known and not self.finished: 1abcdhijefg

214 info_bits.append(self.format_eta()) 1abcdhijefg

215 if self.item_show_func is not None: 1abcdhijefg

216 item_info = self.item_show_func(self.current_item) 1abcdhijefg

217 if item_info is not None: 1abcdhijefg

218 info_bits.append(item_info) 1abcdhijefg

219 

220 return ( 1abcdhijefg

221 self.bar_template 

222 % { 

223 "label": self.label, 

224 "bar": self.format_bar(), 

225 "info": self.info_sep.join(info_bits), 

226 } 

227 ).rstrip() 

228 

229 def render_progress(self) -> None: 1abcdhijefg

230 if self.hidden: 1abcdhijefg

231 return 1abcdhijefg

232 

233 if not self._is_atty: 1abcdhijefg

234 # Only output the label once if the output is not a TTY. 

235 if self._last_line != self.label: 1abcdhijefg

236 self._last_line = self.label 1abcdhijefg

237 echo(self.label, file=self.file, color=self.color) 1abcdhijefg

238 return 1abcdhijefg

239 

240 buf = [] 1abcdhijefg

241 # Update width in case the terminal has been resized 

242 if self.autowidth: 1abcdhijefg

243 import shutil 1abcdhijefg

244 

245 old_width = self.width 1abcdhijefg

246 self.width = 0 1abcdhijefg

247 clutter_length = term_len(self.format_progress_line()) 1abcdhijefg

248 new_width = max(0, shutil.get_terminal_size().columns - clutter_length) 1abcdhijefg

249 if new_width < old_width and self.max_width is not None: 1abcdhijefg

250 buf.append(BEFORE_BAR) 1abcdhijefg

251 buf.append(" " * self.max_width) 1abcdhijefg

252 self.max_width = new_width 1abcdhijefg

253 self.width = new_width 1abcdhijefg

254 

255 clear_width = self.width 1abcdhijefg

256 if self.max_width is not None: 1abcdhijefg

257 clear_width = self.max_width 1abcdhijefg

258 

259 buf.append(BEFORE_BAR) 1abcdhijefg

260 line = self.format_progress_line() 1abcdhijefg

261 line_len = term_len(line) 1abcdhijefg

262 if self.max_width is None or self.max_width < line_len: 1abcdhijefg

263 self.max_width = line_len 1abcdhijefg

264 

265 buf.append(line) 1abcdhijefg

266 buf.append(" " * (clear_width - line_len)) 1abcdhijefg

267 line = "".join(buf) 1abcdhijefg

268 # Render the line only if it changed. 

269 

270 if line != self._last_line: 1abcdhijefg

271 self._last_line = line 1abcdhijefg

272 echo(line, file=self.file, color=self.color, nl=False) 1abcdhijefg

273 self.file.flush() 1abcdhijefg

274 

275 def make_step(self, n_steps: int) -> None: 1abcdhijefg

276 self.pos += n_steps 1abcdhijefg

277 if self.length is not None and self.pos >= self.length: 1abcdhijefg

278 self.finished = True 1abcdhijefg

279 

280 if (time.time() - self.last_eta) < 1.0: 1abcdhijefg

281 return 1abcdhijefg

282 

283 self.last_eta = time.time() 1abcdhijefg

284 

285 # self.avg is a rolling list of length <= 7 of steps where steps are 

286 # defined as time elapsed divided by the total progress through 

287 # self.length. 

288 if self.pos: 1abcdhijefg

289 step = (time.time() - self.start) / self.pos 1abcdhijefg

290 else: 

291 step = time.time() - self.start 1abcdhijefg

292 

293 self.avg = self.avg[-6:] + [step] 1abcdhijefg

294 

295 self.eta_known = self.length is not None 1abcdhijefg

296 

297 def update(self, n_steps: int) -> None: 1abcdhijefg

298 """Update the progress bar by advancing a specified number of steps.""" 

299 self._completed_intervals += n_steps 1abcdhijefg

300 

301 if self._completed_intervals >= self.update_min_steps: 1abcdhijefg

302 self.make_step(self._completed_intervals) 1abcdhijefg

303 self.render_progress() 1abcdhijefg

304 self._completed_intervals = 0 1abcdhijefg

305 

306 def finish(self) -> None: 1abcdhijefg

307 self.eta_known = False 1abcdhijefg

308 self.current_item = None 1abcdhijefg

309 self.finished = True 1abcdhijefg

310 

311 def generator(self) -> Iterator[V]: 1abcdhijefg

312 """Return a generator which yields the items added to the bar 

313 during construction, and updates the progress bar *after* the 

314 yielded block returns. 

315 """ 

316 # WARNING: the iterator interface for `ProgressBar` relies on 

317 # this and only works because this is a simple generator which 

318 # doesn't create or manage additional state. If this function 

319 # changes, the impact should be evaluated both against 

320 # `iter(bar)` and `next(bar)`. `next()` in particular may call 

321 # `self.generator()` repeatedly, and this must remain safe in 

322 # order for that interface to work. 

323 if not self.entered: # pragma: no cover 1abcdhijefg

324 raise RuntimeError("You need to use progress bars in a with block.") 

325 

326 if not self._is_atty: 1abcdhijefg

327 yield from self.iter 1abcdhijefg

328 else: 

329 for rv in self.iter: 1abcdhijefg

330 self.current_item = rv 1abcdhijefg

331 

332 # This allows show_item_func to be updated before the 

333 # item is processed. Only trigger at the beginning of 

334 # the update interval. 

335 if self._completed_intervals == 0: 1abcdhijefg

336 self.render_progress() 1abcdhijefg

337 

338 yield rv 1abcdhijefg

339 self.update(1) 1abcdhijefg

340 

341 self.finish() 1abcdhijefg

342 self.render_progress() 1abcdhijefg

343 

344 

345def open_url(url: str, wait: bool = False, locate: bool = False) -> int: 1abcdhijefg

346 import subprocess 1abcdhijefg

347 

348 def _unquote_file(url: str) -> str: 1abcdhijefg

349 from urllib.parse import unquote 1abcdhijefg

350 

351 if url.startswith("file://"): 1abcdhijefg

352 url = unquote(url[7:]) 1hij

353 

354 return url 1abcdhijefg

355 

356 if sys.platform == "darwin": 1abcdhijefg

357 args = ["open"] 1efg

358 if wait: 1efg

359 args.append("-W") 1efg

360 if locate: 1efg

361 args.append("-R") 1efg

362 args.append(_unquote_file(url)) 1efg

363 null = open("/dev/null", "w") 1efg

364 try: 1efg

365 return subprocess.Popen(args, stderr=null).wait() 1efg

366 finally: 

367 null.close() 1efg

368 elif WIN: 1abcdhij

369 if locate: 1hij

370 url = _unquote_file(url) 1hij

371 args = ["explorer", f"/select,{url}"] 1hij

372 else: 

373 args = ["start"] 1hij

374 if wait: 1hij

375 args.append("/WAIT") 1hij

376 args.append("") 1hij

377 args.append(url) 1hij

378 try: 1hij

379 return subprocess.call(args) 1hij

380 except OSError: 1hij

381 # Command not found 

382 return 127 1hij

383 elif CYGWIN: # pragma: no cover 1abcd

384 if locate: 

385 url = _unquote_file(url) 

386 args = ["cygstart", os.path.dirname(url)] 

387 else: 

388 args = ["cygstart"] 

389 if wait: 

390 args.append("-w") 

391 args.append(url) 

392 try: 

393 return subprocess.call(args) 

394 except OSError: 

395 # Command not found 

396 return 127 

397 

398 try: 1abcd

399 if locate: 1abcd

400 url = os.path.dirname(_unquote_file(url)) or "." 1abcd

401 else: 

402 url = _unquote_file(url) 1abcd

403 c = subprocess.Popen(["xdg-open", url]) 1abcd

404 if wait: 1abcd

405 return c.wait() 1abcd

406 return 0 1abcd

407 except OSError: # pragma: no cover 

408 # TODO: remove this part, doesn't get hit by Typer code paths? 

409 if url.startswith(("http://", "https://")) and not locate and not wait: 

410 import webbrowser 

411 

412 webbrowser.open(url) 

413 return 0 

414 return 1 

415 

416 

417def _translate_ch_to_exc(ch: str) -> None: 1abcdhijefg

418 if ch == "\x03": 1abcdhijefg

419 raise KeyboardInterrupt() 1hij

420 

421 if ch == "\x04" and not WIN: # Unix-like, Ctrl+D 1abcdhijefg

422 raise EOFError() 1abcdefg

423 

424 if ch == "\x1a" and WIN: # Windows, Ctrl+Z 1abcdhijefg

425 raise EOFError() 1hij

426 

427 return None 1abcdhijefg

428 

429 

430if sys.platform == "win32": 1abcdhijefg

431 import msvcrt 1hij

432 

433 @contextlib.contextmanager 1hij

434 def raw_terminal() -> Iterator[int]: 1hij

435 yield -1 1hij

436 

437 def getchar(echo: bool) -> str: 1hij

438 # The function `getch` will return a bytes object corresponding to 

439 # the pressed character. Since Windows 10 build 1803, it will also 

440 # return \x00 when called a second time after pressing a regular key. 

441 # 

442 # `getwch` does not share this probably-bugged behavior. Moreover, it 

443 # returns a Unicode object by default, which is what we want. 

444 # 

445 # Either of these functions will return \x00 or \xe0 to indicate 

446 # a special key, and you need to call the same function again to get 

447 # the "rest" of the code. The fun part is that \u00e0 is 

448 # "latin small letter a with grave", so if you type that on a French 

449 # keyboard, you _also_ get a \xe0. 

450 # E.g., consider the Up arrow. This returns \xe0 and then \x48. The 

451 # resulting Unicode string reads as "a with grave" + "capital H". 

452 # This is indistinguishable from when the user actually types 

453 # "a with grave" and then "capital H". 

454 # 

455 # When \xe0 is returned, we assume it's part of a special-key sequence 

456 # and call `getwch` again, but that means that when the user types 

457 # the \u00e0 character, `getchar` doesn't return until a second 

458 # character is typed. 

459 # The alternative is returning immediately, but that would mess up 

460 # cross-platform handling of arrow keys and others that start with 

461 # \xe0. Another option is using `getch`, but then we can't reliably 

462 # read non-ASCII characters, because return values of `getch` are 

463 # limited to the current 8-bit codepage. 

464 # 

465 # Anyway, Click doesn't claim to do this Right(tm), and using `getwch` 

466 # is doing the right thing in more situations than with `getch`. 

467 

468 if echo: 1hij

469 func = cast(Callable[[], str], msvcrt.getwche) 1hij

470 else: 

471 func = cast(Callable[[], str], msvcrt.getwch) 1hij

472 

473 rv = func() 1hij

474 

475 if rv in ("\x00", "\xe0"): 1hij

476 # \x00 and \xe0 are control characters that indicate special key, 

477 # see above. 

478 rv += func() 1hij

479 

480 _translate_ch_to_exc(rv) 1hij

481 return rv 1hij

482 

483else: 

484 import termios 1abcdefg

485 import tty 1abcdefg

486 

487 @contextlib.contextmanager 1abcdefg

488 def raw_terminal() -> Generator[int]: 1abcdefg

489 f: TextIO | None 

490 fd: int 

491 

492 if not isatty(sys.stdin): 1abcdefg

493 f = open("/dev/tty") 1abcdefg

494 fd = f.fileno() 1abcdefg

495 else: 

496 fd = sys.stdin.fileno() 1abcdefg

497 f = None 1abcdefg

498 

499 try: 1abcdefg

500 old_settings = termios.tcgetattr(fd) 1abcdefg

501 

502 try: 1abcdefg

503 tty.setraw(fd) 1abcdefg

504 yield fd 1abcdefg

505 finally: 

506 termios.tcsetattr(fd, termios.TCSADRAIN, old_settings) 1abcdefg

507 sys.stdout.flush() 1abcdefg

508 

509 if f is not None: 1abcdefg

510 f.close() 1abcdefg

511 except termios.error: # pragma: no cover 

512 pass 

513 

514 def getchar(echo: bool) -> str: 1abcdefg

515 with raw_terminal() as fd: 1abcdefg

516 ch = os.read(fd, 32).decode(get_best_encoding(sys.stdin), "replace") 1abcdefg

517 

518 if echo and isatty(sys.stdout): # pragma: no cover 1abcdefg

519 sys.stdout.write(ch) 1abcdefg

520 

521 _translate_ch_to_exc(ch) 1abcdefg

522 return ch 1abcdefg