armi: 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.
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.
About this issue
- Original URL
- State: closed
- Created 3 years ago
- Comments: 18 (18 by maintainers)
Sorry to bring up a dead thread. But we found that even importing armi in
conf.py, not even configuring anything, was enough to triggerSo if we have a library that uses armi, and we want to extract its version in our docs, our
conf.pyis currently something likeThe workaround is to not import the package, but this makes dynamic access of the release / version string more difficult
@jakehader I am of two minds when it comes to the
extrachange 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, andstacklevel. 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
runLoganyway, 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.
Closing this issue with resolution of opening a “Lessons Learned” Wiki page on https://github.com/terrapower/armi/wiki/Lessons-Learned to hopefully prevent future users from this same issue. I will close out the corresponding PR.