ARMI Application Sphinx Build Error with ARMI Logger

The ARMI framework documents can be built using the make html command within the doc directory. When building the documentation using Sphinx, it imports the ARMI RunLogger during the process. Once ARMI’s logger is imported and configured then the logging is performed from then on with this logger rather than with Python’s standard logger.

A problem arises if any errors are generated from Sphinx, as it expects the logger that is configured to have certain keywords defined in the logger’s log method. Currently, we can see that we implement single and label kwargs that we use internally to catalog the message types as well as to perform some duplication filtering.

https://github.com/terrapower/armi/blob/04526a658dcf59ba1e29c4613374fe23624d33f2/armi/runLog.py#L478-L519

The following table provides the kwargs that are implemented in Python’s standard Logger (see: https://github.com/python/cpython/blob/576e38f9db61ca09ca6dc57ad13b02a7bf9d370a/Lib/logging/__init__.py#L1591-L1615):

Python Version	Logger kwargs
3.4	exc_info, extra, stack_info
3.5	exc_info, extra, stack_info
3.6	exc_info, extra, stack_info
3.7	exc_info, extra, stack_info
3.8	exc_info, extra, stack_info, stacklevel
3.9	exc_info, extra, stack_info, stacklevel
3.10	exc_info, extra, stack_info, stacklevel

Within Python’s Logger implementation, the log method calls the _log method where it uses the exc_info, extra, stack_info, and stacklevel in Python 3.8+. The ARMI framework log method mirrors this implementation by implementing a _log method and calling it, but the main difference is that the Python’s standard log method accepts *args and **kwargs to handle future changes.

To fix this issue with the Sphinx logging, I recommend that we at a minimum implement the extra kwarg to the ARMI framework’s logger. Without this being implemented, I get the following error message when building my ARMI applications documentation:

Exception occurred:
  File "C:\tools\python379\lib\logging\__init__.py", line 1783, in log
    self.logger.log(level, msg, *args, **kwargs)
TypeError: log() got an unexpected keyword argument 'extra'
The full traceback has been saved in C:\Users\jhader\AppData\Local\Temp\sphinx-err-d34y_xg6.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!

This is a pretty simple change, so I will put in a PR for it.

[drewj-usnctech]

Sorry to bring up a dead thread. But we found that even importing armi in conf.py, not even configuring anything, was enough to trigger

  File "/opt/anaconda3/envs/raptor/lib/python3.7/logging/__init__.py", line 1766, in log
    self.logger.log(level, msg, *args, **kwargs)
TypeError: log() got an unexpected keyword argument 'extra'

So if we have a library that uses armi, and we want to extract its version in our docs, our conf.py is currently something like

import demo  # imports armi

release = demo.__version__

The workaround is to not import the package, but this makes dynamic access of the release / version string more difficult

[john-science]

@jakehader I am of two minds when it comes to the extra change to the logger. On the one hand, maybe we should add all four of these two our logger, for future-proofing: exc_info, extra, stack_info, and stacklevel. Generally, that seems like a sound idea. The (potential) down side is having to update all the downstream plugins for another logging feature that doesn’t really help them.

Maybe the next time we need to make a breaking change to runLog anyway, we throw all of those in. That would be a good middle-ground. Of course, that may be a long time from now, which isn’t helpful.

I like that “lessons learned” section you added to the Wiki, by the way.