Warning

This documentation needs to, and is about to be updated significantly.

Public API

Note

The following is extracted from public_api.py. Please feel free to make suggestions if you believe that other functions should be added to this public API.

Important

Sphynx processes automatically the information from the module. If you want to use functions from the public API, ignore the .public_api part of the names and use simply friendly_traceback.some_function().

public_api.py

With the exception of some Friendly-console related classes or functions, this module includes all the functions that are part of the public API and can be directly used, as in:

import friendly_traceback
friendly_traceback.some_function()

instead of:

import friendly_traceback
friendly_traceback.public_api.some_function()
# or
friendly_traceback.some_inner_module.some_function()
friendly_traceback.public_api.advanced_check_syntax(*, source=None, filename='Fake filename', path=None, verbosity=None, lang=None)[source]

This uses Python’s compile() builtin which does some analysis of its code argument and will raise an exception if it identifies some syntax errors, but also some less common “overflow” and “value” errors.

Compared with check_syntax(), the prefix advanced_ simply refers to the greater number of arguments, which are specified as keywords-only arguments.

This function can either be used on a file, using the path argument, or on some code passed as a string, using the source argument. For the latter case, one can also specify a corresponding filename: this could be useful if this function is invoked from a GUI-based editor.

Note that the path argument, if provided, takes precedence over the source argument.

Two additional named arguments, verbosity and lang, can be provided to temporarily set the values to be used during this function call. The original values are restored at the end.

If friendly-traceback exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call.

Returns a tuple containing a code object and a filename if no exception has been raised, False otherwise.

friendly_traceback.public_api.check_syntax(filename, lang=None)[source]

Given a filename (relative or absolute path), this function calls the more keyword-based advanced_check_syntax(), and will raise an exception if it identifies some syntax errors, but also some less common “overflow” and “value” errors. advanced_check_syntax() provides a more flexibility

If friendly-traceback exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call.

Returns False if problems have been found, None otherwise.

friendly_traceback.public_api.clear_traceback()[source]

Clears the existing traceback.

friendly_traceback.public_api.copy_traceback_info(info)[source]

Copy the traceback info obtained from another source.

friendly_traceback.public_api.exclude_file_from_traceback(full_path)[source]

Exclude a file from appearing in a traceback generated by Friendly-traceback. Note that verbosity level=0 is the traceback generated by Python and is unaffected by this.

friendly_traceback.public_api.exec_code(*, source=None, path=None, verbosity=None, lang=None)[source]

This uses check_syntax to see if the code is valid and, if so, executes it into an empty dict as globals. If no exception is raised, this dict is returned. If an exception is raised, False is returned.

It can either be used on a file, using the path argument, or on some code passed as a string, using the source argument.

Note that the path argument, if provided, takes precedence over the source argument.

Two additional named arguments, verbosity and lang, can be provided to temporarily set the values to be used during this function call. The original values are restored at the end.

If friendly-traceback exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call.

friendly_traceback.public_api.explain(redirect=None)[source]

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

friendly_traceback.public_api.get_lang()[source]

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.

friendly_traceback.public_api.get_level()[source]

Deprecated: use get_verbosity instead

Returns the verbosity level currently used.

friendly_traceback.public_api.get_output(flush=True)[source]

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 overriden if desired.

friendly_traceback.public_api.get_stream()[source]

Returns the value of the current stream used for output.

friendly_traceback.public_api.get_verbosity()[source]

Returns the verbosity level currently used.

friendly_traceback.public_api.highlight_source(linenumber, index, lines, offset=None)[source]

Extracts a few relevant lines from a file content given as a list of lines, adding line number information and identifying a particular line.

When dealing with a SyntaxError or its subclasses, offset is an integer normally used by Python to indicate the position of the error with a ^, like:

if True
      ^

which, in this case, points to a missing colon. We use the same representation in this case.

friendly_traceback.public_api.include_file_in_traceback(full_path)[source]

Reverses the effect of exclude_file_from_traceback() so that the file can potentially appear in later tracebacks generated by Friendly-traceback.

A typical pattern might be something like:

import some_module

revert = not is_excluded_file(some_module.__file__)
if revert:
    exclude_file_from_traceback(some_module.__file__)

try:
    some_module.do_something(...)
except Exception:
    friendly_traceback.explain()
finally:
    if revert:
        include_file_in_traceback(some_module.__file__)
friendly_traceback.public_api.install(lang=None, redirect=None, level=None)[source]

Replaces sys.excepthook by friendly_traceback’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

level: verbosity level. See set_level() for details.

hook: exception_hook - if one wants to experiment using

a different one.

friendly_traceback.public_api.is_excluded_file(full_path)[source]

Determines if the file belongs to the group that is excluded from tracebacks.

friendly_traceback.public_api.is_installed()[source]

Returns True if Friendly-traceback is installed, False otherwise

friendly_traceback.public_api.run(filename, lang=None, verbosity=1)[source]

Given a filename (relative or absolute path), this function uses the more complex exec_code() to run a file.

If friendly-traceback exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call. By default, it uses the value of 1 for the verbosity level.

If friendly-traceback exception hook has not been set up prior to calling check_syntax, it will only be used for the duration of this function call.

Returns False if problems have been found, None otherwise.

friendly_traceback.public_api.set_formatter(formatter=None)[source]

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

A custom formatter must accept info as a required arguments as well as arbitrary keyword-based arguments - these are currently subject to change but include level.

friendly_traceback.public_api.set_lang(lang)[source]

Sets the language to be used by gettext.

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

friendly_traceback.public_api.set_level(level)[source]

Deprecated; use set_verbosity() instead.

Sets the verbosity level to be used. The values are as follows:

    0: Normal Python tracebacks
    1: Default - does not need to be specified
    2: Python tracebacks appear before the friendly display
    3: Python tracebacks appended at the end of the friendly display.
    4: Python traceback followed by basic explanation
    5: Only basic explanation
    6: No generic explanation
    7: Python tracebacks appear before the friendly display but
       no generic explanation is included.
    9: Python traceback

The Python tracebacks for level >= 1 are the simulated version.
You can use negative values to show the true Python traceback which
will likely include function calls from friendly-traceback itself.
Thus level -9 is equivalent to level 0.

Other values may be available, as we try to find the most useful
settings for beginners.
friendly_traceback.public_api.set_stream(stream)[source]

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

friendly_traceback.public_api.set_verbosity(level)[source]

Sets the verbosity level to be used. The values are as follows:

0: Normal Python tracebacks
1: Default - does not need to be specified. The normal Python
   traceback is not included in the output.
2: Python tracebacks appear before the friendly display
3: Python tracebacks appended at the end of the friendly display.
4: Python traceback followed by basic explanation only
5: Only basic explanation
6: No generic explanation
7: Python tracebacks appear before the friendly display but
   no generic explanation is included.
9: Python traceback

Other values may be available, as we try to find the most useful settings for beginners.

friendly_traceback.public_api.show_again()[source]

Shows the traceback info again, on the default stream.

Primarily intended to be used when the user changes a verbosity level to view the traceback again.

friendly_traceback.public_api.uninstall()[source]

Resets sys.excepthook to Python’s default