X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=bootstrap.py;h=e9b2033569c0ce552eb56ff785400930f2ce96a9;hb=HEAD;hp=52359f11ab77b64e4fd604528e8cdad54e557a33;hpb=5b50a18959c5d68fe8dcaafa5c3852b262130cbc;p=python_utils.git

diff --git a/bootstrap.py b/bootstrap.py
index 52359f1..e9b2033 100644
--- a/bootstrap.py
+++ b/bootstrap.py
@@ -1,13 +1,28 @@
 #!/usr/bin/env python3
 
+# © Copyright 2021-2022, Scott Gasch
+
 """This is a module for wrapping around python programs and doing some
-minor setup and tear down work for them.  With it, you can break into
-pdb on unhandled top level exceptions, profile your code by passing a
-commandline argument in, audit module import events, examine where
-memory is being used in your program, and so on."""
+minor setup and tear down work for them.  With it, you will get:
+
+* The ability to break into pdb on unhandled exceptions,
+* automatic support for :file:`config.py` (argument parsing)
+* automatic logging support for :file:`logging.py`,
+* the ability to enable code profiling,
+* the ability to enable module import auditing,
+* optional memory profiling for your program,
+* ability to set random seed via commandline,
+* automatic program timing and reporting,
+* more verbose error handling and reporting,
+
+Most of these are enabled and/or configured via commandline flags
+(see below).
+
+"""
 
 import functools
 import importlib
+import importlib.abc
 import logging
 import os
 import sys
@@ -89,18 +104,24 @@ def handle_uncaught_exception(exc_type, exc_value, exc_tb):
         sys.__excepthook__(exc_type, exc_value, exc_tb)
         return
     else:
+        import io
+        import traceback
+
+        tb_output = io.StringIO()
+        traceback.print_tb(exc_tb, None, tb_output)
+        print(tb_output.getvalue(), file=sys.stderr)
+        logger.error(tb_output.getvalue())
+        tb_output.close()
+
+        # stdin or stderr is redirected, just do the normal thing
         if not sys.stderr.isatty() or not sys.stdin.isatty():
-            # stdin or stderr is redirected, just do the normal thing
             ORIGINAL_EXCEPTION_HOOK(exc_type, exc_value, exc_tb)
-        else:
-            # a terminal is attached and stderr is not redirected, maybe debug.
-            import traceback
 
-            traceback.print_exception(exc_type, exc_value, exc_tb)
+        else:  # a terminal is attached and stderr isn't redirected, maybe debug.
             if config.config['debug_unhandled_exceptions']:
+                logger.info("Invoking the debugger...")
                 import pdb
 
-                logger.info("Invoking the debugger...")
                 pdb.pm()
             else:
                 ORIGINAL_EXCEPTION_HOOK(exc_type, exc_value, exc_tb)
@@ -193,6 +214,8 @@ for arg in sys.argv:
 
 
 def dump_all_objects() -> None:
+    """Helper code to dump all known python objects."""
+
     messages = {}
     all_modules = sys.modules
     for obj in object.__subclasses__():
@@ -228,8 +251,32 @@ def dump_all_objects() -> None:
 def initialize(entry_point):
     """
     Remember to initialize config, initialize logging, set/log a random
-    seed, etc... before running main.
+    seed, etc... before running main.  If you use this decorator around
+    your main, like this::
+
+        import bootstrap
+
+        @bootstrap.initialize
+        def main():
+            whatever
+
+        if __name__ == '__main__':
+            main()
+
+    You get:
+
+    * The ability to break into pdb on unhandled exceptions,
+    * automatic support for :file:`config.py` (argument parsing)
+    * automatic logging support for :file:`logging.py`,
+    * the ability to enable code profiling,
+    * the ability to enable module import auditing,
+    * optional memory profiling for your program,
+    * ability to set random seed via commandline,
+    * automatic program timing and reporting,
+    * more verbose error handling and reporting,
 
+    Most of these are enabled and/or configured via commandline flags
+    (see below).
     """
 
     @functools.wraps(entry_point)