Source code for friendly.formatters

"""
formatters.py
==============

Default formatters showing all or only part of the available information.

A formatter is a function that takes two arguments:

1. a dict (named ``info`` everywhere in friendly files) containing
   all the information that can be shown to the user, as well as some
   entries that are meant to be used only internally as the full
   friendly information is obtained.

2. A second argument which is meant to convey what information should be shown.
   This second argument used to be a single integer ("verbosity level").
   It is currently recently being replaced by a single string. However,
   this might change as we experiment with various options prior to
   version 1.0

A formatter returns a single string. By default, this string will be
written to stderr; however this can be changed by the calling program.

This module currently contains 6 formatters:

* ``repl()``: This is used to print the information in a traditional console,
  including that found in IDLE.  The indentation of the traceback itself
  is chosen so as to reproduce that of a normal Python traceback.

* ``docs()``: this produces output with leading spaces so that it can be
  embedded as a code-block in a file (such as .rst). It can also be used
  to print the information in a traditional console, including that
  found in IDLE.

* ``jupyter()``: experimental formatter for Jupyter notebooks

* ``markdown()``: This produces an output formatted with markdown syntax.

* ``markdown_docs()``: This produces an output formatted markdown syntax,
    but where each header is shifted down by 2 (h1 -> h3, etc.) so that they
    can be inserted in a document, without creating artificial top headers.

* ``rich_markdown()``: This produces an output formatted with markdown syntax,
    with some modification, with the end result intended to be printed
    in colour in a console using Rich (https://github.com/willmcgugan/rich).
"""
from .my_gettext import current_lang
from . import debug_helper

try:  # allow to use without installing pygments.
    from pygments import highlight  # noqa
    from pygments.lexers import PythonLexer, PythonTracebackLexer  # noqa
    from pygments.formatters import HtmlFormatter  # noqa
except ImportError:
    pass

ipython_available = False
try:  # pragma: no cover

    from IPython.display import display, HTML  # noqa

    ipython_available = True
except ImportError:
    pass

RICH_HEADER = False

# The following is the order in which the various items, if they exist
# and have been selected to be printed, would be printed.
# If you are writing a custom formatter, this should be taken as the
# authoritative list of items to consider.

items_in_order = [
    "header",
    "message",  # The last line of a Python traceback
    "original_python_traceback",
    "simulated_python_traceback",
    "shortened_traceback",
    "suggest",
    "generic",
    "parsing_error",
    "parsing_error_source",
    "cause",
    "last_call_header",
    "last_call_source",
    "last_call_variables",
    "exception_raised_header",
    "exception_raised_source",
    "exception_raised_variables",
]


repl_indentation = {
    # "header": "single",  # no longer shown; keep for reference
    "message": "single",
    "simulated_python_traceback": "none",
    "original_python_traceback": "none",
    "shortened_traceback": "none",
    "suggest": "double",
    "generic": "single",
    "parsing_error": "single",
    "parsing_error_source": "none",
    "cause": "single",
    "last_call_header": "single",
    "last_call_source": "none",
    "last_call_variables": "double",
    "exception_raised_header": "single",
    "exception_raised_source": "none",
    "exception_raised_variables": "double",
}


# ===============================
#
#  Next, we have the five formatters.
#
# ===============================


