Switch on logging by default when running Finesse interactively
Refs #190 (closed). The way the logging was configured up until 3b28a4cc was to switch it on by default at the
WARNING level. This was problematic in hindsight because it (a) broke pytest's own log capturing (it was impossible to display logs when running pytest no matter which flags you passed), (b) broke the rule of thumb of the Python logging system that libraries should not configure their own logging, and (c) made calls to the convenience function
logging.basicConfig no-ops because there would already be a configured handler (it only configures if it doesn't find an existing handler).
The changes in 3b28a4cc were to remove the configuration of a stream handler in
finesse.__init__. This fixed two of the three issues above. Issue (c) still doesn't work because as per Python logging guidelines
finesse.__init__ still configures a null handler to avoid warnings getting issued for uncaught log messages, which would be the case if the user doesn't configure a log handler in their own code - calls to
basicConfig should from Python 3.8 include a
force=True flag to work around this... a bit convoluted, but this is apparently how it's supposed to be done.
The problem now is how to show warnings to the user by default, which we have agreed in the past is definitely what we want, as long as users are using Finesse via a Jupyter notebook or other interactive means.
Kat scripts run via CLI
The new CLI configures logging to show warnings and errors by default. If users write a kat script and run it via the CLI, this will "just work".
Kat scripts parsed via Python / Python API used directly in .py files
User scripts (ones that
import finesse in a normal Python file) now don't show logs unless they configure logging in their script directly, e.g. with
import logging then
logging.basicConfig(..., force=True). This allows advanced users to handle the logging their own intended way, such as to log to a file instead of stderr, and is the way the Python logging system is intended to be used.
This is not ideal for intermediate users who may wish to use the Python API or parse kat script inside their own Python script, but want to see log messages warning them about unstable cavities etc. We should in this case make it easy for them to configure logging with the 95% most common options via a call to something like
init_logging() the same way we do with
init_plotting() (perhaps we want to merge these into
init_interactive(logging=True, plotting=True, debug=False) or similar).
I am not sure how logging works now when Finesse gets used inside a notebook. In any case what we should definitely do is autodetect whether the user is inside Jupyter or another interactive environment and configure logging for them, just like we already do for (not) showing tracebacks, unless these environments already do something like that themselves.
Ensure Finesse used via IPython terminals and Jupyter notebooks has logging at
WARNINGlevel automatically enabled
- Provide a mechanism to easily switch on Finesse stderr logging inside user Python scripts
- Document how to enable/disable logging in various environments
- Add developer documentation to explain the logging behaviour since it's not necessarily intuitive (at least not to Sean).