Basic usage¶

There are various ways of using friendly. I only list here the basic scenarios available from a terminal or from within a Python interpreter. More options are possible, including running from an editor/IDE as described later in this documentation.

For those that know how to run programs from a terminal, I recommend using one of the first three following options.

Execute a Python program, as I have already shown at the beginning:
```
$ python -m friendly example.py
```
You can also start a friendly console:
```
$ python -m friendly
```
Combining the two options above by using Python’s -i flag to start friendly’s console after executing a program:
```
$ python -im friendly example.py
```

All of the above assume that you are using a terminal with a dark background. If you are using a terminal with a light background, you might want to add --style light as a command line option.

More ways to use¶

The following ways of using friendly are described in more details later. I simply list them here as useful summary for experienced Python programmers.

You can use friendly as an exception hook:

import friendly
friendly.install()  # replaces the default sys.excepthook

Starting the console from any Python interpreter:

>>> import friendly
>>> friendly.start_console()

You can also use it to catch exceptions locally:

import friendly

...

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

All of the above support additional options allowing one to select a different language (only French for now) or changing the information that is shown by default.

More information about various additional options is provided later in this documentation. As a shortcut, you can also type python -m friendly -h in a terminal.

Logging¶

You can use friendly with the logging module. Here’s an example, together with the corresponding output:

import friendly
import logging

# Configure as desired before running the code
logging.basicConfig(filename="ignore.log")
friendly.set_lang('fr')  # Just as an example :-)

try:
    import ignore2
except Exception:
    friendly.explain_traceback(redirect="capture")
    # Note: friendly often remove some details from tracebacks
    # to make them more readable. This can be helpful
    # but sometimes we might also need to see the full
    # traceback in log files.
    # For example, compare the path of ignore2.py shown
    # in both tracebacks.
    log = (" Friendly traceback\n" +
              friendly.get_output() +
              "\n----Original traceback-----\n")
    # exc_info=True below will append the original traceback
    logging.error(log, exc_info=True)

And here’s the output:

ERROR:root: Friendly traceback

Traceback (most recent call last):
  File "ignore.py", line 9, in <module>
    import ignore2
  File "CWD:\ignore2.py", line 3, in <module>
    c = a / b
ZeroDivisionError: division by zero

    Une exception de type `ZeroDivisionError` se produit lorsque vous essayez de diviser une valeur
    par zéro soit directement ou en utilisant une autre opération mathématique.

    Vous divisez par le terme suivant

         b

    qui est égal à zéro.

    L'exécution s'est arrêtée à la ligne 9 du fichier ignore.py

        7:
        8: try:
    --> 9:     import ignore2
       10: except Exception:

    Exception levée à la ligne 3 du fichier CWD:\ignore2.py.

       1: a = 1
       2: b = 0
    -->3: c = a / b
              ^^^^^

            a:  1
            b:  0


----Original traceback-----
Traceback (most recent call last):
  File "ignore.py", line 9, in <module>
    import ignore2
  File "C:\Users\andre\github\friendly\ignore2.py", line 3, in <module>
    c = a / b
ZeroDivisionError: division by zero