Warning

This project is being split into 3 separate projects:

• friendly_traceback,

• friendly, and

• friendly_idle.

The documentation does not reflect this change.

If you are a end-user, just install friendly until further notice.

Custom formatter

friendly comes with various formatters which style the information differently based on the environment. If the builtin formatters do not meet your need, you can design your own and set it as a default using either:

import friendly
from my_module import my_formatter

friendly.set_formatter(formatter=my_formatter)

or, from the command line:

python -m friendly --format path.to.my_module.my_formatter

Currently, a formatter must accept two arguments:

1. A dict (info) which contains the friendly traceback information. The current dict items are the following:

   items = [
        "debug_warning",
        "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_header",
        "cause",
        "last_call_header",
        "last_call_source",
        "last_call_variables",
        "exception_raised_header",
        "exception_raised_source",
        "exception_raised_variables",
    ]
   

   New items are likely going to be added in the near future: is it suggested that you look at the actual code if you plan to create your own formatter.

Tip

Use show_info() in a friendly console to see all possible items.

2. A string (include) which specifies which parts of the friendly traceback should be shown, and whose value is currently set using friendly.set_include(...).

The second argument _might_ change in the future. If you only plan on making use of the traceback information compiled by friendly and determine what to show (and in which order) on your own, to ensure that future version of friendly will be compatible with your formatter, we suggest the following definition:

def my_formatter(info, **ignore):
    ....

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).

docs(info, include='friendly_tb')

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.

jupyter(info, include='friendly_tb')

Default formatter, primarily for console usage.

The only change made to the content of “info” is some added indentation.

markdown(info, include='friendly_tb')

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.

markdown_docs(info, include='explain')

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.

no_result(info, include)

Should normally only be called if no result is available from either hint() or why().

repl(info, include='friendly_tb')

Default formatter, primarily for console usage.

The only change made to the content of “info” is some added indentation.

rich_markdown(info, include='friendly_tb')

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().