Added section Automatic Traceback Handler to traceback.rst. It desc…

…ribes a method to automatically install the rich.traceback without having to include the code in your modules.
jizongFox · Oct 9, 2021 · 510cec7 · 510cec7
1 parent 18bedc6
commit 510cec7
Showing 1 changed file with 24 additions and 2 deletions.
diff --git 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 <https://github.com/willmcgugan/rich/blob/master/examples/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)
+        console.print_exception(max_frames=20)
+