Warning

Most of the documentation was written prior to version 0.5 and needs to be updated. This work has now started for version 0.7 and we aim to have it completed before version 0.8 is available.

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. At the time this documentation was written, the dict items were the following:

   items_in_order = [
       "header",  # Currently unused by this project; used by HackInScience
       "message",  # The last line of a Python traceback
       "original_python_traceback",  # <-- Friendly._debug_tb()
       "simulated_python_traceback",  # <-- python_tb()
       "shortened_traceback",  # <-- friendly_tb()
       "suggest",  # <-- hint()
       "warning message",
       "generic",  # <-- what()
       "parsing_error",
       "parsing_error_source",
       "cause",  # <-- why()
       "last_call_header",
       "last_call_source",
       "last_call_variables",
       "exception_raised_header",
       "exception_raised_source",
       "exception_raised_variables",
       "warning location header",
       "warning source",
       "warning variables",
       "additional variable warning",
   ]
   

Tip

To see all the items of a traceback when object Friendly is available, do the following:

from pprint import pprint

info = Friendly._get_info()
pprint(info)

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

base_formatters.py

This file contains the formatters included with friendly_traceback. Other formatters of potential interest, including a formatter designed for IDLE as well as some making use of Rich, are included with friendly.

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 2 formatters:

• repl(): This is used to print the information in a traditional console. The indentation of the traceback itself is chosen 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.

detailed_tb(info)

Unlike the normal information from ‘where()’, which focus on at most two frames, detailed_tb() gives information for all the frames. It is used mostly in IPython based environment - especially with the ‘button-based’ mode in Jupyter notebooks/lab.

Return type

str

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.

Return type

str

no_result(info, include)

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

Return type

str

repl(info, include='friendly_tb')

Default formatter, primarily for console usage.

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

Return type

str