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.

Everything about the interactive friendly console¶

Note

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 friendly-traceback code.

Note that, in addition to the functions shown below, when using friendly instead of friendly-traceback in a given environment, some additional functions might be included that are specific to that environment.

This module includes functions that can be used in a friendly console or in other interactive environments such as in a Jupyter notebook.

If you intend to use friendly_traceback in an interactive environment, you should use friendly instead, as in:

from friendly.ipython import ...
# or
from friendly.jupyter import ...
# etc.

Since this documentation is generated automatically by Sphinx using friendly_traceback code, it will not contain all the relevant functions specific to a given environment. To find out about what functions are available in such environments, do the following:

prompt>> from friendly.X import Friendly
prompt>> Friendly
# The output will include the required information

disable()[source]¶: Disable friendly-traceback exception hook

enable()[source]¶: Enable friendly-traceback exception hook

explain(index=-1, include='explain')[source]¶

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

Return type: None

friendly_tb(index=-1)[source]¶

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

Return type: None

get_include()[source]¶

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

Return type: Literal[‘message’, ‘hint’, ‘what’, ‘why’, ‘where’, ‘friendly_tb’, ‘python_tb’, ‘debug_tb’, ‘explain’, ‘no_tb’]

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 seen by the end user: if the translations do not exist for that language, the default English strings are used.

Return type: str

hint(index=-1)[source]¶

Shows hint/suggestion if available.

Return type: None

python_tb(index=-1)[source]¶

Shows the Python traceback, excluding files from friendly itself.

Return type: None

set_debug(flag=True)[source]¶

This sets the value of the debug flag for the current session.

Return type: None

set_formatter(formatter=None)[source]¶

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

Return type: None

set_include(include)[source]¶

Specifies the information to include in the traceback.

Parameters: include (Literal[‘message’, ‘hint’, ‘what’, ‘why’, ‘where’, ‘friendly_tb’, ‘python_tb’, ‘debug_tb’, ‘explain’, ‘no_tb’]) – one of the following allowed values: message, message_plus, hint, what, why, where, friendly_tb, python_tb, debug_tb, detailed_tb, explain, no_tb
Return type: None

set_lang(lang='en')[source]¶

Sets the language to be used for the display.

Parameters: lang (str) – If no translations exist for that language, the original English strings will be used. If a value of None is used, a list of available languages is returned.
Return type: Optional[List[str]]

show_paths()[source]¶

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.

Return type: None

what(exception_or_index=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.

Return type: None

where(index=-1, more=False)[source]¶

Shows the information about where the exception occurred

Return type: None

why(index=-1)[source]¶

Shows the likely cause of the exception.

Return type: None

www(site_or_index=-1)[source]¶

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_or_index is not specified, and an exception or a warning has been raised, an internet search will be done using the exception message of the last exception or warning as the search string.
If the argument site_or_index is not specified, and NO exception has been raised, Friendly’s documentation will open.
If the argument site_or_index == “friendly”, Friendly’s documentation will open.
If the argument site_or_index == “python”, Python’s documentation site will open with the currently used Python version.
If the argument site_or_index == “bug”, the Issues page for Friendly on GitHub will open.
If the argument site_or_index == “email”, the default email client should open with Friendly’s developer’s address already filled in.
If the argument site_or_index is an integer representing an item in the recorded history, an internet search will be done using the exception message of the corresponding item as the search string.

Return type: None