From 510cec7116dcd64ae6f3da2ae72cada7f36c9e78 Mon Sep 17 00:00:00 2001 From: Troy Williams Date: Sat, 9 Oct 2021 09:37:08 -0400 Subject: [PATCH] Added section `Automatic Traceback Handler` to traceback.rst. It describes a method to automatically install the rich.traceback without having to include the code in your modules. --- docs/source/traceback.rst | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/source/traceback.rst b/docs/source/traceback.rst index 6b1a6f9c..120ca0ce 100644 --- a/docs/source/traceback.rst +++ b/docs/source/traceback.rst @@ -26,7 +26,7 @@ The ``show_locals=True`` parameter causes Rich to display the value of local var See `exception.py `_ for a larger example. -Traceback handler +Traceback Handler ----------------- Rich can be installed as the default traceback handler so that all uncaught exceptions will be rendered with highlighting. Here's how:: @@ -36,6 +36,27 @@ Rich can be installed as the default traceback handler so that all uncaught exce There are a few options to configure the traceback handler, see :func:`~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 ------------------ @@ -73,4 +94,5 @@ Here's an example of printing an recursive error:: try: foo(1) except Exception: - console.print_exception(max_frames=20) \ No newline at end of file + console.print_exception(max_frames=20) +