enh(#311): Usability improvements

- Better debug logging config
- Helpful message when it crashes

README.rst

@@ -14,13 +14,6 @@ SIERRA (reSearch pIpEline for Reproducibility, Reusability, and Automation)
 .. |linux-supported| image:: https://svgshare.com/i/Zhy.svg
 .. |osx-supported| image:: https://svgshare.com/i/ZjP.svg
 
-..
-   .. image:: https://img.shields.io/badge/python-3.8-blue.svg
-      :target: https://www.python.org/downloads/release/python-380/
-
-   .. image:: https://img.shields.io/badge/python-3.9-blue.svg
-      :target: https://www.python.org/downloads/release/python-390/
-
 .. |ci-integration-master| image:: https://github.com/jharwell/sierra/actions/workflows/integration-all.yml/badge.svg?branch=master
 .. |ci-analysis-master| image:: https://github.com/jharwell/sierra/actions/workflows/static-analysis.yml/badge.svg?branch=master
 .. |ci-coverage-master| image:: https://coveralls.io/repos/github/jharwell/sierra/badge.svg?branch=master

docs/conf.py

@@ -51,7 +51,7 @@
               'xref',
               'sphinx_last_updated_by_git',
               'sphinx_rtd_theme',
-              'sphinxcontrib.napoleon',
+              'sphinx.ext.napoleon',
               'autoapi.sphinx',
               'sphinx.ext.autosummary']
 

setup.py

@@ -88,6 +88,7 @@
         "psutil",
         "distro",
         "netifaces",
+        "haggis",
 
         "coloredlogs",
         "implements",
@@ -98,7 +99,7 @@
     extras_require={
         "devel": [
             # checkers, CI, etc.
-            'pylint',
+            'pylint==2.14.5',  # Temporarily, until the default 2.15.0 is fixed/superseded
             'pytype',
             'pydocstyle',
             'xenon',

sierra/core/logging.py

@@ -28,25 +28,16 @@
 
 # 3rd party packages
 import coloredlogs
+from haggis import logs
 
 # Project packages
 
-TRACE = logging.DEBUG - 5
-
-
-def initialize(log_level):
-    def log_for_level(self, message, *args, **kwargs):
-        if self.isEnabledFor(TRACE):
-            self._log(TRACE, message, args, **kwargs)
-
-    def log_to_root(message, *args, **kwargs):
-        logging.log(TRACE, message, *args, **kwargs)
-
-    logging.addLevelName(TRACE, "TRACE")
-    setattr(logging, "TRACE", TRACE)
-    setattr(logging.getLoggerClass(), "trace", log_for_level)
-    setattr(logging, "trace", log_to_root)
 
+def initialize(log_level: str):
+    logs.add_logging_level(level_name='TRACE',
+                           level_num=logging.DEBUG - 5,
+                           method_name=None,
+                           if_exists=logs.RAISE)
     # Needed for static analysis (mypy and/or pylint)
     setattr(logging, '_HAS_DYNAMIC_ATTRIBUTES', True)
 

sierra/main.py

@@ -37,6 +37,8 @@
 import sierra.core.startup
 import sierra.version
 
+kIssuesURL = "https://github.com/jharwell/sierra/issues"
+
 
 class SIERRA():
     """Initialize SIERRA and then launch the pipeline."""
@@ -138,12 +140,31 @@ def __call__(self) -> None:
             sys.exit()
 
 
+def excepthook(exc_type, exc_value, exc_traceback):
+    logging.fatal(("SIERRA has encountered an unexpected error and will now "
+                   "terminate.\n\n"
+                   "If you think this is a bug, please report it at:\n\n%s\n\n"
+                   "When reporting, please include as much information as you "
+                   "can. Ideally:\n\n"
+                   "1. The below traceback.\n"
+                   "2. The exact command you used to run sierra-cli.\n"
+                   "3. sierra-cli's logging output in the terminal.\n\n"
+                   "In some cases, creating a Minimum Working Example (MWE) "
+                   "reproducing the error with specific input files and/or "
+                   "data is also helpful for quick triage and fix.\n"),
+                  kIssuesURL,
+                  exc_info=(exc_type, exc_value, exc_traceback))
+
+
 def main():
     # Necessary on OSX, because python > 3.8 defaults to "spawn" which does not
     # copy loaded modules, which results in the singleton plugin managers not
     # working.
     mp.set_start_method("fork")
 
+    # Nice traceback on unexpected errors
+    sys.excepthook = excepthook
+
     # Bootstrap the cmdline to print version if needed
     bootstrap = cmd.BootstrapCmdline()
     bootstrap_args, _ = bootstrap.parser.parse_known_args()

sierra/version.py

@@ -20,4 +20,4 @@
 
 # Project packages
 
-__version__ = "1.2.22"
+__version__ = "1.2.23"

todo.org

@@ -27,8 +27,8 @@
 files. This will allow me to easily parameterize multiple versions of python,
 AND reduce the # of jobs I need/total workflow runtime on github by a good bit.
 
-** TODO Switch from cmdopts dictionary to a data class with fields--I will get
-WAY better help from the static analyzer
+** TODO Switch from cmdopts dictionary to a data class with fields
+I will get WAY better help from the static analyzer
 
 ** TODO Add quick quick start: a linux VM with SIERRA all set up and ready to go
 
@@ -161,3 +161,9 @@ This really should be there.... And not require a valid --project to be passed.
   cohesion
 ** DONE Make bivariate inter-experiment heatmaps renderable into videos
    CLOSED: [2022-08-25 Thu 12:56]
+** DONE Switch from my logging hack to haggis module
+CLOSED: [2022-10-18 Tue 15:02]
+Does what I do, but much better
+
+** DONE Add sys.excepthook hook asking the user to file a bug.
+CLOSED: [2022-10-18 Tue 15:02]