Use the 'rich' package to create more detailed exception tracebacks

[whart222]

Summary

Use the rich package to create detailed traceback messages

Rationale

Python tracebacks are hard to parse and often not sufficiently informative to support debugging. The 'rich' package includes facilities for generating detailed tracebacks that are (1) easy to read, and (2) show the values of local variables.

Description

I recently saw a really nice traceback generated when running pip with the --debug option. I tracked this down to the rich package. Looking at the pip package (see https://github.com/pypa/pip/blob/29cd0c4eb72458c946ca5d681a3a3a74a015a0d9/src/pip/_vendor/rich/_extension.py#L7), I think the following is enough to setup rich tracebacks:

import rich.traceback
rich.traceback.install(show_locals=True)

See the rich documentation: https://rich.readthedocs.io/en/stable/traceback.html

I'm not sure where it makes sense to include this import, though.

Additional information

None.

[whart222]

Here's a snapshot of the traceback I saw using pip.

[blnicho]

@whart222 that debugging output is really neat! With this issue are you suggesting that we add rich as a hard dependency so that this debugging output is always the default? Could we instead just add an example to the documentation telling users to add the 2 lines above to help with debugging if needed?

[michaelbynum]

I like @blnicho's suggestion.

[whart222]

I agree that adding this to the documentation makes sense.

But I think this is so useful for diagnosing errors that I would always want this feature enabled. Hence, it'd be nice to have a convenient utility function to enable rich traceback messages. This would do the import and install, but wouldn't create a hard dependency. Maybe this would be another optional utility in pyomo.common?

[jsiirola]

I think I would rather support a "Sphinx-like" approach and allow users to inject code into the environment setup process.

We have already been talking about (and drafting implementations) for a per-user config file (sitting in PYOMO_CONFIG_DIR (~/.pyomo on Linux/OSX, and %LOCALAPPDATA% on Windows). That file would allow users to set various defaults (like interface versions, templatization, tee settings, solver-specific default options, etc.). We could add a "setup" field where the user could specify arbitrary python code that we execute when processing pyomo.environ.

This way we don't have to incur the technical debt of supporting a bunch of "one off" options, and leave users the flexibility to setup their environment however they want.

[whart222]

An advantage of a sphinx-like strategy is that the user wouldn't have to remember to initialize features like this in every script.

A disadvantage is that they might forget that they had initialized features, and then struggle to diagnose unexpected behavior.