[docs]def repl(info, include="friendly_tb"): """Default formatter, primarily for console usage. The only change made to the content of "info" is some added indentation. """ items_to_show = select_items(include) spacing = {"single": " " * 4, "double": " " * 8, "none": ""} result = [""] if include == "message": return info["message"] for item in items_to_show: if item in info: indentation = spacing[repl_indentation[item]] for line in info[item].split("\n"): result.append(indentation + line) if result == [""] or not result: return no_result(info, include) return "\n".join(result)
def html_escape(text): # pragma: no cover text = ( text.replace("&", "&amp;") .replace("<", "&lt;") .replace(">", "&gt;") .replace("\n\n", "<br>") ) while "`" in text: text = text.replace("`", "<code>", 1) text = text.replace("`", "</code>", 1) return text # For some reason, moving this to friendly.ipython # and trying to import it from there uninstalls everything: it is as though # it starts a new iPython subprocess.
[docs]def jupyter(info, include="friendly_tb"): # pragma: no cover """Jupyter formatter using pygments and html format.""" _ = current_lang.translate css = HtmlFormatter().get_style_defs(".highlight") display(HTML(f"<style>{css}</style>")) # noqa items_to_show = select_items(include) result = False for item in items_to_show: if item in info: result = True if "source" in item or "variable" in item: text = info[item] text = highlight(text, PythonLexer(), HtmlFormatter()) display(HTML(text)) # noqa elif "traceback" in item: text = info[item] text = highlight(text, PythonTracebackLexer(), HtmlFormatter()) display(HTML(text)) # noqa elif item == "message": # format like last line of traceback content = info[item].split(":") error_name = content[0] message = ":".join(content[1:]) if len(content) > 1 else "" text = "".join( [ '<div class="highlight"><pre><span class="gr">', error_name, '</span>: <span class="n">', message, "</span></pre></div>", ] ) display(HTML(text)) # noqa elif item == "suggest": text = html_escape(info[item]) display(HTML(f"<p><i>{text}<i><p>")) # noqa else: text = html_escape(info[item]) if "header" in item: display(HTML(f"<p><b>{text}</b></p>")) # noqa else: display(HTML(f'<p style="width: 70ch">{text}</p>')) # noqa if not result: text = "" if include == "why": text = _("I do not know.") elif include == "hint": if info["cause"]: text = _("I have no suggestion to offer; try `why()`.") else: text = _("I have no suggestion to offer.") if not text: return "" display(HTML(f'<p style="width: 70ch;">{text}</p>')) # noqa return ""
if not ipython_available: jupyter = repl # noqa
[docs]def docs(info, include="friendly_tb"): # pragma: no cover """Formatter that produces an output that is suitable for insertion in a RestructuredText (.rst) code block, with pre-formatted indentation. The only change made to the content of "info" is some added indentation. """ # We first define the indentation to appear before each item pre_items = dict(**repl_indentation) pre_items.update( **{ "simulated_python_traceback": "single", "original_python_traceback": "single", "shortened_traceback": "single", } ) items_to_show = select_items(include) spacing = {"single": " " * 4, "double": " " * 8, "none": ""} result = [""] for item in items_to_show: if item in info and info[item].strip(): indentation = spacing[pre_items[item]] for line in info[item].split("\n"): result.append(indentation + line) if result == [""]: return no_result(info, include) return "\n".join(result)
[docs]def markdown(info, include="friendly_tb"): # pragma: no cover """Traceback formatted with markdown syntax. Some minor changes of the traceback info content are done, for nicer final display when the markdown generated content if further processed. """ return _markdown(info, include)
[docs]def markdown_docs(info, include="explain"): # pragma: no cover """Traceback formatted with markdown syntax, where each header is shifted down by 2 (h1 -> h3, etc.) so that they can be inserted in a document, without creating artificial top headers. Some minor changes of the traceback info content are done, for nicer final display when the markdown generated content is further processed. """ return _markdown(info, include, documentation=True)
[docs]def rich_markdown(info, include="friendly_tb"): # pragma: no cover """Traceback formatted with with markdown syntax suitable for printing in color in the console using Rich. Some minor changes of the traceback info content are done, for nicer final display when the markdown generated content if further processed. Some additional processing is done just prior to doing the final output, by ``session._write_err()``. """ return _markdown(info, include, rich=True)
def _markdown(info, include, rich=False, documentation=False): # pragma: no cover """Traceback formatted with with markdown syntax.""" global RICH_HEADER RICH_HEADER = False markdown_items = { "header": ("# ", ""), "message": ("", ""), "suggest": ("", "\n"), "generic": ("", ""), "parsing_error": ("", ""), "parsing_error_source": ("```python\n", "\n```"), "cause": ("", ""), "last_call_header": ("## ", ""), "last_call_source": ("```python\n", "\n```"), "last_call_variables": ("```python\n", "\n```"), "exception_raised_header": ("## ", ""), "exception_raised_source": ("```python\n", "\n```"), "exception_raised_variables": ("```python\n", "\n```"), "simulated_python_traceback": ("```pytb\n", "\n```"), "original_python_traceback": ("```pytb\n", "\n```"), "shortened_traceback": ("```pytb\n", "\n```"), } items_to_show = select_items(include) # tb_items_to_show(level=level) if rich and include == "explain": RICH_HEADER = True # Skip it here; handled by session.py result = [""] for item in items_to_show: if item in info and info[item].strip(): # With normal markdown formatting, it does not make sense to have a # header end with a colon. # However, we style headers differently with Rich; see # Rich theme in file friendly_rich. content = info[item] if item.endswith("header"): content = content.rstrip(":") if item == "message" and rich: # Ensure that the exception name is highlighted. content = content.split(":") content[0] = "`" + content[0] + "`" content = ":".join(content) prefix, suffix = markdown_items[item] if documentation and prefix.startswith("#"): prefix = "##" + prefix result.append(prefix + content + suffix) if result == [""]: return no_result(info, include) if include == "message": return result[1] return "\n\n".join(result)
[docs]def no_result(info, include): """Should normally only be called if no result is available from either hint() or why(). """ _ = current_lang.translate if include == "why": return _("I have no suggestion to offer.") if include == "hint": if "cause" in info: return _("I have no suggestion to offer; try `why()`.") return _("I have no suggestion to offer.") debug_helper.log( f"Internal error: include = {include} in formatters.no_result()" ) # pragma: no cover
items_groups = { "message": {"message"}, # Also included as last line of traceback "hint": {"suggest"}, "what": {"generic"}, "why": {"cause"}, "where": { "parsing_error", "parsing_error_source", "last_call_header", "last_call_source", "last_call_variables", "exception_raised_header", "exception_raised_source", "exception_raised_variables", }, "friendly_tb": {"shortened_traceback", "suggest"}, "python_tb": {"simulated_python_traceback"}, "debug_tb": {"original_python_traceback"}, } items_groups["explain"] = ( items_groups["friendly_tb"] .union(items_groups["what"]) .union(items_groups["why"]) .union(items_groups["where"]) ) items_groups["no_tb"] = items_groups["explain"] # used in check_syntax() items_groups["no_tb"].discard(items_groups["friendly_tb"]) def select_items(group_name): items = items_groups[group_name] return [item for item in items_in_order if item in items]