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.

Everything about the friendly console


The hand-written documentation about the console might not reflect the latest version of the code. This page documents the relevant API by automatically extracting information from the code.

Note that dark() and light() might not be available in some environments (for example, when using IDLE or Mu.)


Functions that can be used in a friendly console or in other interactive environments such as in a Jupyter notebook.


Removes the last recorded traceback item.

The intention is to allow recovering from a typo when trying interactively to find out specific information about a given exception.


Synonym of set_formatter(‘dark’) designed to be used within iPython/Jupyter programming environments or at a terminal.


Shows the previously recorded traceback info again, with the option to specify different items to include. For example, explain("why") is equivalent to why().


Shows the a simplified Python traceback, which includes the hint/suggestion if available.


Retrieves the value used to determine what to include in the traceback. See set_include() for details.


Returns the current language that had been set for translations.

Note that the value returned may not reflect truly what is being see by the end user: if the translations do not exist for that language, the default English strings are used.


Shows hint/suggestion if available.


Prints the list of error messages recorded so far.


Synonym of set_formatter(‘light’) designed to be used within iPython/Jupyter programming environments or at a terminal.


Shows the Python traceback, excluding files from friendly itself.

set_formatter(formatter=None, **kwargs)[source]

Sets the default formatter. If no argument is given, the default formatter is used.

A custom formatter must accept info as a required arguments as well an additional argument whose value is subject to change. See formatters.py for details.


Specifies the information to include in the traceback.

The allowed values are:

‘message’, ‘hint’, ‘what’, ‘why’, ‘where’, ‘friendly_tb’, ‘python_tb’, ‘debug_tb’, ‘explain’, ‘no_tb’


Sets the language to be used for the display.

If no translations exist for that language, the original English strings will be used.


To avoid displaying very long file paths to the user, Friendly-traceback tries to shorten them using some easily recognized synonyms. This function shows the path synonyms currently used.

what(exception=None, pre=False)[source]

If known, shows the generic explanation about a given exception.

If the pre argument is set to True, the output is formatted in a way that is suitable for inclusion in the documentation.


Shows the information about where the exception occurred


Shows the likely cause of the exception.

This uses the webbrowser module to open a tab (or window)

in the default browser, linking to a specific url or opening the default email client.

  • If the argument ‘site’ is not specified, and an exception has been raised, an internet search will be done using the exception message as the search string.

  • If the argument ‘site’ is not specified, and NO exception has been raised, Friendly’s documentation will open.

  • If the argument ‘site’ == “friendly”, Friendly’s documentation will open.

  • If the argument ‘site’ == “python”, Python’s documentation site will open with the currently used Python version.

  • If the argument ‘site’ == “bug”, the Issues page for Friendly on Github will open.

  • If the argument ‘site’ == “email”, the default email client should open with Friendly’s developer’s address already filled in.