def _output(self, text, color, *args, **kw):
self._erase_spinner()
if terminal_supports_colors(sys.stdout):
text = ansi_wrap(text, color=color)
auto_encode(sys.stdout, text, ind=_DETAIL_INDENT, *args, **kw)
sys.stdout.flush()
def _output(self, text, color, *args, **kw):
self._erase_spinner()
text = coerce_string(text)
if terminal_supports_colors(sys.stdout):
text = ansi_wrap(text, color=color)
auto_encode(sys.stdout, text, ind=_DETAIL_INDENT, *args, **kw)
sys.stdout.flush()
def _output(self, text, color, *args, **kw):
if self._need_to_erase_spinner:
if self._progress_spinner and self._progress_spinner.interactive:
sys.stdout.write(erase_line_code)
self._need_to_erase_spinner = False
text = coerce_string(text)
if terminal_supports_colors(sys.stdout):
text = ansi_wrap(text, color=color)
auto_encode(sys.stdout, text, ind=_DETAIL_INDENT, *args, **kw)
def highlight(text):
"""
Highlight a piece of text using ANSI escape sequences.
:param text: The text to highlight (a string).
:returns: The highlighted text (when standard output is connected to a
terminal) or the original text (when standard output is not
connected to a terminal).
"""
if terminal_supports_colors(sys.stdout):
text = ansi_wrap(text, color=HIGHLIGHT_COLOR)
return text
def highlight(text):
"""
Highlight a piece of text using ANSI escape sequences.
:param text: The text to highlight (a string).
:returns: The highlighted text (when standard output is connected to a
terminal) or the original text (when standard output is not
connected to a terminal).
"""
if terminal_supports_colors(sys.stdout):
text = ansi_wrap(text, color=HIGHLIGHT_COLOR)
return text
def prepare_prompt_text(prompt_text, **options):
"""
Wrap a text to be rendered as an interactive prompt in ANSI escape sequences.
:param prompt_text: The text to render on the prompt (a string).
:param options: Any keyword arguments are passed on to :func:`.ansi_wrap()`.
:returns: The resulting prompt text (a string).
ANSI escape sequences are only used when the standard output stream is
connected to a terminal. When the standard input stream is connected to a
terminal any escape sequences are wrapped in "readline hints".
"""
return (ansi_wrap(prompt_text, readline_hints=connected_to_terminal(sys.stdin), **options)
if terminal_supports_colors(sys.stdout)
else prompt_text)
def use_color():
use_colors = True
if use_colors or (use_colors is None):
# Respect the user's choice not to have colors.
if use_colors is None and 'NO_COLOR' in os.environ:
# For details on this see https://no-color.org/.
use_colors = False
# Try to enable Windows native ANSI support or Colorama?
if (use_colors or use_colors is None) and on_windows():
# This can fail, in which case ANSI escape sequences would end
# up being printed to the terminal in raw form. This is very
# user hostile, so to avoid this happening we disable color
# support on failure.
use_colors = enable_ansi_support()
# When auto detection is enabled, and so far we encountered no
# reason to disable color support, then we will enable color
# support if 'stream' is connected to a terminal.
if use_colors is None:
use_colors = terminal_supports_colors()
return use_colors
def install(level=None, **kw):
"""
Enable colored terminal output for Python's :mod:`logging` module.
:param level: The default logging level (an integer or a string with a
level name, defaults to :data:`logging.INFO`).
:param logger: The logger to which the stream handler should be attached (a
:class:`~logging.Logger` object, defaults to the root logger).
:param fmt: Set the logging format (a string like those accepted by
:class:`~logging.Formatter`, defaults to
:data:`DEFAULT_LOG_FORMAT`).
:param datefmt: Set the date/time format (a string, defaults to
:data:`DEFAULT_DATE_FORMAT`).
:param level_styles: A dictionary with custom level styles (defaults to
:data:`DEFAULT_LEVEL_STYLES`).
:param field_styles: A dictionary with custom field styles (defaults to
:data:`DEFAULT_FIELD_STYLES`).
:param stream: The stream where log messages should be written to (a
file-like object, defaults to :data:`sys.stderr`).
:param isatty: :data:`True` to use a :class:`ColoredFormatter`,
:data:`False` to use a normal :class:`~logging.Formatter`
(defaults to auto-detection using
:func:`~humanfriendly.terminal.terminal_supports_colors()`).
:param reconfigure: If :data:`True` (the default) multiple calls to
:func:`coloredlogs.install()` will each override
the previous configuration.
:param use_chroot: Refer to :class:`HostNameFilter`.
:param programname: Refer to :class:`ProgramNameFilter`.
:param syslog: If :data:`True` then :func:`~coloredlogs.syslog.enable_system_logging()`
will be called without arguments (defaults to :data:`False`).
The :func:`coloredlogs.install()` function is similar to
:func:`logging.basicConfig()`, both functions take a lot of optional
keyword arguments but try to do the right thing by default:
1. If `reconfigure` is :data:`True` (it is by default) and an existing
:class:`~logging.StreamHandler` is found that is connected to either
:data:`~sys.stdout` or :data:`~sys.stderr` the handler will be removed.
This means that first calling :func:`logging.basicConfig()` and then
calling :func:`coloredlogs.install()` will replace the stream handler
instead of adding a duplicate stream handler. If `reconfigure` is
:data:`False` and an existing handler is found no further steps are
taken (to avoid installing a duplicate stream handler).
2. A :class:`~logging.StreamHandler` is created and connected to the stream
given by the `stream` keyword argument (:data:`sys.stderr` by
default). The stream handler's level is set to the value of the `level`
keyword argument.
3. A :class:`ColoredFormatter` is created if the `isatty` keyword argument
allows it (or auto-detection allows it), otherwise a normal
:class:`~logging.Formatter` is created. The formatter is initialized
with the `fmt` and `datefmt` keyword arguments (or their computed
defaults).
4. :func:`HostNameFilter.install()` and :func:`ProgramNameFilter.install()`
are called to enable the use of additional fields in the log format.
5. The formatter is added to the handler and the handler is added to the
logger. The logger's level is set to :data:`logging.NOTSET` so that each
handler gets to decide which records they filter. This makes it possible
to have controllable verbosity on the terminal while logging at full
verbosity to the system log or a file.
"""
logger = kw.get('logger') or logging.getLogger()
reconfigure = kw.get('reconfigure', True)
stream = kw.get('stream', sys.stderr)
# Remove any existing stream handler that writes to stdout or stderr, even
# if the stream handler wasn't created by coloredlogs because multiple
# stream handlers (in the same hierarchy) writing to stdout or stderr would
# create duplicate output.
standard_streams = (sys.stdout, sys.stderr)
match_streams = standard_streams if stream in standard_streams else (
stream, )
match_handler = lambda handler: match_stream_handler(
handler, match_streams)
handler, logger = replace_handler(logger, match_handler, reconfigure)
# Make sure reconfiguration is allowed or not relevant.
if not (handler and not reconfigure):
# Make it easy to enable system logging.
if kw.get('syslog', False):
from coloredlogs import syslog
syslog.enable_system_logging()
# Figure out whether we can use ANSI escape sequences.
use_colors = kw.get('isatty', None)
if use_colors or use_colors is None:
if NEED_COLORAMA:
if HAVE_COLORAMA:
# On Windows we can only use ANSI escape
# sequences if Colorama is available.
colorama.init()
use_colors = True
else:
# If Colorama isn't available then we specifically
# shouldn't emit ANSI escape sequences!
use_colors = False
elif use_colors is None:
# Auto-detect terminal support on other platforms.
use_colors = terminal_supports_colors(stream)
# Create a stream handler.
handler = logging.StreamHandler(stream)
if level is None:
level = os.environ.get('COLOREDLOGS_LOG_LEVEL') or 'INFO'
handler.setLevel(level_to_number(level))
# Prepare the arguments to the formatter. The caller is
# allowed to customize `fmt' and/or `datefmt' as desired.
formatter_options = dict(fmt=kw.get('fmt'), datefmt=kw.get('datefmt'))
# Come up with a default log format?
if not formatter_options['fmt']:
# Use the log format defined by the environment variable
# $COLOREDLOGS_LOG_FORMAT or fall back to the default.
formatter_options['fmt'] = os.environ.get(
'COLOREDLOGS_LOG_FORMAT') or DEFAULT_LOG_FORMAT
# If the caller didn't specify a date/time format we'll use the format
# defined by the environment variable $COLOREDLOGS_DATE_FORMAT (or fall
# back to the default).
if not formatter_options['datefmt']:
formatter_options['datefmt'] = os.environ.get(
'COLOREDLOGS_DATE_FORMAT') or DEFAULT_DATE_FORMAT
# Do we need to make %(hostname) available to the formatter?
HostNameFilter.install(
handler=handler,
fmt=formatter_options['fmt'],
use_chroot=kw.get('use_chroot', True),
)
# Do we need to make %(programname) available to the formatter?
ProgramNameFilter.install(
handler=handler,
fmt=formatter_options['fmt'],
programname=kw.get('programname'),
)
# Inject additional formatter arguments specific to ColoredFormatter?
if use_colors:
for name, environment_name in (('field_styles',
'COLOREDLOGS_FIELD_STYLES'),
('level_styles',
'COLOREDLOGS_LEVEL_STYLES')):
value = kw.get(name)
if value is None:
# If no styles have been specified we'll fall back
# to the styles defined by the environment variable.
environment_value = os.environ.get(environment_name)
if environment_value is not None:
value = parse_encoded_styles(environment_value)
if value is not None:
formatter_options[name] = value
# Create a (possibly colored) formatter.
formatter_type = ColoredFormatter if use_colors else logging.Formatter
handler.setFormatter(formatter_type(**formatter_options))
# Install the stream handler.
logger.setLevel(logging.NOTSET)
logger.addHandler(handler)
def install(level=None, **kw):
"""
Enable colored terminal output for Python's :mod:`logging` module.
:param level: The default logging level (an integer or a string with a
level name, defaults to :data:`DEFAULT_LOG_LEVEL`).
:param logger: The logger to which the stream handler should be attached (a
:class:`~logging.Logger` object, defaults to the root logger).
:param fmt: Set the logging format (a string like those accepted by
:class:`~logging.Formatter`, defaults to
:data:`DEFAULT_LOG_FORMAT`).
:param datefmt: Set the date/time format (a string, defaults to
:data:`DEFAULT_DATE_FORMAT`).
:param level_styles: A dictionary with custom level styles (defaults to
:data:`DEFAULT_LEVEL_STYLES`).
:param field_styles: A dictionary with custom field styles (defaults to
:data:`DEFAULT_FIELD_STYLES`).
:param stream: The stream where log messages should be written to (a
file-like object). This defaults to :data:`None` which
means :class:`StandardErrorHandler` is used.
:param isatty: :data:`True` to use a :class:`ColoredFormatter`,
:data:`False` to use a normal :class:`~logging.Formatter`
(defaults to auto-detection using
:func:`~humanfriendly.terminal.terminal_supports_colors()`).
:param reconfigure: If :data:`True` (the default) multiple calls to
:func:`coloredlogs.install()` will each override
the previous configuration.
:param use_chroot: Refer to :class:`HostNameFilter`.
:param programname: Refer to :class:`ProgramNameFilter`.
:param syslog: If :data:`True` then :func:`.enable_system_logging()` will
be called without arguments (defaults to :data:`False`). The
`syslog` argument may also be a number or string, in this
case it is assumed to be a logging level which is passed on
to :func:`.enable_system_logging()`.
The :func:`coloredlogs.install()` function is similar to
:func:`logging.basicConfig()`, both functions take a lot of optional
keyword arguments but try to do the right thing by default:
1. If `reconfigure` is :data:`True` (it is by default) and an existing
:class:`~logging.StreamHandler` is found that is connected to either
:data:`~sys.stdout` or :data:`~sys.stderr` the handler will be removed.
This means that first calling :func:`logging.basicConfig()` and then
calling :func:`coloredlogs.install()` will replace the stream handler
instead of adding a duplicate stream handler. If `reconfigure` is
:data:`False` and an existing handler is found no further steps are
taken (to avoid installing a duplicate stream handler).
2. A :class:`~logging.StreamHandler` is created and connected to the stream
given by the `stream` keyword argument (:data:`sys.stderr` by
default). The stream handler's level is set to the value of the `level`
keyword argument.
3. A :class:`ColoredFormatter` is created if the `isatty` keyword argument
allows it (or auto-detection allows it), otherwise a normal
:class:`~logging.Formatter` is created. The formatter is initialized
with the `fmt` and `datefmt` keyword arguments (or their computed
defaults).
4. :func:`HostNameFilter.install()` and :func:`ProgramNameFilter.install()`
are called to enable the use of additional fields in the log format.
5. If the logger's level is too restrictive it is relaxed (refer to `notes
about log levels`_ for details).
6. The formatter is added to the handler and the handler is added to the
logger.
"""
logger = kw.get('logger') or logging.getLogger()
reconfigure = kw.get('reconfigure', True)
stream = kw.get('stream', None)
# Get the log level from an argument, environment variable or default and
# convert the names of log levels to numbers to enable numeric comparison.
if level is None:
level = os.environ.get('COLOREDLOGS_LOG_LEVEL', DEFAULT_LOG_LEVEL)
level = level_to_number(level)
# Remove any existing stream handler that writes to stdout or stderr, even
# if the stream handler wasn't created by coloredlogs because multiple
# stream handlers (in the same hierarchy) writing to stdout or stderr would
# create duplicate output. `None' is a synonym for the possibly dynamic
# value of the stderr attribute of the sys module.
match_streams = ([sys.stdout, sys.stderr]
if stream in [sys.stdout, sys.stderr, None] else [stream])
match_handler = lambda handler: match_stream_handler(
handler, match_streams)
handler, logger = replace_handler(logger, match_handler, reconfigure)
# Make sure reconfiguration is allowed or not relevant.
if not (handler and not reconfigure):
# Make it easy to enable system logging.
syslog_enabled = kw.get('syslog')
# We ignore the value `None' because it means the caller didn't opt in
# to system logging and `False' because it means the caller explicitly
# opted out of system logging.
#
# We never enable system logging on Windows because it is my impression
# that SysLogHandler isn't intended to be used on Windows; I've had
# reports of coloredlogs spewing extremely verbose errno 10057 warning
# messages to the console (once for each log message I suppose).
if syslog_enabled not in (None, False) and not WINDOWS:
from coloredlogs.syslog import enable_system_logging
if syslog_enabled is True:
# If the caller passed syslog=True then we leave the choice of
# default log level up to the coloredlogs.syslog module.
enable_system_logging()
else:
# Values other than (None, True, False) are assumed to
# represent a logging level for system logging.
enable_system_logging(level=syslog_enabled)
# Figure out whether we can use ANSI escape sequences.
use_colors = kw.get('isatty', None)
if use_colors or use_colors is None:
if NEED_COLORAMA:
try:
# On Windows we can only use ANSI escape
# sequences if Colorama is available.
import colorama
colorama.init()
use_colors = True
except ImportError:
# If Colorama isn't available then we specifically
# shouldn't emit ANSI escape sequences!
use_colors = False
elif use_colors is None:
# Auto-detect terminal support on other platforms.
use_colors = terminal_supports_colors(stream)
# Create a stream handler.
handler = logging.StreamHandler(
stream) if stream else StandardErrorHandler()
handler.setLevel(level)
# Prepare the arguments to the formatter. The caller is
# allowed to customize `fmt' and/or `datefmt' as desired.
formatter_options = dict(fmt=kw.get('fmt'), datefmt=kw.get('datefmt'))
# Come up with a default log format?
if not formatter_options['fmt']:
# Use the log format defined by the environment variable
# $COLOREDLOGS_LOG_FORMAT or fall back to the default.
formatter_options['fmt'] = os.environ.get(
'COLOREDLOGS_LOG_FORMAT') or DEFAULT_LOG_FORMAT
# If the caller didn't specify a date/time format we'll use the format
# defined by the environment variable $COLOREDLOGS_DATE_FORMAT (or fall
# back to the default).
if not formatter_options['datefmt']:
formatter_options['datefmt'] = os.environ.get(
'COLOREDLOGS_DATE_FORMAT') or DEFAULT_DATE_FORMAT
# Do we need to make %(hostname) available to the formatter?
HostNameFilter.install(
handler=handler,
fmt=formatter_options['fmt'],
use_chroot=kw.get('use_chroot', True),
)
# Do we need to make %(programname) available to the formatter?
ProgramNameFilter.install(
handler=handler,
fmt=formatter_options['fmt'],
programname=kw.get('programname'),
)
# Inject additional formatter arguments specific to ColoredFormatter?
if use_colors:
for name, environment_name in (('field_styles',
'COLOREDLOGS_FIELD_STYLES'),
('level_styles',
'COLOREDLOGS_LEVEL_STYLES')):
value = kw.get(name)
if value is None:
# If no styles have been specified we'll fall back
# to the styles defined by the environment variable.
environment_value = os.environ.get(environment_name)
if environment_value is not None:
value = parse_encoded_styles(environment_value)
if value is not None:
formatter_options[name] = value
# Create a (possibly colored) formatter.
formatter_type = ColoredFormatter if use_colors else logging.Formatter
handler.setFormatter(formatter_type(**formatter_options))
# Adjust the level of the selected logger.
adjust_level(logger, level)
# Install the stream handler.
logger.addHandler(handler)
def prompt_for_confirmation(question, default=None, padding=True):
"""
Prompt the user for confirmation.
:param question: The text that explains what the user is confirming (a string).
:param default: The default value (a boolean) or :data:`None`.
:param padding: Refer to the documentation of :func:`prompt_for_input()`.
:returns: - If the user enters 'yes' or 'y' then :data:`True` is returned.
- If the user enters 'no' or 'n' then :data:`False` is returned.
- If the user doesn't enter any text or standard input is not
connected to a terminal (which makes it impossible to prompt
the user) the value of the keyword argument ``default`` is
returned (if that value is not :data:`None`).
:raises: - Any exceptions raised by :func:`retry_limit()`.
- Any exceptions raised by :func:`prompt_for_input()`.
When `default` is :data:`False` and the user doesn't enter any text an
error message is printed and the prompt is repeated:
>>> prompt_for_confirmation("Are you sure?")
<BLANKLINE>
Are you sure? [y/n]
<BLANKLINE>
Error: Please enter 'yes' or 'no' (there's no default choice).
<BLANKLINE>
Are you sure? [y/n]
The same thing happens when the user enters text that isn't recognized:
>>> prompt_for_confirmation("Are you sure?")
<BLANKLINE>
Are you sure? [y/n] about what?
<BLANKLINE>
Error: Please enter 'yes' or 'no' (the text 'about what?' is not recognized).
<BLANKLINE>
Are you sure? [y/n]
"""
# Generate the text for the prompt.
prompt_text = question
if terminal_supports_colors():
prompt_text = ansi_wrap(prompt_text, bold=True, readline_hints=True)
# Append the valid replies (and default reply) to the prompt text.
hint = "[Y/n]" if default else "[y/N]" if default is not None else "[y/n]"
if terminal_supports_colors():
hint = ansi_wrap(hint, color=HIGHLIGHT_COLOR, readline_hints=True)
prompt_text += " %s " % hint
# Loop until a valid response is given.
logger.debug("Requesting interactive confirmation from terminal: %r",
ansi_strip(prompt_text).rstrip())
for attempt in retry_limit():
reply = prompt_for_input(prompt_text, '', padding=padding, strip=True)
if reply.lower() in ('y', 'yes'):
logger.debug("Confirmation granted by reply (%r).", reply)
return True
elif reply.lower() in ('n', 'no'):
logger.debug("Confirmation denied by reply (%r).", reply)
return False
elif (not reply) and default is not None:
logger.debug("Default choice selected by empty reply (%r).",
"granted" if default else "denied")
return default
else:
details = ("the text '%s' is not recognized" %
reply if reply else "there's no default choice")
logger.debug("Got %s reply (%s), retrying (%i/%i) ..",
"invalid" if reply else "empty", details, attempt,
MAX_ATTEMPTS)
warning("{indent}Error: Please enter 'yes' or 'no' ({details}).",
indent=' ' if padding else '',
details=details)
def format_text(self, include_password=True, use_colors=None, padding=True, filters=()):
"""
Format :attr:`text` for viewing on a terminal.
:param include_password: :data:`True` to include the password in the
formatted text, :data:`False` to exclude the
password from the formatted text.
:param use_colors: :data:`True` to use ANSI escape sequences,
:data:`False` otherwise. When this is :data:`None`
:func:`~humanfriendly.terminal.terminal_supports_colors()`
will be used to detect whether ANSI escape sequences
are supported.
:param padding: :data:`True` to add empty lines before and after the
entry and indent the entry's text with two spaces,
:data:`False` to skip the padding.
:param filters: An iterable of regular expression patterns (defaults to
an empty tuple). If a line in the entry's text matches
one of these patterns it won't be shown on the
terminal.
:returns: The formatted entry (a string).
"""
# Determine whether we can use ANSI escape sequences.
if use_colors is None:
use_colors = terminal_supports_colors()
# Extract the password (first line) from the entry.
lines = self.text.splitlines()
password = lines.pop(0).strip()
# Compile the given patterns to case insensitive regular expressions
# and use them to ignore lines that match any of the given filters.
patterns = [coerce_pattern(f, re.IGNORECASE) for f in filters]
lines = [l for l in lines if not any(p.search(l) for p in patterns)]
text = trim_empty_lines("\n".join(lines))
# Include the password in the formatted text?
if include_password:
text = "Password: %s\n%s" % (password, text)
# Add the name to the entry (only when there's something to show).
if text and not text.isspace():
title = " / ".join(split(self.name, "/"))
if use_colors:
title = ansi_wrap(title, bold=True)
text = "%s\n\n%s" % (title, text)
# Highlight the entry's text using ANSI escape sequences.
lines = []
for line in text.splitlines():
# Check for a "Key: Value" line.
match = KEY_VALUE_PATTERN.match(line)
if match:
key = "%s:" % match.group(1).strip()
value = match.group(2).strip()
if use_colors:
# Highlight the key.
key = ansi_wrap(key, color=HIGHLIGHT_COLOR)
# Underline hyperlinks in the value.
tokens = value.split()
for i in range(len(tokens)):
if "://" in tokens[i]:
tokens[i] = ansi_wrap(tokens[i], underline=True)
# Replace the line with a highlighted version.
line = key + " " + " ".join(tokens)
if padding:
line = " " + line
lines.append(line)
text = "\n".join(lines)
text = trim_empty_lines(text)
if text and padding:
text = "\n%s\n" % text
return text
def format_pretty_table(data, column_names=None, horizontal_bar='-', vertical_bar='|'):
"""
Render a table using characters like dashes and vertical bars to emulate borders.
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:param horizontal_bar: The character used to represent a horizontal bar (a
string).
:param vertical_bar: The character used to represent a vertical bar (a
string).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_pretty_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_pretty_table(humanfriendly_releases, column_names))
-------------------------------------
| Version | Uploaded on | Downloads |
-------------------------------------
| 1.23 | 2015-05-25 | 218 |
| 1.23.1 | 2015-05-26 | 1354 |
| 1.24 | 2015-05-26 | 223 |
| 1.25 | 2015-05-26 | 4319 |
| 1.25.1 | 2015-06-02 | 197 |
-------------------------------------
Notes about the resulting table:
- If a column contains numeric data (integer and/or floating point
numbers) in all rows (ignoring column names of course) then the content
of that column is right-aligned, as can be seen in the example above. The
idea here is to make it easier to compare the numbers in different
columns to each other.
- The column names are highlighted in color so they stand out a bit more
(see also :data:`.HIGHLIGHT_COLOR`). The following screen shot shows what
that looks like (my terminals are always set to white text on a black
background):
.. image:: images/pretty-table.png
"""
# Normalize the input because we'll have to iterate it more than once.
data = [normalize_columns(r) for r in data]
if column_names is not None:
column_names = normalize_columns(column_names)
if column_names:
if terminal_supports_colors():
column_names = [highlight_column_name(n) for n in column_names]
data.insert(0, column_names)
# Calculate the maximum width of each column.
widths = collections.defaultdict(int)
numeric_data = collections.defaultdict(list)
for row_index, row in enumerate(data):
for column_index, column in enumerate(row):
widths[column_index] = max(widths[column_index], ansi_width(column))
if not (column_names and row_index == 0):
numeric_data[column_index].append(bool(NUMERIC_DATA_PATTERN.match(ansi_strip(column))))
# Create a horizontal bar of dashes as a delimiter.
line_delimiter = horizontal_bar * (sum(widths.values()) + len(widths) * 3 + 1)
# Start the table with a vertical bar.
lines = [line_delimiter]
# Format the rows and columns.
for row_index, row in enumerate(data):
line = [vertical_bar]
for column_index, column in enumerate(row):
padding = ' ' * (widths[column_index] - ansi_width(column))
if all(numeric_data[column_index]):
line.append(' ' + padding + column + ' ')
else:
line.append(' ' + column + padding + ' ')
line.append(vertical_bar)
lines.append(u''.join(line))
if column_names and row_index == 0:
lines.append(line_delimiter)
# End the table with a vertical bar.
lines.append(line_delimiter)
# Join the lines, returning a single string.
return u'\n'.join(lines)
def prompt_for_choice(choices, default=None, padding=True):
"""
Prompt the user to select a choice from a group of options.
:param choices: A sequence of strings with available options.
:param default: The default choice if the user simply presses Enter
(expected to be a string, defaults to :data:`None`).
:param padding: Refer to the documentation of :func:`prompt_for_input()`.
:returns: The string corresponding to the user's choice.
:raises: - :exc:`~exceptions.ValueError` if `choices` is an empty sequence.
- Any exceptions raised by :func:`retry_limit()`.
- Any exceptions raised by :func:`prompt_for_input()`.
When no options are given an exception is raised:
>>> prompt_for_choice([])
Traceback (most recent call last):
File "humanfriendly/prompts.py", line 148, in prompt_for_choice
raise ValueError("Can't prompt for choice without any options!")
ValueError: Can't prompt for choice without any options!
If a single option is given the user isn't prompted:
>>> prompt_for_choice(['only one choice'])
'only one choice'
Here's what the actual prompt looks like by default:
>>> prompt_for_choice(['first option', 'second option'])
<BLANKLINE>
1. first option
2. second option
<BLANKLINE>
Enter your choice as a number or unique substring (Control-C aborts): second
<BLANKLINE>
'second option'
If you don't like the whitespace (empty lines and indentation):
>>> prompt_for_choice(['first option', 'second option'], padding=False)
1. first option
2. second option
Enter your choice as a number or unique substring (Control-C aborts): first
'first option'
"""
indent = ' ' if padding else ''
# Make sure we can use 'choices' more than once (i.e. not a generator).
choices = list(choices)
if len(choices) == 1:
# If there's only one option there's no point in prompting the user.
logger.debug("Skipping interactive prompt because there's only option (%r).", choices[0])
return choices[0]
elif not choices:
# We can't render a choice prompt without any options.
raise ValueError("Can't prompt for choice without any options!")
# Generate the prompt text.
prompt_text = ('\n\n' if padding else '\n').join([
# Present the available choices in a user friendly way.
"\n".join([
(u" %i. %s" % (i, choice)) + (" (default choice)" if choice == default else "")
for i, choice in enumerate(choices, start=1)
]),
# Instructions for the user.
"Enter your choice as a number or unique substring (Control-C aborts): ",
])
if terminal_supports_colors():
prompt_text = ansi_wrap(prompt_text, bold=True, readline_hints=True)
# Loop until a valid choice is made.
logger.debug("Requesting interactive choice on terminal (options are %s) ..",
concatenate(map(repr, choices)))
for attempt in retry_limit():
reply = prompt_for_input(prompt_text, '', padding=padding, strip=True)
if not reply and default is not None:
logger.debug("Default choice selected by empty reply (%r).", default)
return default
elif reply.isdigit():
index = int(reply) - 1
if 0 <= index < len(choices):
logger.debug("Option (%r) selected by numeric reply (%s).", choices[index], reply)
return choices[index]
# Check for substring matches.
matches = []
for choice in choices:
lower_reply = reply.lower()
lower_choice = choice.lower()
if lower_reply == lower_choice:
# If we have an 'exact' match we return it immediately.
logger.debug("Option (%r) selected by reply (exact match).", choice, reply)
return choice
elif lower_reply in lower_choice and len(lower_reply) > 0:
# Otherwise we gather substring matches.
matches.append(choice)
if len(matches) == 1:
# If a single choice was matched we return it.
logger.debug("Option (%r) selected by reply (substring match on %r).", matches[0], reply)
return matches[0]
else:
# Give the user a hint about what went wrong.
if matches:
details = format("text '%s' matches more than one choice: %s", reply, concatenate(matches))
elif reply.isdigit():
details = format("number %i is not a valid choice", int(reply))
elif reply and not reply.isspace():
details = format("text '%s' doesn't match any choices", reply)
else:
details = "there's no default choice"
logger.debug("Got %s reply (%s), retrying (%i/%i) ..",
"invalid" if reply else "empty", details,
attempt, MAX_ATTEMPTS)
warning("%sError: Invalid input (%s).", indent, details)
from typing import List, Optional, Union, TypeVar, Generic, Tuple, Iterator, Iterable, ClassVar, Any
from math import ceil
import sys
try:
from humanfriendly.terminal import ansi_wrap, terminal_supports_colors
have_ansi = terminal_supports_colors()
except ImportError:
have_ansi = False
__all__ = ['TablePrinter', 'TableData']
class BaseTableElement:
_width: Optional[int]
def __init__(self) -> None:
self._width = None
@property
def width(self) -> int:
if self._width is None:
self._width = self._calculate_width()
return self._width
def _calculate_width(self) -> int:
raise NotImplementedError
def _trigger_recalculate_width(self) -> None:
self._width = None
def install(level=None, **kw):
"""
Enable colored terminal output for Python's :mod:`logging` module.
:param level: The default logging level (an integer or a string with a
level name, defaults to :data:`logging.INFO`).
:param logger: The logger to which the stream handler should be attached (a
:class:`~logging.Logger` object, defaults to the root logger).
:param fmt: Set the logging format (a string like those accepted by
:class:`~logging.Formatter`, defaults to
:data:`DEFAULT_LOG_FORMAT`).
:param datefmt: Set the date/time format (a string, defaults to
:data:`DEFAULT_DATE_FORMAT`).
:param level_styles: A dictionary with custom level styles (defaults to
:data:`DEFAULT_LEVEL_STYLES`).
:param field_styles: A dictionary with custom field styles (defaults to
:data:`DEFAULT_FIELD_STYLES`).
:param stream: The stream where log messages should be written to (a
file-like object, defaults to :data:`sys.stderr`).
:param isatty: :data:`True` to use a :class:`ColoredFormatter`,
:data:`False` to use a normal :class:`~logging.Formatter`
(defaults to auto-detection using
:func:`~humanfriendly.terminal.terminal_supports_colors()`).
:param reconfigure: If :data:`True` (the default) multiple calls to
:func:`coloredlogs.install()` will each override
the previous configuration.
:param use_chroot: Refer to :class:`HostNameFilter`.
:param programname: Refer to :class:`ProgramNameFilter`.
:param syslog: If :data:`True` then :func:`~coloredlogs.syslog.enable_system_logging()`
will be called without arguments (defaults to :data:`False`).
The :func:`coloredlogs.install()` function is similar to
:func:`logging.basicConfig()`, both functions take a lot of optional
keyword arguments but try to do the right thing by default:
1. If `reconfigure` is :data:`True` (it is by default) and an existing
:class:`~logging.StreamHandler` is found that is connected to either
:data:`~sys.stdout` or :data:`~sys.stderr` the handler will be removed.
This means that first calling :func:`logging.basicConfig()` and then
calling :func:`coloredlogs.install()` will replace the stream handler
instead of adding a duplicate stream handler. If `reconfigure` is
:data:`False` and an existing handler is found no further steps are
taken (to avoid installing a duplicate stream handler).
2. A :class:`~logging.StreamHandler` is created and connected to the stream
given by the `stream` keyword argument (:data:`sys.stderr` by
default). The stream handler's level is set to the value of the `level`
keyword argument.
3. A :class:`ColoredFormatter` is created if the `isatty` keyword argument
allows it (or auto-detection allows it), otherwise a normal
:class:`~logging.Formatter` is created. The formatter is initialized
with the `fmt` and `datefmt` keyword arguments (or their computed
defaults).
4. :func:`HostNameFilter.install()` and :func:`ProgramNameFilter.install()`
are called to enable the use of additional fields in the log format.
5. The formatter is added to the handler and the handler is added to the
logger. The logger's level is set to :data:`logging.NOTSET` so that each
handler gets to decide which records they filter. This makes it possible
to have controllable verbosity on the terminal while logging at full
verbosity to the system log or a file.
"""
logger = kw.get('logger') or logging.getLogger()
reconfigure = kw.get('reconfigure', True)
stream = kw.get('stream', sys.stderr)
# Remove any existing stream handler that writes to stdout or stderr, even
# if the stream handler wasn't created by coloredlogs because multiple
# stream handlers (in the same hierarchy) writing to stdout or stderr would
# create duplicate output.
standard_streams = (sys.stdout, sys.stderr)
match_streams = standard_streams if stream in standard_streams else (stream,)
match_handler = lambda handler: match_stream_handler(handler, match_streams)
handler, logger = replace_handler(logger, match_handler, reconfigure)
# Make sure reconfiguration is allowed or not relevant.
if not (handler and not reconfigure):
# Make it easy to enable system logging.
if kw.get('syslog', False):
from coloredlogs import syslog
syslog.enable_system_logging()
# Figure out whether we can use ANSI escape sequences.
use_colors = kw.get('isatty', None)
if use_colors or use_colors is None:
if NEED_COLORAMA:
if HAVE_COLORAMA:
# On Windows we can only use ANSI escape
# sequences if Colorama is available.
colorama.init()
use_colors = True
else:
# If Colorama isn't available then we specifically
# shouldn't emit ANSI escape sequences!
use_colors = False
elif use_colors is None:
# Auto-detect terminal support on other platforms.
use_colors = terminal_supports_colors(stream)
# Create a stream handler.
handler = logging.StreamHandler(stream)
if level is None:
level = os.environ.get('COLOREDLOGS_LOG_LEVEL') or 'INFO'
handler.setLevel(level_to_number(level))
# Prepare the arguments to the formatter. The caller is
# allowed to customize `fmt' and/or `datefmt' as desired.
formatter_options = dict(fmt=kw.get('fmt'), datefmt=kw.get('datefmt'))
# Come up with a default log format?
if not formatter_options['fmt']:
# Use the log format defined by the environment variable
# $COLOREDLOGS_LOG_FORMAT or fall back to the default.
formatter_options['fmt'] = os.environ.get('COLOREDLOGS_LOG_FORMAT') or DEFAULT_LOG_FORMAT
# If the caller didn't specify a date/time format we'll use the format
# defined by the environment variable $COLOREDLOGS_DATE_FORMAT (or fall
# back to the default).
if not formatter_options['datefmt']:
formatter_options['datefmt'] = os.environ.get('COLOREDLOGS_DATE_FORMAT') or DEFAULT_DATE_FORMAT
# Do we need to make %(hostname) available to the formatter?
HostNameFilter.install(
handler=handler,
fmt=formatter_options['fmt'],
use_chroot=kw.get('use_chroot', True),
)
# Do we need to make %(programname) available to the formatter?
ProgramNameFilter.install(
handler=handler,
fmt=formatter_options['fmt'],
programname=kw.get('programname'),
)
# Inject additional formatter arguments specific to ColoredFormatter?
if use_colors:
for name, environment_name in (('field_styles', 'COLOREDLOGS_FIELD_STYLES'),
('level_styles', 'COLOREDLOGS_LEVEL_STYLES')):
value = kw.get(name)
if value is None:
# If no styles have been specified we'll fall back
# to the styles defined by the environment variable.
environment_value = os.environ.get(environment_name)
if environment_value is not None:
value = parse_encoded_styles(environment_value)
if value is not None:
formatter_options[name] = value
# Create a (possibly colored) formatter.
formatter_type = ColoredFormatter if use_colors else logging.Formatter
handler.setFormatter(formatter_type(**formatter_options))
# Install the stream handler.
logger.setLevel(logging.NOTSET)
logger.addHandler(handler)
def format_pretty_table(data,
column_names=None,
horizontal_bar='-',
vertical_bar='|'):
"""
Render a table using characters like dashes and vertical bars to emulate borders.
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:param horizontal_bar: The character used to represent a horizontal bar (a
string).
:param vertical_bar: The character used to represent a vertical bar (a
string).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_pretty_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_pretty_table(humanfriendly_releases, column_names))
-------------------------------------
| Version | Uploaded on | Downloads |
-------------------------------------
| 1.23 | 2015-05-25 | 218 |
| 1.23.1 | 2015-05-26 | 1354 |
| 1.24 | 2015-05-26 | 223 |
| 1.25 | 2015-05-26 | 4319 |
| 1.25.1 | 2015-06-02 | 197 |
-------------------------------------
Notes about the resulting table:
- If a column contains numeric data (integer and/or floating point
numbers) in all rows (ignoring column names of course) then the content
of that column is right-aligned, as can be seen in the example above. The
idea here is to make it easier to compare the numbers in different
columns to each other.
- The column names are highlighted in color so they stand out a bit more
(see also :data:`.HIGHLIGHT_COLOR`). The following screen shot shows what
that looks like (my terminals are always set to white text on a black
background):
.. image:: images/pretty-table.png
"""
# Normalize the input because we'll have to iterate it more than once.
data = [normalize_columns(r) for r in data]
if column_names is not None:
column_names = normalize_columns(column_names)
if column_names:
if terminal_supports_colors():
column_names = [highlight_column_name(n) for n in column_names]
data.insert(0, column_names)
# Calculate the maximum width of each column.
widths = collections.defaultdict(int)
numeric_data = collections.defaultdict(list)
for row_index, row in enumerate(data):
for column_index, column in enumerate(row):
widths[column_index] = max(widths[column_index],
ansi_width(column))
if not (column_names and row_index == 0):
numeric_data[column_index].append(
bool(NUMERIC_DATA_PATTERN.match(ansi_strip(column))))
# Create a horizontal bar of dashes as a delimiter.
line_delimiter = horizontal_bar * (sum(widths.values()) + len(widths) * 3 +
1)
# Start the table with a vertical bar.
lines = [line_delimiter]
# Format the rows and columns.
for row_index, row in enumerate(data):
line = [vertical_bar]
for column_index, column in enumerate(row):
padding = ' ' * (widths[column_index] - ansi_width(column))
if all(numeric_data[column_index]):
line.append(' ' + padding + column + ' ')
else:
line.append(' ' + column + padding + ' ')
line.append(vertical_bar)
lines.append(u''.join(line))
if column_names and row_index == 0:
lines.append(line_delimiter)
# End the table with a vertical bar.
lines.append(line_delimiter)
# Join the lines, returning a single string.
return u'\n'.join(lines)
def format_robust_table(data, column_names):
"""
Render tabular data with one column per line (allowing columns with line breaks).
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_robust_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_robust_table(humanfriendly_releases, column_names))
-----------------------
Version: 1.23
Uploaded on: 2015-05-25
Downloads: 218
-----------------------
Version: 1.23.1
Uploaded on: 2015-05-26
Downloads: 1354
-----------------------
Version: 1.24
Uploaded on: 2015-05-26
Downloads: 223
-----------------------
Version: 1.25
Uploaded on: 2015-05-26
Downloads: 4319
-----------------------
Version: 1.25.1
Uploaded on: 2015-06-02
Downloads: 197
-----------------------
The column names are highlighted in bold font and color so they stand out a
bit more (see :data:`.HIGHLIGHT_COLOR`).
"""
blocks = []
column_names = ["%s:" % n for n in normalize_columns(column_names)]
if terminal_supports_colors():
column_names = [highlight_column_name(n) for n in column_names]
# Convert each row into one or more `name: value' lines (one per column)
# and group each `row of lines' into a block (i.e. rows become blocks).
for row in data:
lines = []
for column_index, column_text in enumerate(normalize_columns(row)):
stripped_column = column_text.strip()
if '\n' not in stripped_column:
# Columns without line breaks are formatted inline.
lines.append("%s %s" %
(column_names[column_index], stripped_column))
else:
# Columns with line breaks could very well contain indented
# lines, so we'll put the column name on a separate line. This
# way any indentation remains intact, and it's easier to
# copy/paste the text.
lines.append(column_names[column_index])
lines.extend(column_text.rstrip().splitlines())
blocks.append(lines)
# Calculate the width of the row delimiter.
num_rows, num_columns = find_terminal_size()
longest_line = max(max(map(ansi_width, lines)) for lines in blocks)
delimiter = u"\n%s\n" % ('-' * min(longest_line, num_columns))
# Force a delimiter at the start and end of the table.
blocks.insert(0, "")
blocks.append("")
# Embed the row delimiter between every two blocks.
return delimiter.join(u"\n".join(b) for b in blocks).strip()
def prompt_for_confirmation(question, default=None, padding=True):
"""
Prompt the user for confirmation.
:param question: The text that explains what the user is confirming (a string).
:param default: The default value (a boolean) or :data:`None`.
:param padding: Refer to the documentation of :func:`prompt_for_input()`.
:returns: - If the user enters 'yes' or 'y' then :data:`True` is returned.
- If the user enters 'no' or 'n' then :data:`False` is returned.
- If the user doesn't enter any text or standard input is not
connected to a terminal (which makes it impossible to prompt
the user) the value of the keyword argument ``default`` is
returned (if that value is not :data:`None`).
:raises: - Any exceptions raised by :func:`retry_limit()`.
- Any exceptions raised by :func:`prompt_for_input()`.
When `default` is :data:`False` and the user doesn't enter any text an
error message is printed and the prompt is repeated:
>>> prompt_for_confirmation("Are you sure?")
<BLANKLINE>
Are you sure? [y/n]
<BLANKLINE>
Error: Please enter 'yes' or 'no' (there's no default choice).
<BLANKLINE>
Are you sure? [y/n]
The same thing happens when the user enters text that isn't recognized:
>>> prompt_for_confirmation("Are you sure?")
<BLANKLINE>
Are you sure? [y/n] about what?
<BLANKLINE>
Error: Please enter 'yes' or 'no' (the text 'about what?' is not recognized).
<BLANKLINE>
Are you sure? [y/n]
"""
# Generate the text for the prompt.
prompt_text = question
if terminal_supports_colors():
prompt_text = ansi_wrap(prompt_text, bold=True, readline_hints=True)
# Append the valid replies (and default reply) to the prompt text.
hint = "[Y/n]" if default else "[y/N]" if default is not None else "[y/n]"
if terminal_supports_colors():
hint = ansi_wrap(hint, color=HIGHLIGHT_COLOR, readline_hints=True)
prompt_text += " %s " % hint
# Loop until a valid response is given.
logger.debug("Requesting interactive confirmation from terminal: %r", ansi_strip(prompt_text).rstrip())
for attempt in retry_limit():
reply = prompt_for_input(prompt_text, '', padding=padding, strip=True)
if reply.lower() in ('y', 'yes'):
logger.debug("Confirmation granted by reply (%r).", reply)
return True
elif reply.lower() in ('n', 'no'):
logger.debug("Confirmation denied by reply (%r).", reply)
return False
elif (not reply) and default is not None:
logger.debug("Default choice selected by empty reply (%r).",
"granted" if default else "denied")
return default
else:
details = ("the text '%s' is not recognized" % reply
if reply else "there's no default choice")
logger.debug("Got %s reply (%s), retrying (%i/%i) ..",
"invalid" if reply else "empty", details,
attempt, MAX_ATTEMPTS)
warning("{indent}Error: Please enter 'yes' or 'no' ({details}).",
indent=' ' if padding else '', details=details)
def prompt_for_choice(choices, default=None, padding=True):
"""
Prompt the user to select a choice from a group of options.
:param choices: A sequence of strings with available options.
:param default: The default choice if the user simply presses Enter
(expected to be a string, defaults to :data:`None`).
:param padding: Refer to the documentation of :func:`prompt_for_input()`.
:returns: The string corresponding to the user's choice.
:raises: - :exc:`~exceptions.ValueError` if `choices` is an empty sequence.
- Any exceptions raised by :func:`retry_limit()`.
- Any exceptions raised by :func:`prompt_for_input()`.
When no options are given an exception is raised:
>>> prompt_for_choice([])
Traceback (most recent call last):
File "humanfriendly/prompts.py", line 148, in prompt_for_choice
raise ValueError("Can't prompt for choice without any options!")
ValueError: Can't prompt for choice without any options!
If a single option is given the user isn't prompted:
>>> prompt_for_choice(['only one choice'])
'only one choice'
Here's what the actual prompt looks like by default:
>>> prompt_for_choice(['first option', 'second option'])
<BLANKLINE>
1. first option
2. second option
<BLANKLINE>
Enter your choice as a number or unique substring (Control-C aborts): second
<BLANKLINE>
'second option'
If you don't like the whitespace (empty lines and indentation):
>>> prompt_for_choice(['first option', 'second option'], padding=False)
1. first option
2. second option
Enter your choice as a number or unique substring (Control-C aborts): first
'first option'
"""
indent = ' ' if padding else ''
# Make sure we can use 'choices' more than once (i.e. not a generator).
choices = list(choices)
if len(choices) == 1:
# If there's only one option there's no point in prompting the user.
logger.debug(
"Skipping interactive prompt because there's only option (%r).",
choices[0])
return choices[0]
elif not choices:
# We can't render a choice prompt without any options.
raise ValueError("Can't prompt for choice without any options!")
# Generate the prompt text.
prompt_text = ('\n\n' if padding else '\n').join([
# Present the available choices in a user friendly way.
"\n".join([(u" %i. %s" % (i, choice)) +
(" (default choice)" if choice == default else "")
for i, choice in enumerate(choices, start=1)]),
# Instructions for the user.
"Enter your choice as a number or unique substring (Control-C aborts): ",
])
if terminal_supports_colors():
prompt_text = ansi_wrap(prompt_text, bold=True, readline_hints=True)
# Loop until a valid choice is made.
logger.debug(
"Requesting interactive choice on terminal (options are %s) ..",
concatenate(map(repr, choices)))
for attempt in retry_limit():
reply = prompt_for_input(prompt_text, '', padding=padding, strip=True)
if not reply and default is not None:
logger.debug("Default choice selected by empty reply (%r).",
default)
return default
elif reply.isdigit():
index = int(reply) - 1
if 0 <= index < len(choices):
logger.debug("Option (%r) selected by numeric reply (%s).",
choices[index], reply)
return choices[index]
# Check for substring matches.
matches = []
for choice in choices:
lower_reply = reply.lower()
lower_choice = choice.lower()
if lower_reply == lower_choice:
# If we have an 'exact' match we return it immediately.
logger.debug("Option (%r) selected by reply (exact match).",
choice)
return choice
elif lower_reply in lower_choice and len(lower_reply) > 0:
# Otherwise we gather substring matches.
matches.append(choice)
if len(matches) == 1:
# If a single choice was matched we return it.
logger.debug(
"Option (%r) selected by reply (substring match on %r).",
matches[0], reply)
return matches[0]
else:
# Give the user a hint about what went wrong.
if matches:
details = format("text '%s' matches more than one choice: %s",
reply, concatenate(matches))
elif reply.isdigit():
details = format("number %i is not a valid choice", int(reply))
elif reply and not reply.isspace():
details = format("text '%s' doesn't match any choices", reply)
else:
details = "there's no default choice"
logger.debug("Got %s reply (%s), retrying (%i/%i) ..",
"invalid" if reply else "empty", details, attempt,
MAX_ATTEMPTS)
warning("%sError: Invalid input (%s).", indent, details)
def format_robust_table(data, column_names):
"""
Render tabular data with one column per line (allowing columns with line breaks).
:param data: An iterable (e.g. a :func:`tuple` or :class:`list`)
containing the rows of the table, where each row is an
iterable containing the columns of the table (strings).
:param column_names: An iterable of column names (strings).
:returns: The rendered table (a string).
Here's an example:
>>> from humanfriendly.tables import format_robust_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_robust_table(humanfriendly_releases, column_names))
-----------------------
Version: 1.23
Uploaded on: 2015-05-25
Downloads: 218
-----------------------
Version: 1.23.1
Uploaded on: 2015-05-26
Downloads: 1354
-----------------------
Version: 1.24
Uploaded on: 2015-05-26
Downloads: 223
-----------------------
Version: 1.25
Uploaded on: 2015-05-26
Downloads: 4319
-----------------------
Version: 1.25.1
Uploaded on: 2015-06-02
Downloads: 197
-----------------------
The column names are highlighted in bold font and color so they stand out a
bit more (see :data:`.HIGHLIGHT_COLOR`).
"""
blocks = []
column_names = ["%s:" % n for n in normalize_columns(column_names)]
if terminal_supports_colors():
column_names = [highlight_column_name(n) for n in column_names]
# Convert each row into one or more `name: value' lines (one per column)
# and group each `row of lines' into a block (i.e. rows become blocks).
for row in data:
lines = []
for column_index, column_text in enumerate(normalize_columns(row)):
stripped_column = column_text.strip()
if '\n' not in stripped_column:
# Columns without line breaks are formatted inline.
lines.append("%s %s" % (column_names[column_index], stripped_column))
else:
# Columns with line breaks could very well contain indented
# lines, so we'll put the column name on a separate line. This
# way any indentation remains intact, and it's easier to
# copy/paste the text.
lines.append(column_names[column_index])
lines.extend(column_text.rstrip().splitlines())
blocks.append(lines)
# Calculate the width of the row delimiter.
num_rows, num_columns = find_terminal_size()
longest_line = max(max(map(ansi_width, lines)) for lines in blocks)
delimiter = u"\n%s\n" % ('-' * min(longest_line, num_columns))
# Force a delimiter at the start and end of the table.
blocks.insert(0, "")
blocks.append("")
# Embed the row delimiter between every two blocks.
return delimiter.join(u"\n".join(b) for b in blocks).strip()
def format_text(self,
include_password=True,
use_colors=None,
padding=True):
"""
Format :attr:`text` for viewing on a terminal.
:param include_password: :data:`True` to include the password in the
formatted text, :data:`False` to exclude the
password from the formatted text.
:param use_colors: :data:`True` to use ANSI escape sequences,
:data:`False` otherwise. When this is :data:`None`
:func:`~humanfriendly.terminal.terminal_supports_colors()`
will be used to detect whether ANSI escape sequences
are supported.
:param padding: :data:`True` to add empty lines before and after the
entry and indent the entry's text with two spaces,
:data:`False` to skip the padding.
:returns: The formatted entry (a string).
"""
# Determine whether we can use ANSI escape sequences.
if use_colors is None:
use_colors = terminal_supports_colors()
# Extract the password (first line) from the entry.
lines = self.text.splitlines()
password = lines.pop(0).strip()
text = trim_empty_lines('\n'.join(lines))
# Include the password in the formatted text?
if include_password:
text = "Password: %s\n%s" % (password, text)
# Add the name to the entry (only when there's something to show).
if text and not text.isspace():
title = ' / '.join(split(self.name, '/'))
if use_colors:
title = ansi_wrap(title, bold=True)
text = "%s\n\n%s" % (title, text)
# Highlight the entry's text using ANSI escape sequences.
lines = []
for line in text.splitlines():
# Check for a "Key: Value" line.
match = KEY_VALUE_PATTERN.match(line)
if match:
key = "%s:" % match.group(1).strip()
value = match.group(2).strip()
if use_colors:
# Highlight the key.
key = ansi_wrap(key, color=HIGHLIGHT_COLOR)
# Underline hyperlinks in the value.
tokens = value.split()
for i in range(len(tokens)):
if '://' in tokens[i]:
tokens[i] = ansi_wrap(tokens[i], underline=True)
# Replace the line with a highlighted version.
line = key + ' ' + ' '.join(tokens)
if padding:
line = ' ' + line
lines.append(line)
text = '\n'.join(lines)
if text and padding:
text = '\n%s\n' % text
return text
