More documentation changes but includes a change to config.py that

[pyutils.git] / src / pyutils / bootstrap.py

diff --git a/src/pyutils/bootstrap.py b/src/pyutils/bootstrap.py
index 5a596150201dcd10d32584c1f0524b55c7bce186..3ee5f1fa6c7c4f13a913c0222b908a0698a699b6 100644 (file)
--- a/src/pyutils/bootstrap.py
+++ b/src/pyutils/bootstrap.py
@@ -2,21 +2,38 @@
 
 # © 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 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).
+"""
+If you decorate your main method (i.e. program entry point) like this::
+
+    @bootstrap.initialize
+    def main():
+        whatever
+
+...you will get:
+
+    * automatic support for :py:mod:`pyutils.config` (argument parsing, see
+      that module for details),
+    * The ability to break into pdb on unhandled exceptions (which is
+      enabled/disabled via the commandline flag `--debug_unhandled_exceptions`),
+    * automatic logging support from :py:mod:`pyutils.logging` controllable
+      via several commandline flags,
+    * the ability to optionally enable whole-program code profiling and reporting
+      when you run your code using commandline flag `--run_profiler`,
+    * the ability to optionally enable import auditing via the commandline flag
+      `--audit_import_events`.  This logs a message whenever a module is imported
+      *after* the bootstrap module itself is loaded.  Note that other modules may
+      already be loaded when bootstrap is loaded and these imports will not be
+      logged.  If you're trying to debug import events or dependency problems,
+      I suggest putting bootstrap very early in your import list and using this
+      flag.
+    * optional memory profiling for your program set via the commandline flag
+      `--trace_memory`.  This provides a report of python memory utilization
+      at program termination time.
+    * the ability to set the global random seed via commandline flag for
+      reproducable runs (as long as subsequent code doesn't reset the seed)
+      using the `--set_random_seed` flag,
+    * automatic program timing and reporting logged to the INFO log,
+    * more verbose error handling and reporting.
 
 """
 
@@ -254,9 +271,8 @@ def dump_all_objects() -> None:
 
 def initialize(entry_point):
     """
-    Remember to initialize config, initialize logging, set/log a random
-    seed, etc... before running main.  If you use this decorator around
-    your main, like this::
+    Do whole program setup and instrumentation.  See module comments for
+    details.  To use::
 
         from pyutils import bootstrap
 
@@ -266,21 +282,6 @@ def initialize(entry_point):
 
         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)