termui.py 23 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681
  1. import inspect
  2. import io
  3. import itertools
  4. import os
  5. import struct
  6. import sys
  7. from ._compat import DEFAULT_COLUMNS
  8. from ._compat import get_winterm_size
  9. from ._compat import isatty
  10. from ._compat import raw_input
  11. from ._compat import string_types
  12. from ._compat import strip_ansi
  13. from ._compat import text_type
  14. from ._compat import WIN
  15. from .exceptions import Abort
  16. from .exceptions import UsageError
  17. from .globals import resolve_color_default
  18. from .types import Choice
  19. from .types import convert_type
  20. from .types import Path
  21. from .utils import echo
  22. from .utils import LazyFile
  23. # The prompt functions to use. The doc tools currently override these
  24. # functions to customize how they work.
  25. visible_prompt_func = raw_input
  26. _ansi_colors = {
  27. "black": 30,
  28. "red": 31,
  29. "green": 32,
  30. "yellow": 33,
  31. "blue": 34,
  32. "magenta": 35,
  33. "cyan": 36,
  34. "white": 37,
  35. "reset": 39,
  36. "bright_black": 90,
  37. "bright_red": 91,
  38. "bright_green": 92,
  39. "bright_yellow": 93,
  40. "bright_blue": 94,
  41. "bright_magenta": 95,
  42. "bright_cyan": 96,
  43. "bright_white": 97,
  44. }
  45. _ansi_reset_all = "\033[0m"
  46. def hidden_prompt_func(prompt):
  47. import getpass
  48. return getpass.getpass(prompt)
  49. def _build_prompt(
  50. text, suffix, show_default=False, default=None, show_choices=True, type=None
  51. ):
  52. prompt = text
  53. if type is not None and show_choices and isinstance(type, Choice):
  54. prompt += " ({})".format(", ".join(map(str, type.choices)))
  55. if default is not None and show_default:
  56. prompt = "{} [{}]".format(prompt, _format_default(default))
  57. return prompt + suffix
  58. def _format_default(default):
  59. if isinstance(default, (io.IOBase, LazyFile)) and hasattr(default, "name"):
  60. return default.name
  61. return default
  62. def prompt(
  63. text,
  64. default=None,
  65. hide_input=False,
  66. confirmation_prompt=False,
  67. type=None,
  68. value_proc=None,
  69. prompt_suffix=": ",
  70. show_default=True,
  71. err=False,
  72. show_choices=True,
  73. ):
  74. """Prompts a user for input. This is a convenience function that can
  75. be used to prompt a user for input later.
  76. If the user aborts the input by sending a interrupt signal, this
  77. function will catch it and raise a :exc:`Abort` exception.
  78. .. versionadded:: 7.0
  79. Added the show_choices parameter.
  80. .. versionadded:: 6.0
  81. Added unicode support for cmd.exe on Windows.
  82. .. versionadded:: 4.0
  83. Added the `err` parameter.
  84. :param text: the text to show for the prompt.
  85. :param default: the default value to use if no input happens. If this
  86. is not given it will prompt until it's aborted.
  87. :param hide_input: if this is set to true then the input value will
  88. be hidden.
  89. :param confirmation_prompt: asks for confirmation for the value.
  90. :param type: the type to use to check the value against.
  91. :param value_proc: if this parameter is provided it's a function that
  92. is invoked instead of the type conversion to
  93. convert a value.
  94. :param prompt_suffix: a suffix that should be added to the prompt.
  95. :param show_default: shows or hides the default value in the prompt.
  96. :param err: if set to true the file defaults to ``stderr`` instead of
  97. ``stdout``, the same as with echo.
  98. :param show_choices: Show or hide choices if the passed type is a Choice.
  99. For example if type is a Choice of either day or week,
  100. show_choices is true and text is "Group by" then the
  101. prompt will be "Group by (day, week): ".
  102. """
  103. result = None
  104. def prompt_func(text):
  105. f = hidden_prompt_func if hide_input else visible_prompt_func
  106. try:
  107. # Write the prompt separately so that we get nice
  108. # coloring through colorama on Windows
  109. echo(text, nl=False, err=err)
  110. return f("")
  111. except (KeyboardInterrupt, EOFError):
  112. # getpass doesn't print a newline if the user aborts input with ^C.
  113. # Allegedly this behavior is inherited from getpass(3).
  114. # A doc bug has been filed at https://bugs.python.org/issue24711
  115. if hide_input:
  116. echo(None, err=err)
  117. raise Abort()
  118. if value_proc is None:
  119. value_proc = convert_type(type, default)
  120. prompt = _build_prompt(
  121. text, prompt_suffix, show_default, default, show_choices, type
  122. )
  123. while 1:
  124. while 1:
  125. value = prompt_func(prompt)
  126. if value:
  127. break
  128. elif default is not None:
  129. if isinstance(value_proc, Path):
  130. # validate Path default value(exists, dir_okay etc.)
  131. value = default
  132. break
  133. return default
  134. try:
  135. result = value_proc(value)
  136. except UsageError as e:
  137. echo("Error: {}".format(e.message), err=err) # noqa: B306
  138. continue
  139. if not confirmation_prompt:
  140. return result
  141. while 1:
  142. value2 = prompt_func("Repeat for confirmation: ")
  143. if value2:
  144. break
  145. if value == value2:
  146. return result
  147. echo("Error: the two entered values do not match", err=err)
  148. def confirm(
  149. text, default=False, abort=False, prompt_suffix=": ", show_default=True, err=False
  150. ):
  151. """Prompts for confirmation (yes/no question).
  152. If the user aborts the input by sending a interrupt signal this
  153. function will catch it and raise a :exc:`Abort` exception.
  154. .. versionadded:: 4.0
  155. Added the `err` parameter.
  156. :param text: the question to ask.
  157. :param default: the default for the prompt.
  158. :param abort: if this is set to `True` a negative answer aborts the
  159. exception by raising :exc:`Abort`.
  160. :param prompt_suffix: a suffix that should be added to the prompt.
  161. :param show_default: shows or hides the default value in the prompt.
  162. :param err: if set to true the file defaults to ``stderr`` instead of
  163. ``stdout``, the same as with echo.
  164. """
  165. prompt = _build_prompt(
  166. text, prompt_suffix, show_default, "Y/n" if default else "y/N"
  167. )
  168. while 1:
  169. try:
  170. # Write the prompt separately so that we get nice
  171. # coloring through colorama on Windows
  172. echo(prompt, nl=False, err=err)
  173. value = visible_prompt_func("").lower().strip()
  174. except (KeyboardInterrupt, EOFError):
  175. raise Abort()
  176. if value in ("y", "yes"):
  177. rv = True
  178. elif value in ("n", "no"):
  179. rv = False
  180. elif value == "":
  181. rv = default
  182. else:
  183. echo("Error: invalid input", err=err)
  184. continue
  185. break
  186. if abort and not rv:
  187. raise Abort()
  188. return rv
  189. def get_terminal_size():
  190. """Returns the current size of the terminal as tuple in the form
  191. ``(width, height)`` in columns and rows.
  192. """
  193. # If shutil has get_terminal_size() (Python 3.3 and later) use that
  194. if sys.version_info >= (3, 3):
  195. import shutil
  196. shutil_get_terminal_size = getattr(shutil, "get_terminal_size", None)
  197. if shutil_get_terminal_size:
  198. sz = shutil_get_terminal_size()
  199. return sz.columns, sz.lines
  200. # We provide a sensible default for get_winterm_size() when being invoked
  201. # inside a subprocess. Without this, it would not provide a useful input.
  202. if get_winterm_size is not None:
  203. size = get_winterm_size()
  204. if size == (0, 0):
  205. return (79, 24)
  206. else:
  207. return size
  208. def ioctl_gwinsz(fd):
  209. try:
  210. import fcntl
  211. import termios
  212. cr = struct.unpack("hh", fcntl.ioctl(fd, termios.TIOCGWINSZ, "1234"))
  213. except Exception:
  214. return
  215. return cr
  216. cr = ioctl_gwinsz(0) or ioctl_gwinsz(1) or ioctl_gwinsz(2)
  217. if not cr:
  218. try:
  219. fd = os.open(os.ctermid(), os.O_RDONLY)
  220. try:
  221. cr = ioctl_gwinsz(fd)
  222. finally:
  223. os.close(fd)
  224. except Exception:
  225. pass
  226. if not cr or not cr[0] or not cr[1]:
  227. cr = (os.environ.get("LINES", 25), os.environ.get("COLUMNS", DEFAULT_COLUMNS))
  228. return int(cr[1]), int(cr[0])
  229. def echo_via_pager(text_or_generator, color=None):
  230. """This function takes a text and shows it via an environment specific
  231. pager on stdout.
  232. .. versionchanged:: 3.0
  233. Added the `color` flag.
  234. :param text_or_generator: the text to page, or alternatively, a
  235. generator emitting the text to page.
  236. :param color: controls if the pager supports ANSI colors or not. The
  237. default is autodetection.
  238. """
  239. color = resolve_color_default(color)
  240. if inspect.isgeneratorfunction(text_or_generator):
  241. i = text_or_generator()
  242. elif isinstance(text_or_generator, string_types):
  243. i = [text_or_generator]
  244. else:
  245. i = iter(text_or_generator)
  246. # convert every element of i to a text type if necessary
  247. text_generator = (el if isinstance(el, string_types) else text_type(el) for el in i)
  248. from ._termui_impl import pager
  249. return pager(itertools.chain(text_generator, "\n"), color)
  250. def progressbar(
  251. iterable=None,
  252. length=None,
  253. label=None,
  254. show_eta=True,
  255. show_percent=None,
  256. show_pos=False,
  257. item_show_func=None,
  258. fill_char="#",
  259. empty_char="-",
  260. bar_template="%(label)s [%(bar)s] %(info)s",
  261. info_sep=" ",
  262. width=36,
  263. file=None,
  264. color=None,
  265. ):
  266. """This function creates an iterable context manager that can be used
  267. to iterate over something while showing a progress bar. It will
  268. either iterate over the `iterable` or `length` items (that are counted
  269. up). While iteration happens, this function will print a rendered
  270. progress bar to the given `file` (defaults to stdout) and will attempt
  271. to calculate remaining time and more. By default, this progress bar
  272. will not be rendered if the file is not a terminal.
  273. The context manager creates the progress bar. When the context
  274. manager is entered the progress bar is already created. With every
  275. iteration over the progress bar, the iterable passed to the bar is
  276. advanced and the bar is updated. When the context manager exits,
  277. a newline is printed and the progress bar is finalized on screen.
  278. Note: The progress bar is currently designed for use cases where the
  279. total progress can be expected to take at least several seconds.
  280. Because of this, the ProgressBar class object won't display
  281. progress that is considered too fast, and progress where the time
  282. between steps is less than a second.
  283. No printing must happen or the progress bar will be unintentionally
  284. destroyed.
  285. Example usage::
  286. with progressbar(items) as bar:
  287. for item in bar:
  288. do_something_with(item)
  289. Alternatively, if no iterable is specified, one can manually update the
  290. progress bar through the `update()` method instead of directly
  291. iterating over the progress bar. The update method accepts the number
  292. of steps to increment the bar with::
  293. with progressbar(length=chunks.total_bytes) as bar:
  294. for chunk in chunks:
  295. process_chunk(chunk)
  296. bar.update(chunks.bytes)
  297. .. versionadded:: 2.0
  298. .. versionadded:: 4.0
  299. Added the `color` parameter. Added a `update` method to the
  300. progressbar object.
  301. :param iterable: an iterable to iterate over. If not provided the length
  302. is required.
  303. :param length: the number of items to iterate over. By default the
  304. progressbar will attempt to ask the iterator about its
  305. length, which might or might not work. If an iterable is
  306. also provided this parameter can be used to override the
  307. length. If an iterable is not provided the progress bar
  308. will iterate over a range of that length.
  309. :param label: the label to show next to the progress bar.
  310. :param show_eta: enables or disables the estimated time display. This is
  311. automatically disabled if the length cannot be
  312. determined.
  313. :param show_percent: enables or disables the percentage display. The
  314. default is `True` if the iterable has a length or
  315. `False` if not.
  316. :param show_pos: enables or disables the absolute position display. The
  317. default is `False`.
  318. :param item_show_func: a function called with the current item which
  319. can return a string to show the current item
  320. next to the progress bar. Note that the current
  321. item can be `None`!
  322. :param fill_char: the character to use to show the filled part of the
  323. progress bar.
  324. :param empty_char: the character to use to show the non-filled part of
  325. the progress bar.
  326. :param bar_template: the format string to use as template for the bar.
  327. The parameters in it are ``label`` for the label,
  328. ``bar`` for the progress bar and ``info`` for the
  329. info section.
  330. :param info_sep: the separator between multiple info items (eta etc.)
  331. :param width: the width of the progress bar in characters, 0 means full
  332. terminal width
  333. :param file: the file to write to. If this is not a terminal then
  334. only the label is printed.
  335. :param color: controls if the terminal supports ANSI colors or not. The
  336. default is autodetection. This is only needed if ANSI
  337. codes are included anywhere in the progress bar output
  338. which is not the case by default.
  339. """
  340. from ._termui_impl import ProgressBar
  341. color = resolve_color_default(color)
  342. return ProgressBar(
  343. iterable=iterable,
  344. length=length,
  345. show_eta=show_eta,
  346. show_percent=show_percent,
  347. show_pos=show_pos,
  348. item_show_func=item_show_func,
  349. fill_char=fill_char,
  350. empty_char=empty_char,
  351. bar_template=bar_template,
  352. info_sep=info_sep,
  353. file=file,
  354. label=label,
  355. width=width,
  356. color=color,
  357. )
  358. def clear():
  359. """Clears the terminal screen. This will have the effect of clearing
  360. the whole visible space of the terminal and moving the cursor to the
  361. top left. This does not do anything if not connected to a terminal.
  362. .. versionadded:: 2.0
  363. """
  364. if not isatty(sys.stdout):
  365. return
  366. # If we're on Windows and we don't have colorama available, then we
  367. # clear the screen by shelling out. Otherwise we can use an escape
  368. # sequence.
  369. if WIN:
  370. os.system("cls")
  371. else:
  372. sys.stdout.write("\033[2J\033[1;1H")
  373. def style(
  374. text,
  375. fg=None,
  376. bg=None,
  377. bold=None,
  378. dim=None,
  379. underline=None,
  380. blink=None,
  381. reverse=None,
  382. reset=True,
  383. ):
  384. """Styles a text with ANSI styles and returns the new string. By
  385. default the styling is self contained which means that at the end
  386. of the string a reset code is issued. This can be prevented by
  387. passing ``reset=False``.
  388. Examples::
  389. click.echo(click.style('Hello World!', fg='green'))
  390. click.echo(click.style('ATTENTION!', blink=True))
  391. click.echo(click.style('Some things', reverse=True, fg='cyan'))
  392. Supported color names:
  393. * ``black`` (might be a gray)
  394. * ``red``
  395. * ``green``
  396. * ``yellow`` (might be an orange)
  397. * ``blue``
  398. * ``magenta``
  399. * ``cyan``
  400. * ``white`` (might be light gray)
  401. * ``bright_black``
  402. * ``bright_red``
  403. * ``bright_green``
  404. * ``bright_yellow``
  405. * ``bright_blue``
  406. * ``bright_magenta``
  407. * ``bright_cyan``
  408. * ``bright_white``
  409. * ``reset`` (reset the color code only)
  410. .. versionadded:: 2.0
  411. .. versionadded:: 7.0
  412. Added support for bright colors.
  413. :param text: the string to style with ansi codes.
  414. :param fg: if provided this will become the foreground color.
  415. :param bg: if provided this will become the background color.
  416. :param bold: if provided this will enable or disable bold mode.
  417. :param dim: if provided this will enable or disable dim mode. This is
  418. badly supported.
  419. :param underline: if provided this will enable or disable underline.
  420. :param blink: if provided this will enable or disable blinking.
  421. :param reverse: if provided this will enable or disable inverse
  422. rendering (foreground becomes background and the
  423. other way round).
  424. :param reset: by default a reset-all code is added at the end of the
  425. string which means that styles do not carry over. This
  426. can be disabled to compose styles.
  427. """
  428. bits = []
  429. if fg:
  430. try:
  431. bits.append("\033[{}m".format(_ansi_colors[fg]))
  432. except KeyError:
  433. raise TypeError("Unknown color '{}'".format(fg))
  434. if bg:
  435. try:
  436. bits.append("\033[{}m".format(_ansi_colors[bg] + 10))
  437. except KeyError:
  438. raise TypeError("Unknown color '{}'".format(bg))
  439. if bold is not None:
  440. bits.append("\033[{}m".format(1 if bold else 22))
  441. if dim is not None:
  442. bits.append("\033[{}m".format(2 if dim else 22))
  443. if underline is not None:
  444. bits.append("\033[{}m".format(4 if underline else 24))
  445. if blink is not None:
  446. bits.append("\033[{}m".format(5 if blink else 25))
  447. if reverse is not None:
  448. bits.append("\033[{}m".format(7 if reverse else 27))
  449. bits.append(text)
  450. if reset:
  451. bits.append(_ansi_reset_all)
  452. return "".join(bits)
  453. def unstyle(text):
  454. """Removes ANSI styling information from a string. Usually it's not
  455. necessary to use this function as Click's echo function will
  456. automatically remove styling if necessary.
  457. .. versionadded:: 2.0
  458. :param text: the text to remove style information from.
  459. """
  460. return strip_ansi(text)
  461. def secho(message=None, file=None, nl=True, err=False, color=None, **styles):
  462. """This function combines :func:`echo` and :func:`style` into one
  463. call. As such the following two calls are the same::
  464. click.secho('Hello World!', fg='green')
  465. click.echo(click.style('Hello World!', fg='green'))
  466. All keyword arguments are forwarded to the underlying functions
  467. depending on which one they go with.
  468. .. versionadded:: 2.0
  469. """
  470. if message is not None:
  471. message = style(message, **styles)
  472. return echo(message, file=file, nl=nl, err=err, color=color)
  473. def edit(
  474. text=None, editor=None, env=None, require_save=True, extension=".txt", filename=None
  475. ):
  476. r"""Edits the given text in the defined editor. If an editor is given
  477. (should be the full path to the executable but the regular operating
  478. system search path is used for finding the executable) it overrides
  479. the detected editor. Optionally, some environment variables can be
  480. used. If the editor is closed without changes, `None` is returned. In
  481. case a file is edited directly the return value is always `None` and
  482. `require_save` and `extension` are ignored.
  483. If the editor cannot be opened a :exc:`UsageError` is raised.
  484. Note for Windows: to simplify cross-platform usage, the newlines are
  485. automatically converted from POSIX to Windows and vice versa. As such,
  486. the message here will have ``\n`` as newline markers.
  487. :param text: the text to edit.
  488. :param editor: optionally the editor to use. Defaults to automatic
  489. detection.
  490. :param env: environment variables to forward to the editor.
  491. :param require_save: if this is true, then not saving in the editor
  492. will make the return value become `None`.
  493. :param extension: the extension to tell the editor about. This defaults
  494. to `.txt` but changing this might change syntax
  495. highlighting.
  496. :param filename: if provided it will edit this file instead of the
  497. provided text contents. It will not use a temporary
  498. file as an indirection in that case.
  499. """
  500. from ._termui_impl import Editor
  501. editor = Editor(
  502. editor=editor, env=env, require_save=require_save, extension=extension
  503. )
  504. if filename is None:
  505. return editor.edit(text)
  506. editor.edit_file(filename)
  507. def launch(url, wait=False, locate=False):
  508. """This function launches the given URL (or filename) in the default
  509. viewer application for this file type. If this is an executable, it
  510. might launch the executable in a new session. The return value is
  511. the exit code of the launched application. Usually, ``0`` indicates
  512. success.
  513. Examples::
  514. click.launch('https://click.palletsprojects.com/')
  515. click.launch('/my/downloaded/file', locate=True)
  516. .. versionadded:: 2.0
  517. :param url: URL or filename of the thing to launch.
  518. :param wait: waits for the program to stop.
  519. :param locate: if this is set to `True` then instead of launching the
  520. application associated with the URL it will attempt to
  521. launch a file manager with the file located. This
  522. might have weird effects if the URL does not point to
  523. the filesystem.
  524. """
  525. from ._termui_impl import open_url
  526. return open_url(url, wait=wait, locate=locate)
  527. # If this is provided, getchar() calls into this instead. This is used
  528. # for unittesting purposes.
  529. _getchar = None
  530. def getchar(echo=False):
  531. """Fetches a single character from the terminal and returns it. This
  532. will always return a unicode character and under certain rare
  533. circumstances this might return more than one character. The
  534. situations which more than one character is returned is when for
  535. whatever reason multiple characters end up in the terminal buffer or
  536. standard input was not actually a terminal.
  537. Note that this will always read from the terminal, even if something
  538. is piped into the standard input.
  539. Note for Windows: in rare cases when typing non-ASCII characters, this
  540. function might wait for a second character and then return both at once.
  541. This is because certain Unicode characters look like special-key markers.
  542. .. versionadded:: 2.0
  543. :param echo: if set to `True`, the character read will also show up on
  544. the terminal. The default is to not show it.
  545. """
  546. f = _getchar
  547. if f is None:
  548. from ._termui_impl import getchar as f
  549. return f(echo)
  550. def raw_terminal():
  551. from ._termui_impl import raw_terminal as f
  552. return f()
  553. def pause(info="Press any key to continue ...", err=False):
  554. """This command stops execution and waits for the user to press any
  555. key to continue. This is similar to the Windows batch "pause"
  556. command. If the program is not run through a terminal, this command
  557. will instead do nothing.
  558. .. versionadded:: 2.0
  559. .. versionadded:: 4.0
  560. Added the `err` parameter.
  561. :param info: the info string to print before pausing.
  562. :param err: if set to message goes to ``stderr`` instead of
  563. ``stdout``, the same as with echo.
  564. """
  565. if not isatty(sys.stdin) or not isatty(sys.stdout):
  566. return
  567. try:
  568. if info:
  569. echo(info, nl=False, err=err)
  570. try:
  571. getchar()
  572. except (KeyboardInterrupt, EOFError):
  573. pass
  574. finally:
  575. if info:
  576. echo(err=err)