traceback.rst

Traceback

Rich can render Python tracebacks with syntax highlighting and formatting. Rich tracebacks are easier to read and show more code than standard Python tracebacks.

To see an example of a Rich traceback, running the following command:

python -m rich.traceback

Printing tracebacks

The ~rich.console.Console.print_exception method will print a traceback for the current exception being handled. Here's an example:

from rich.console import Console
console = Console()

try:
    do_something()
except Exception:
    console.print_exception(show_locals=True)

The show_locals=True parameter causes Rich to display the value of local variables for each frame of the traceback.

See exception.py for a larger example.

Traceback Handler

Rich can be installed as the default traceback handler so that all uncaught exceptions will be rendered with highlighting. Here's how:

from rich.traceback import install
install(show_locals=True)

There are a few options to configure the traceback handler, see ~rich.traceback.install for details.

Automatic Traceback Handler

In some cases you may want to have the traceback handler installed automatically without having to worry about importing the code in your module. You can do that by modifying the sitecustomize.py in your virtual environment. Typically it would be located in your virtual environment path, underneath the site-packages folder, something like this:

./.venv/lib/python3.9/site-packages/sitecustomize.py

In most cases this file will not exist. If it doesn't exist, you can create it by:

$ touch .venv/lib/python3.9/site-packages/sitecustomize.py

Add the following code to the file:

from rich.traceback import install
install(show_locals=True)

At this point, the traceback will be installed for any code that is run within the virtual environment.

Note

If you plan on sharing your code, it is probably best to include the traceback install in your main entry point module.

Suppressing Frames

If you are working with a framework (click, django etc), you may only be interested in seeing the code from your own application within the traceback. You can exclude framework code by setting the suppress argument on Traceback, install, Console.print_exception, and RichHandler, which should be a list of modules or str paths.

Here's how you would exclude click from Rich exceptions:

import click
from rich.traceback import install
install(suppress=[click])

Suppressed frames will show the line and file only, without any code.

Max Frames

A recursion error can generate very large tracebacks that take a while to render and contain a lot of repetitive frames. Rich guards against this with a max_frames argument, which defaults to 100. If a traceback contains more than 100 frames then only the first 50, and last 50 will be shown. You can disable this feature by setting max_frames to 0.

Here's an example of printing a recursive error:

from rich.console import Console


def foo(n):
    return bar(n)


def bar(n):
    return foo(n)


console = Console()

try:
    foo(1)
except Exception:
    console.print_exception(max_frames=20)

Rendering Rich Exceptions

You can create exceptions that implement protocol, which would be rendered when presented in a traceback.

Here's an example that renders the exception's message in a ~rich.panel.Panel with an ASCII box:

from rich.box import ASCII
from rich.console import Console
from rich.panel import Panel


class MyAwesomeException(Exception):
    def __init__(self, message: str):
        super().__init__(message)
        self.message = message

    def __rich__(self):
        return Panel(self.message, title="My Awesome Exception", box=ASCII)


def do_something():
    raise MyAwesomeException("Something went wrong")

console = Console()
try:
    do_something()
except Exception:
    console.print_exception()