682 lines
23 KiB
Python
682 lines
23 KiB
Python
|
import inspect
|
||
|
|
import io
|
||
|
|
import itertools
|
||
|
|
import os
|
||
|
|
import struct
|
||
|
|
import sys
|
||
|
|
|
||
|
|
from ._compat import DEFAULT_COLUMNS
|
||
|
|
from ._compat import get_winterm_size
|
||
|
|
from ._compat import isatty
|
||
|
|
from ._compat import raw_input
|
||
|
|
from ._compat import string_types
|
||
|
|
from ._compat import strip_ansi
|
||
|
|
from ._compat import text_type
|
||
|
|
from ._compat import WIN
|
||
|
|
from .exceptions import Abort
|
||
|
|
from .exceptions import UsageError
|
||
|
|
from .globals import resolve_color_default
|
||
|
|
from .types import Choice
|
||
|
|
from .types import convert_type
|
||
|
|
from .types import Path
|
||
|
|
from .utils import echo
|
||
|
|
from .utils import LazyFile
|
||
|
|
|
||
|
|
# The prompt functions to use. The doc tools currently override these
|
||
|
|
# functions to customize how they work.
|
||
|
|
visible_prompt_func = raw_input
|
||
|
|
|
||
|
|
_ansi_colors = {
|
||
|
|
"black": 30,
|
||
|
|
"red": 31,
|
||
|
|
"green": 32,
|
||
|
|
"yellow": 33,
|
||
|
|
"blue": 34,
|
||
|
|
"magenta": 35,
|
||
|
|
"cyan": 36,
|
||
|
|
"white": 37,
|
||
|
|
"reset": 39,
|
||
|
|
"bright_black": 90,
|
||
|
|
"bright_red": 91,
|
||
|
|
"bright_green": 92,
|
||
|
|
"bright_yellow": 93,
|
||
|
|
"bright_blue": 94,
|
||
|
|
"bright_magenta": 95,
|
||
|
|
"bright_cyan": 96,
|
||
|
|
"bright_white": 97,
|
||
|
|
}
|
||
|
|
_ansi_reset_all = "\033[0m"
|
||
|
|
|
||
|
|
|
||
|
|
def hidden_prompt_func(prompt):
|
||
|
|
import getpass
|
||
|
|
|
||
|
|
return getpass.getpass(prompt)
|
||
|
|
|
||
|
|
|
||
|
|
def _build_prompt(
|
||
|
|
text, suffix, show_default=False, default=None, show_choices=True, type=None
|
||
|
|
):
|
||
|
|
prompt = text
|
||
|
|
if type is not None and show_choices and isinstance(type, Choice):
|
||
|
|
prompt += " ({})".format(", ".join(map(str, type.choices)))
|
||
|
|
if default is not None and show_default:
|
||
|
|
prompt = "{} [{}]".format(prompt, _format_default(default))
|
||
|
|
return prompt + suffix
|
||
|
|
|
||
|
|
|
||
|
|
def _format_default(default):
|
||
|
|
if isinstance(default, (io.IOBase, LazyFile)) and hasattr(default, "name"):
|
||
|
|
return default.name
|
||
|
|
|
||
|
|
return default
|
||
|
|
|
||
|
|
|
||
|
|
def prompt(
|
||
|
|
text,
|
||
|
|
default=None,
|
||
|
|
hide_input=False,
|
||
|
|
confirmation_prompt=False,
|
||
|
|
type=None,
|
||
|
|
value_proc=None,
|
||
|
|
prompt_suffix=": ",
|
||
|
|
show_default=True,
|
||
|
|
err=False,
|
||
|
|
show_choices=True,
|
||
|
|
):
|
||
|
|
"""Prompts a user for input. This is a convenience function that can
|
||
|
|
be used to prompt a user for input later.
|
||
|
|
|
||
|
|
If the user aborts the input by sending a interrupt signal, this
|
||
|
|
function will catch it and raise a :exc:`Abort` exception.
|
||
|
|
|
||
|
|
.. versionadded:: 7.0
|
||
|
|
Added the show_choices parameter.
|
||
|
|
|
||
|
|
.. versionadded:: 6.0
|
||
|
|
Added unicode support for cmd.exe on Windows.
|
||
|
|
|
||
|
|
.. versionadded:: 4.0
|
||
|
|
Added the `err` parameter.
|
||
|
|
|
||
|
|
:param text: the text to show for the prompt.
|
||
|
|
:param default: the default value to use if no input happens. If this
|
||
|
|
is not given it will prompt until it's aborted.
|
||
|
|
:param hide_input: if this is set to true then the input value will
|
||
|
|
be hidden.
|
||
|
|
:param confirmation_prompt: asks for confirmation for the value.
|
||
|
|
:param type: the type to use to check the value against.
|
||
|
|
:param value_proc: if this parameter is provided it's a function that
|
||
|
|
is invoked instead of the type conversion to
|
||
|
|
convert a value.
|
||
|
|
:param prompt_suffix: a suffix that should be added to the prompt.
|
||
|
|
:param show_default: shows or hides the default value in the prompt.
|
||
|
|
:param err: if set to true the file defaults to ``stderr`` instead of
|
||
|
|
``stdout``, the same as with echo.
|
||
|
|
:param show_choices: Show or hide choices if the passed type is a Choice.
|
||
|
|
For example if type is a Choice of either day or week,
|
||
|
|
show_choices is true and text is "Group by" then the
|
||
|
|
prompt will be "Group by (day, week): ".
|
||
|
|
"""
|
||
|
|
result = None
|
||
|
|
|
||
|
|
def prompt_func(text):
|
||
|
|
f = hidden_prompt_func if hide_input else visible_prompt_func
|
||
|
|
try:
|
||
|
|
# Write the prompt separately so that we get nice
|
||
|
|
# coloring through colorama on Windows
|
||
|
|
echo(text, nl=False, err=err)
|
||
|
|
return f("")
|
||
|
|
except (KeyboardInterrupt, EOFError):
|
||
|
|
# getpass doesn't print a newline if the user aborts input with ^C.
|
||
|
|
# Allegedly this behavior is inherited from getpass(3).
|
||
|
|
# A doc bug has been filed at https://bugs.python.org/issue24711
|
||
|
|
if hide_input:
|
||
|
|
echo(None, err=err)
|
||
|
|
raise Abort()
|
||
|
|
|
||
|
|
if value_proc is None:
|
||
|
|
value_proc = convert_type(type, default)
|
||
|
|
|
||
|
|
prompt = _build_prompt(
|
||
|
|
text, prompt_suffix, show_default, default, show_choices, type
|
||
|
|
)
|
||
|
|
|
||
|
|
while 1:
|
||
|
|
while 1:
|
||
|
|
value = prompt_func(prompt)
|
||
|
|
if value:
|
||
|
|
break
|
||
|
|
elif default is not None:
|
||
|
|
if isinstance(value_proc, Path):
|
||
|
|
# validate Path default value(exists, dir_okay etc.)
|
||
|
|
value = default
|
||
|
|
break
|
||
|
|
return default
|
||
|
|
try:
|
||
|
|
result = value_proc(value)
|
||
|
|
except UsageError as e:
|
||
|
|
echo("Error: {}".format(e.message), err=err) # noqa: B306
|
||
|
|
continue
|
||
|
|
if not confirmation_prompt:
|
||
|
|
return result
|
||
|
|
while 1:
|
||
|
|
value2 = prompt_func("Repeat for confirmation: ")
|
||
|
|
if value2:
|
||
|
|
break
|
||
|
|
if value == value2:
|
||
|
|
return result
|
||
|
|
echo("Error: the two entered values do not match", err=err)
|
||
|
|
|
||
|
|
|
||
|
|
def confirm(
|
||
|
|
text, default=False, abort=False, prompt_suffix=": ", show_default=True, err=False
|
||
|
|
):
|
||
|
|
"""Prompts for confirmation (yes/no question).
|
||
|
|
|
||
|
|
If the user aborts the input by sending a interrupt signal this
|
||
|
|
function will catch it and raise a :exc:`Abort` exception.
|
||
|
|
|
||
|
|
.. versionadded:: 4.0
|
||
|
|
Added the `err` parameter.
|
||
|
|
|
||
|
|
:param text: the question to ask.
|
||
|
|
:param default: the default for the prompt.
|
||
|
|
:param abort: if this is set to `True` a negative answer aborts the
|
||
|
|
exception by raising :exc:`Abort`.
|
||
|
|
:param prompt_suffix: a suffix that should be added to the prompt.
|
||
|
|
:param show_default: shows or hides the default value in the prompt.
|
||
|
|
:param err: if set to true the file defaults to ``stderr`` instead of
|
||
|
|
``stdout``, the same as with echo.
|
||
|
|
"""
|
||
|
|
prompt = _build_prompt(
|
||
|
|
text, prompt_suffix, show_default, "Y/n" if default else "y/N"
|
||
|
|
)
|
||
|
|
while 1:
|
||
|
|
try:
|
||
|
|
# Write the prompt separately so that we get nice
|
||
|
|
# coloring through colorama on Windows
|
||
|
|
echo(prompt, nl=False, err=err)
|
||
|
|
value = visible_prompt_func("").lower().strip()
|
||
|
|
except (KeyboardInterrupt, EOFError):
|
||
|
|
raise Abort()
|
||
|
|
if value in ("y", "yes"):
|
||
|
|
rv = True
|
||
|
|
elif value in ("n", "no"):
|
||
|
|
rv = False
|
||
|
|
elif value == "":
|
||
|
|
rv = default
|
||
|
|
else:
|
||
|
|
echo("Error: invalid input", err=err)
|
||
|
|
continue
|
||
|
|
break
|
||
|
|
if abort and not rv:
|
||
|
|
raise Abort()
|
||
|
|
return rv
|
||
|
|
|
||
|
|
|
||
|
|
def get_terminal_size():
|
||
|
|
"""Returns the current size of the terminal as tuple in the form
|
||
|
|
``(width, height)`` in columns and rows.
|
||
|
|
"""
|
||
|
|
# If shutil has get_terminal_size() (Python 3.3 and later) use that
|
||
|
|
if sys.version_info >= (3, 3):
|
||
|
|
import shutil
|
||
|
|
|
||
|
|
shutil_get_terminal_size = getattr(shutil, "get_terminal_size", None)
|
||
|
|
if shutil_get_terminal_size:
|
||
|
|
sz = shutil_get_terminal_size()
|
||
|
|
return sz.columns, sz.lines
|
||
|
|
|
||
|
|
# We provide a sensible default for get_winterm_size() when being invoked
|
||
|
|
# inside a subprocess. Without this, it would not provide a useful input.
|
||
|
|
if get_winterm_size is not None:
|
||
|
|
size = get_winterm_size()
|
||
|
|
if size == (0, 0):
|
||
|
|
return (79, 24)
|
||
|
|
else:
|
||
|
|
return size
|
||
|
|
|
||
|
|
def ioctl_gwinsz(fd):
|
||
|
|
try:
|
||
|
|
import fcntl
|
||
|
|
import termios
|
||
|
|
|
||
|
|
cr = struct.unpack("hh", fcntl.ioctl(fd, termios.TIOCGWINSZ, "1234"))
|
||
|
|
except Exception:
|
||
|
|
return
|
||
|
|
return cr
|
||
|
|
|
||
|
|
cr = ioctl_gwinsz(0) or ioctl_gwinsz(1) or ioctl_gwinsz(2)
|
||
|
|
if not cr:
|
||
|
|
try:
|
||
|
|
fd = os.open(os.ctermid(), os.O_RDONLY)
|
||
|
|
try:
|
||
|
|
cr = ioctl_gwinsz(fd)
|
||
|
|
finally:
|
||
|
|
os.close(fd)
|
||
|
|
except Exception:
|
||
|
|
pass
|
||
|
|
if not cr or not cr[0] or not cr[1]:
|
||
|
|
cr = (os.environ.get("LINES", 25), os.environ.get("COLUMNS", DEFAULT_COLUMNS))
|
||
|
|
return int(cr[1]), int(cr[0])
|
||
|
|
|
||
|
|
|
||
|
|
def echo_via_pager(text_or_generator, color=None):
|
||
|
|
"""This function takes a text and shows it via an environment specific
|
||
|
|
pager on stdout.
|
||
|
|
|
||
|
|
.. versionchanged:: 3.0
|
||
|
|
Added the `color` flag.
|
||
|
|
|
||
|
|
:param text_or_generator: the text to page, or alternatively, a
|
||
|
|
generator emitting the text to page.
|
||
|
|
:param color: controls if the pager supports ANSI colors or not. The
|
||
|
|
default is autodetection.
|
||
|
|
"""
|
||
|
|
color = resolve_color_default(color)
|
||
|
|
|
||
|
|
if inspect.isgeneratorfunction(text_or_generator):
|
||
|
|
i = text_or_generator()
|
||
|
|
elif isinstance(text_or_generator, string_types):
|
||
|
|
i = [text_or_generator]
|
||
|
|
else:
|
||
|
|
i = iter(text_or_generator)
|
||
|
|
|
||
|
|
# convert every element of i to a text type if necessary
|
||
|
|
text_generator = (el if isinstance(el, string_types) else text_type(el) for el in i)
|
||
|
|
|
||
|
|
from ._termui_impl import pager
|
||
|
|
|
||
|
|
return pager(itertools.chain(text_generator, "\n"), color)
|
||
|
|
|
||
|
|
|
||
|
|
def progressbar(
|
||
|
|
iterable=None,
|
||
|
|
length=None,
|
||
|
|
label=None,
|
||
|
|
show_eta=True,
|
||
|
|
show_percent=None,
|
||
|
|
show_pos=False,
|
||
|
|
item_show_func=None,
|
||
|
|
fill_char="#",
|
||
|
|
empty_char="-",
|
||
|
|
bar_template="%(label)s [%(bar)s] %(info)s",
|
||
|
|
info_sep=" ",
|
||
|
|
width=36,
|
||
|
|
file=None,
|
||
|
|
color=None,
|
||
|
|
):
|
||
|
|
"""This function creates an iterable context manager that can be used
|
||
|
|
to iterate over something while showing a progress bar. It will
|
||
|
|
either iterate over the `iterable` or `length` items (that are counted
|
||
|
|
up). While iteration happens, this function will print a rendered
|
||
|
|
progress bar to the given `file` (defaults to stdout) and will attempt
|
||
|
|
to calculate remaining time and more. By default, this progress bar
|
||
|
|
will not be rendered if the file is not a terminal.
|
||
|
|
|
||
|
|
The context manager creates the progress bar. When the context
|
||
|
|
manager is entered the progress bar is already created. With every
|
||
|
|
iteration over the progress bar, the iterable passed to the bar is
|
||
|
|
advanced and the bar is updated. When the context manager exits,
|
||
|
|
a newline is printed and the progress bar is finalized on screen.
|
||
|
|
|
||
|
|
Note: The progress bar is currently designed for use cases where the
|
||
|
|
total progress can be expected to take at least several seconds.
|
||
|
|
Because of this, the ProgressBar class object won't display
|
||
|
|
progress that is considered too fast, and progress where the time
|
||
|
|
between steps is less than a second.
|
||
|
|
|
||
|
|
No printing must happen or the progress bar will be unintentionally
|
||
|
|
destroyed.
|
||
|
|
|
||
|
|
Example usage::
|
||
|
|
|
||
|
|
with progressbar(items) as bar:
|
||
|
|
for item in bar:
|
||
|
|
do_something_with(item)
|
||
|
|
|
||
|
|
Alternatively, if no iterable is specified, one can manually update the
|
||
|
|
progress bar through the `update()` method instead of directly
|
||
|
|
iterating over the progress bar. The update method accepts the number
|
||
|
|
of steps to increment the bar with::
|
||
|
|
|
||
|
|
with progressbar(length=chunks.total_bytes) as bar:
|
||
|
|
for chunk in chunks:
|
||
|
|
process_chunk(chunk)
|
||
|
|
bar.update(chunks.bytes)
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
|
||
|
|
.. versionadded:: 4.0
|
||
|
|
Added the `color` parameter. Added a `update` method to the
|
||
|
|
progressbar object.
|
||
|
|
|
||
|
|
:param iterable: an iterable to iterate over. If not provided the length
|
||
|
|
is required.
|
||
|
|
:param length: the number of items to iterate over. By default the
|
||
|
|
progressbar will attempt to ask the iterator about its
|
||
|
|
length, which might or might not work. If an iterable is
|
||
|
|
also provided this parameter can be used to override the
|
||
|
|
length. If an iterable is not provided the progress bar
|
||
|
|
will iterate over a range of that length.
|
||
|
|
:param label: the label to show next to the progress bar.
|
||
|
|
:param show_eta: enables or disables the estimated time display. This is
|
||
|
|
automatically disabled if the length cannot be
|
||
|
|
determined.
|
||
|
|
:param show_percent: enables or disables the percentage display. The
|
||
|
|
default is `True` if the iterable has a length or
|
||
|
|
`False` if not.
|
||
|
|
:param show_pos: enables or disables the absolute position display. The
|
||
|
|
default is `False`.
|
||
|
|
:param item_show_func: a function called with the current item which
|
||
|
|
can return a string to show the current item
|
||
|
|
next to the progress bar. Note that the current
|
||
|
|
item can be `None`!
|
||
|
|
:param fill_char: the character to use to show the filled part of the
|
||
|
|
progress bar.
|
||
|
|
:param empty_char: the character to use to show the non-filled part of
|
||
|
|
the progress bar.
|
||
|
|
:param bar_template: the format string to use as template for the bar.
|
||
|
|
The parameters in it are ``label`` for the label,
|
||
|
|
``bar`` for the progress bar and ``info`` for the
|
||
|
|
info section.
|
||
|
|
:param info_sep: the separator between multiple info items (eta etc.)
|
||
|
|
:param width: the width of the progress bar in characters, 0 means full
|
||
|
|
terminal width
|
||
|
|
:param file: the file to write to. If this is not a terminal then
|
||
|
|
only the label is printed.
|
||
|
|
:param color: controls if the terminal supports ANSI colors or not. The
|
||
|
|
default is autodetection. This is only needed if ANSI
|
||
|
|
codes are included anywhere in the progress bar output
|
||
|
|
which is not the case by default.
|
||
|
|
"""
|
||
|
|
from ._termui_impl import ProgressBar
|
||
|
|
|
||
|
|
color = resolve_color_default(color)
|
||
|
|
return ProgressBar(
|
||
|
|
iterable=iterable,
|
||
|
|
length=length,
|
||
|
|
show_eta=show_eta,
|
||
|
|
show_percent=show_percent,
|
||
|
|
show_pos=show_pos,
|
||
|
|
item_show_func=item_show_func,
|
||
|
|
fill_char=fill_char,
|
||
|
|
empty_char=empty_char,
|
||
|
|
bar_template=bar_template,
|
||
|
|
info_sep=info_sep,
|
||
|
|
file=file,
|
||
|
|
label=label,
|
||
|
|
width=width,
|
||
|
|
color=color,
|
||
|
|
)
|
||
|
|
|
||
|
|
|
||
|
|
def clear():
|
||
|
|
"""Clears the terminal screen. This will have the effect of clearing
|
||
|
|
the whole visible space of the terminal and moving the cursor to the
|
||
|
|
top left. This does not do anything if not connected to a terminal.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
"""
|
||
|
|
if not isatty(sys.stdout):
|
||
|
|
return
|
||
|
|
# If we're on Windows and we don't have colorama available, then we
|
||
|
|
# clear the screen by shelling out. Otherwise we can use an escape
|
||
|
|
# sequence.
|
||
|
|
if WIN:
|
||
|
|
os.system("cls")
|
||
|
|
else:
|
||
|
|
sys.stdout.write("\033[2J\033[1;1H")
|
||
|
|
|
||
|
|
|
||
|
|
def style(
|
||
|
|
text,
|
||
|
|
fg=None,
|
||
|
|
bg=None,
|
||
|
|
bold=None,
|
||
|
|
dim=None,
|
||
|
|
underline=None,
|
||
|
|
blink=None,
|
||
|
|
reverse=None,
|
||
|
|
reset=True,
|
||
|
|
):
|
||
|
|
"""Styles a text with ANSI styles and returns the new string. By
|
||
|
|
default the styling is self contained which means that at the end
|
||
|
|
of the string a reset code is issued. This can be prevented by
|
||
|
|
passing ``reset=False``.
|
||
|
|
|
||
|
|
Examples::
|
||
|
|
|
||
|
|
click.echo(click.style('Hello World!', fg='green'))
|
||
|
|
click.echo(click.style('ATTENTION!', blink=True))
|
||
|
|
click.echo(click.style('Some things', reverse=True, fg='cyan'))
|
||
|
|
|
||
|
|
Supported color names:
|
||
|
|
|
||
|
|
* ``black`` (might be a gray)
|
||
|
|
* ``red``
|
||
|
|
* ``green``
|
||
|
|
* ``yellow`` (might be an orange)
|
||
|
|
* ``blue``
|
||
|
|
* ``magenta``
|
||
|
|
* ``cyan``
|
||
|
|
* ``white`` (might be light gray)
|
||
|
|
* ``bright_black``
|
||
|
|
* ``bright_red``
|
||
|
|
* ``bright_green``
|
||
|
|
* ``bright_yellow``
|
||
|
|
* ``bright_blue``
|
||
|
|
* ``bright_magenta``
|
||
|
|
* ``bright_cyan``
|
||
|
|
* ``bright_white``
|
||
|
|
* ``reset`` (reset the color code only)
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
|
||
|
|
.. versionadded:: 7.0
|
||
|
|
Added support for bright colors.
|
||
|
|
|
||
|
|
:param text: the string to style with ansi codes.
|
||
|
|
:param fg: if provided this will become the foreground color.
|
||
|
|
:param bg: if provided this will become the background color.
|
||
|
|
:param bold: if provided this will enable or disable bold mode.
|
||
|
|
:param dim: if provided this will enable or disable dim mode. This is
|
||
|
|
badly supported.
|
||
|
|
:param underline: if provided this will enable or disable underline.
|
||
|
|
:param blink: if provided this will enable or disable blinking.
|
||
|
|
:param reverse: if provided this will enable or disable inverse
|
||
|
|
rendering (foreground becomes background and the
|
||
|
|
other way round).
|
||
|
|
:param reset: by default a reset-all code is added at the end of the
|
||
|
|
string which means that styles do not carry over. This
|
||
|
|
can be disabled to compose styles.
|
||
|
|
"""
|
||
|
|
bits = []
|
||
|
|
if fg:
|
||
|
|
try:
|
||
|
|
bits.append("\033[{}m".format(_ansi_colors[fg]))
|
||
|
|
except KeyError:
|
||
|
|
raise TypeError("Unknown color '{}'".format(fg))
|
||
|
|
if bg:
|
||
|
|
try:
|
||
|
|
bits.append("\033[{}m".format(_ansi_colors[bg] + 10))
|
||
|
|
except KeyError:
|
||
|
|
raise TypeError("Unknown color '{}'".format(bg))
|
||
|
|
if bold is not None:
|
||
|
|
bits.append("\033[{}m".format(1 if bold else 22))
|
||
|
|
if dim is not None:
|
||
|
|
bits.append("\033[{}m".format(2 if dim else 22))
|
||
|
|
if underline is not None:
|
||
|
|
bits.append("\033[{}m".format(4 if underline else 24))
|
||
|
|
if blink is not None:
|
||
|
|
bits.append("\033[{}m".format(5 if blink else 25))
|
||
|
|
if reverse is not None:
|
||
|
|
bits.append("\033[{}m".format(7 if reverse else 27))
|
||
|
|
bits.append(text)
|
||
|
|
if reset:
|
||
|
|
bits.append(_ansi_reset_all)
|
||
|
|
return "".join(bits)
|
||
|
|
|
||
|
|
|
||
|
|
def unstyle(text):
|
||
|
|
"""Removes ANSI styling information from a string. Usually it's not
|
||
|
|
necessary to use this function as Click's echo function will
|
||
|
|
automatically remove styling if necessary.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
|
||
|
|
:param text: the text to remove style information from.
|
||
|
|
"""
|
||
|
|
return strip_ansi(text)
|
||
|
|
|
||
|
|
|
||
|
|
def secho(message=None, file=None, nl=True, err=False, color=None, **styles):
|
||
|
|
"""This function combines :func:`echo` and :func:`style` into one
|
||
|
|
call. As such the following two calls are the same::
|
||
|
|
|
||
|
|
click.secho('Hello World!', fg='green')
|
||
|
|
click.echo(click.style('Hello World!', fg='green'))
|
||
|
|
|
||
|
|
All keyword arguments are forwarded to the underlying functions
|
||
|
|
depending on which one they go with.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
"""
|
||
|
|
if message is not None:
|
||
|
|
message = style(message, **styles)
|
||
|
|
return echo(message, file=file, nl=nl, err=err, color=color)
|
||
|
|
|
||
|
|
|
||
|
|
def edit(
|
||
|
|
text=None, editor=None, env=None, require_save=True, extension=".txt", filename=None
|
||
|
|
):
|
||
|
|
r"""Edits the given text in the defined editor. If an editor is given
|
||
|
|
(should be the full path to the executable but the regular operating
|
||
|
|
system search path is used for finding the executable) it overrides
|
||
|
|
the detected editor. Optionally, some environment variables can be
|
||
|
|
used. If the editor is closed without changes, `None` is returned. In
|
||
|
|
case a file is edited directly the return value is always `None` and
|
||
|
|
`require_save` and `extension` are ignored.
|
||
|
|
|
||
|
|
If the editor cannot be opened a :exc:`UsageError` is raised.
|
||
|
|
|
||
|
|
Note for Windows: to simplify cross-platform usage, the newlines are
|
||
|
|
automatically converted from POSIX to Windows and vice versa. As such,
|
||
|
|
the message here will have ``\n`` as newline markers.
|
||
|
|
|
||
|
|
:param text: the text to edit.
|
||
|
|
:param editor: optionally the editor to use. Defaults to automatic
|
||
|
|
detection.
|
||
|
|
:param env: environment variables to forward to the editor.
|
||
|
|
:param require_save: if this is true, then not saving in the editor
|
||
|
|
will make the return value become `None`.
|
||
|
|
:param extension: the extension to tell the editor about. This defaults
|
||
|
|
to `.txt` but changing this might change syntax
|
||
|
|
highlighting.
|
||
|
|
:param filename: if provided it will edit this file instead of the
|
||
|
|
provided text contents. It will not use a temporary
|
||
|
|
file as an indirection in that case.
|
||
|
|
"""
|
||
|
|
from ._termui_impl import Editor
|
||
|
|
|
||
|
|
editor = Editor(
|
||
|
|
editor=editor, env=env, require_save=require_save, extension=extension
|
||
|
|
)
|
||
|
|
if filename is None:
|
||
|
|
return editor.edit(text)
|
||
|
|
editor.edit_file(filename)
|
||
|
|
|
||
|
|
|
||
|
|
def launch(url, wait=False, locate=False):
|
||
|
|
"""This function launches the given URL (or filename) in the default
|
||
|
|
viewer application for this file type. If this is an executable, it
|
||
|
|
might launch the executable in a new session. The return value is
|
||
|
|
the exit code of the launched application. Usually, ``0`` indicates
|
||
|
|
success.
|
||
|
|
|
||
|
|
Examples::
|
||
|
|
|
||
|
|
click.launch('https://click.palletsprojects.com/')
|
||
|
|
click.launch('/my/downloaded/file', locate=True)
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
|
||
|
|
:param url: URL or filename of the thing to launch.
|
||
|
|
:param wait: waits for the program to stop.
|
||
|
|
:param locate: if this is set to `True` then instead of launching the
|
||
|
|
application associated with the URL it will attempt to
|
||
|
|
launch a file manager with the file located. This
|
||
|
|
might have weird effects if the URL does not point to
|
||
|
|
the filesystem.
|
||
|
|
"""
|
||
|
|
from ._termui_impl import open_url
|
||
|
|
|
||
|
|
return open_url(url, wait=wait, locate=locate)
|
||
|
|
|
||
|
|
|
||
|
|
# If this is provided, getchar() calls into this instead. This is used
|
||
|
|
# for unittesting purposes.
|
||
|
|
_getchar = None
|
||
|
|
|
||
|
|
|
||
|
|
def getchar(echo=False):
|
||
|
|
"""Fetches a single character from the terminal and returns it. This
|
||
|
|
will always return a unicode character and under certain rare
|
||
|
|
circumstances this might return more than one character. The
|
||
|
|
situations which more than one character is returned is when for
|
||
|
|
whatever reason multiple characters end up in the terminal buffer or
|
||
|
|
standard input was not actually a terminal.
|
||
|
|
|
||
|
|
Note that this will always read from the terminal, even if something
|
||
|
|
is piped into the standard input.
|
||
|
|
|
||
|
|
Note for Windows: in rare cases when typing non-ASCII characters, this
|
||
|
|
function might wait for a second character and then return both at once.
|
||
|
|
This is because certain Unicode characters look like special-key markers.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
|
||
|
|
:param echo: if set to `True`, the character read will also show up on
|
||
|
|
the terminal. The default is to not show it.
|
||
|
|
"""
|
||
|
|
f = _getchar
|
||
|
|
if f is None:
|
||
|
|
from ._termui_impl import getchar as f
|
||
|
|
return f(echo)
|
||
|
|
|
||
|
|
|
||
|
|
def raw_terminal():
|
||
|
|
from ._termui_impl import raw_terminal as f
|
||
|
|
|
||
|
|
return f()
|
||
|
|
|
||
|
|
|
||
|
|
def pause(info="Press any key to continue ...", err=False):
|
||
|
|
"""This command stops execution and waits for the user to press any
|
||
|
|
key to continue. This is similar to the Windows batch "pause"
|
||
|
|
command. If the program is not run through a terminal, this command
|
||
|
|
will instead do nothing.
|
||
|
|
|
||
|
|
.. versionadded:: 2.0
|
||
|
|
|
||
|
|
.. versionadded:: 4.0
|
||
|
|
Added the `err` parameter.
|
||
|
|
|
||
|
|
:param info: the info string to print before pausing.
|
||
|
|
:param err: if set to message goes to ``stderr`` instead of
|
||
|
|
``stdout``, the same as with echo.
|
||
|
|
"""
|
||
|
|
if not isatty(sys.stdin) or not isatty(sys.stdout):
|
||
|
|
return
|
||
|
|
try:
|
||
|
|
if info:
|
||
|
|
echo(info, nl=False, err=err)
|
||
|
|
try:
|
||
|
|
getchar()
|
||
|
|
except (KeyboardInterrupt, EOFError):
|
||
|
|
pass
|
||
|
|
finally:
|
||
|
|
if info:
|
||
|
|
echo(err=err)
|