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.

Other details for advanced users¶

Note

Some additional information might be available from the command line:

python -m friendly -h

Where the output is written?¶

By default, friendly tracebacks are written to sys.stderr. However, it is possible to override this choice, as follows:

friendly.set_stream(stream)

Thus, the default amounts to:

friendly.set_stream(sys.stderr)

A special option exists to capture the output as a string:

friendly.set_stream("capture")

Later, this captured output can be retrieved using:

output = friendly.get_output()

# equivalent to
output = friendly.get_output(flush=True)

The value shown for the flush parameter is the default; this means that the output will be cleared once it has been retrieved. If this is not the desired behaviour, simply use flush=False.

Language used¶

The language used can be explicitly set as follows:

friendly.set_lang("fr")  # two-letter code for French

The language currently used can be obtained using:

lang = friendly.get_lang()

If the language requested does not exist, no error is raised nor any warning given, but the choice reverts to the default (English). More information on the choice of language (localization) can be found in the section about design.

As an exception hook¶

When “installing” friendly, one can use various optional parameters:

friendly.install(lang="fr", redirect="capture", include="explain")

This is equivalent to writing:

friendly.install()
friendly.set_lang("fr")
friendly.set_stream("capture")
friendly.set_include("explain")

Catching exception locally¶

As mentioned before, another way to use friendly is to catch exceptions where they are expected to arise, such as:

try:
    # Some code
except Exception:
    friendly.explain_traceback()

This uses the default of writing to sys.stderr. One can also temporarily redirect the output to any stream:

try:
    # Some code
except Exception:
    friendly.explain_traceback(redirect=stream)

By default, friendly takes its information from sys.exc_info(). It may happen that this is not what we want to show. For example, the showtraceback method in Python’s code.py replaces one of the items prior to showing the traceback to the user; we currently also do something similar in friendly’s own console.

Finally, if one wishes to temporarily change some other option mentioned above, it can be done as in the following example:

try:
    # Some code
except Exception:
    lang = friendly.get_lang()
    friendly.set_lang("fr")
    friendly.explain_traceback()
    friendly.set_lang(lang)

Running another script¶

We have already given an example of running another script:

$ python -m friendly demos/hello.py

Hello world!
Running as main!

What if the separate script has its own command line arguments? If they are simply positional arguments, you can simply tack them on at the end of the argument list. An example can be found in the demos/ directory, which can be run directly or using friendly.

$ python demos/adder.py 1 2 3
The sum is 6

$ python -m friendly demos/adder.py 1 2 3
The sum is 6.0

Note that this works even if you specify command line arguments that are specific to friendly:

$ python -m friendly --lang fr demos/adder.py 1 2 3
The sum is 6.0

However, what if one wants to run a script that uses optional named arguments similarly to how friendly can use --lang and other optional arguments? In this case, use -- to separate the list of arguments to be used by the script from those written previously and intended to be used by friendly:

$ python -m friendly --lang fr demos/adder.py -- --to_int 1 2 3
The sum is 6

An alterative is to use either a sitecustomize.py or a usercustomize.py file, as described in the Python documentation.

For example, you can use the following approach.

Create a usercustomize.py file whose content is the following:

import friendly
friendly.install()
# specify other desired options here

Set the PYTHONPATH environment variable to that directory. On Windows, this can be done by navigating to that directory and writing:
```
set PYTHONPATH=%CD%
```

You can now run your script normally: friendly exception handling will be used by default on it.