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.

Public API

Before getting Sphinx to document the public API automatically, I need to let you in on a little secret: occasionally, friendly will lie to you. Furthermore, I encourage you to do the same.

Actually, if you have read the section Multiple tracebacks, you already have seen that the traceback shown usually does not include modules from friendly itself. You can do the same for your own modules using something like the following:

import my_module
friendly.add_excluded_path(my_module.__file__)

Without further ado, here’s the API automatically obtained by Sphinx from the source code.

friendly.__init__.py

With the exceptions of the functions that are specific to the console, this module contains all the functions that are part of the public API. While Friendly is still considered to be in alpha stage, we do attempt to avoid creating incompatibility for the functions here when introducing changes.

The goal is to be even more careful to avoid introducing incompatibilities when reaching beta stage, and planning to be always backward compatible starting at version 1.0 – except possibly for the required minimal Python version.

Friendly is currently compatible with Python versions 3.6 or newer.

If you find that some additional functionality would be useful to have as part of the public API, please let us know.

exclude_directory_from_traceback(dir_name)

Exclude all files found in a given directory, including sub-directories, from appearing in a traceback generated by Friendly. Note that this does not apply to the true Python traceback obtained using “debug_tb”.

exclude_file_from_traceback(full_path)

Exclude a file from appearing in a traceback generated by Friendly. Note that this does not apply to the true Python traceback obtained using “debug_tb”.

explain_traceback(redirect=None)

Replaces a standard traceback by a friendlier one, giving more information about a given exception than a standard traceback. Note that this excludes SystemExit and KeyboardInterrupt which are re-raised.

By default, the output goes to sys.stderr or to some other stream set to be the default by another API call. However, if:

redirect = some_stream

is specified, the output goes to that stream, but without changing the global settings.

If the string "capture" is given as the value for redirect, the output is saved and can be later retrieved by get_output().

get_include()

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

get_lang()

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.

get_output(flush=True)

Returns the result of captured output as a string which can be written anywhere desired.

By default, flushes all the captured content. However, this can be overridden if desired.

get_stream()

Returns the value of the current stream used for output.

install(lang=None, redirect=None, include='explain', _debug=None)

Replaces sys.excepthook by friendly’s own version. Intercepts, and provides an explanation for all Python exceptions except for SystemExist and KeyboardInterrupt.

The optional arguments are:

lang: language to be used for translations. If not available,

English will be used as a default.

redirect: stream to be used to send the output.

The default is sys.stderr

include: controls the amount of information displayed. See set_include() for details.

is_installed()

Returns True if Friendly is installed, False otherwise.

run(filename, lang=None, include=None, args=None, console=True, formatter='bw', redirect=None, background=None)

Given a filename (relative or absolute path) ending with the “.py” extension, this function uses the more complex exec_code() to run a file.

If console is set to False, run() returns an empty dict if a SyntaxError was raised, otherwise returns the dict in which the module (filename) was executed.

If console is set to True (the default), the execution continues as an interactive session in a Friendly console, with the module dict being used as the locals dict.

Other arguments include:

lang: language used; currently only 'en' (default) and 'fr' are available.

include: specifies what information is to be included if an exception is raised; the default is "friendly_tb" if console is set to True, otherwise it is "explain"

args: strings tuple that is passed to the program as though it was run on the command line as follows:

python filename.py arg1 arg2 ...

use_rich: False by default. Set it to True if Rich is available and the environment supports it.

theme: Theme to be used with Rich. Currently only "dark", the default, and "light" are available. "light" is meant for light coloured background and has not been extensively tested.

set_formatter(formatter=None, **kwargs)

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.

set_include(include)

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’

set_lang(lang='en')

Sets the language to be used for the display.

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

set_stream(redirect=None)

Sets the stream to which the output should be directed.

If the string "capture" is given as argument, the output is saved and can be later retrieved by get_output().

If no argument is given, the default stream (stderr) is set.

start_console(local_vars=None, formatter='bw', include='friendly_tb', lang='en', banner=None, color_schemes=None, background=None, displayhook=None)

Starts a Friendly console.

uninstall()

Resets sys.excepthook to Python’s default.