2021-04-05 23:49:45 +02:00
|
|
|
"""
|
|
|
|
Warnings filter extension
|
|
|
|
#########################
|
|
|
|
|
|
|
|
Copyright (c) 2021 Nordic Semiconductor ASA
|
|
|
|
SPDX-License-Identifier: Apache-2.0
|
|
|
|
|
|
|
|
Introduction
|
|
|
|
============
|
|
|
|
|
|
|
|
This Sphinx plugin can be used to filter out warnings that are known to be false
|
|
|
|
positives. The warnings are filtered out based on a set of regular expressions
|
|
|
|
given via an configuration file. The format of the configuration file is a
|
|
|
|
plain-text file where each line consists of a regular expression. Any lines
|
|
|
|
starting with ``#`` will be ignored.
|
|
|
|
|
|
|
|
Configuration options
|
|
|
|
=====================
|
|
|
|
|
|
|
|
- ``warnings_filter_config``: Configuration file.
|
|
|
|
- ``warnings_filter_silent``: Silent flag. If True, warning is hidden. If False
|
|
|
|
the warning is converted to an information message and displayed.
|
|
|
|
"""
|
|
|
|
|
|
|
|
import logging
|
|
|
|
import re
|
2023-07-01 22:16:50 +02:00
|
|
|
from typing import Dict, Any, List, Optional
|
2021-04-05 23:49:45 +02:00
|
|
|
|
|
|
|
from sphinx.application import Sphinx
|
|
|
|
from sphinx.util.logging import NAMESPACE
|
|
|
|
|
|
|
|
|
|
|
|
__version__ = "0.1.0"
|
|
|
|
|
|
|
|
|
|
|
|
class WarningsFilter(logging.Filter):
|
|
|
|
"""Warnings filter.
|
|
|
|
|
|
|
|
Args:
|
|
|
|
expressions: List of regular expressions.
|
|
|
|
silent: If true, warning is hidden, otherwise it is shown as INFO.
|
|
|
|
name: Filter name.
|
|
|
|
"""
|
2023-07-01 22:16:50 +02:00
|
|
|
|
2021-04-05 23:49:45 +02:00
|
|
|
def __init__(self, expressions: List[str], silent: bool, name: str = "") -> None:
|
|
|
|
super().__init__(name)
|
|
|
|
|
|
|
|
self._expressions = expressions
|
|
|
|
self._silent = silent
|
|
|
|
|
|
|
|
def filter(self, record: logging.LogRecord) -> bool:
|
|
|
|
if record.levelno != logging.WARNING:
|
|
|
|
return True
|
|
|
|
|
|
|
|
for expression in self._expressions:
|
2023-06-21 21:49:08 +02:00
|
|
|
# The message isn't always a string so we convert it before regexing as we can only regex strings
|
2023-07-01 22:16:50 +02:00
|
|
|
if expression.match(str(record.msg)):
|
2021-04-05 23:49:45 +02:00
|
|
|
if self._silent:
|
|
|
|
return False
|
|
|
|
else:
|
|
|
|
record.levelno = logging.INFO
|
|
|
|
record.msg = f"Filtered warning: {record.msg}"
|
|
|
|
return True
|
|
|
|
|
|
|
|
return True
|
|
|
|
|
|
|
|
|
2023-07-01 22:16:50 +02:00
|
|
|
class Expression:
|
|
|
|
"""
|
|
|
|
Encapsulate a log filter pattern and track if it ever matches a log line.
|
|
|
|
"""
|
|
|
|
|
|
|
|
def __init__(self, pattern):
|
|
|
|
self.pattern = pattern
|
|
|
|
self.matched = False
|
|
|
|
|
|
|
|
def match(self, str):
|
|
|
|
matches = bool(re.match(self.pattern, str))
|
|
|
|
self.matched = matches or self.matched
|
|
|
|
return matches
|
|
|
|
|
|
|
|
|
2021-04-05 23:49:45 +02:00
|
|
|
def configure(app: Sphinx) -> None:
|
|
|
|
"""Entry point.
|
|
|
|
|
|
|
|
Args:
|
|
|
|
app: Sphinx application instance.
|
|
|
|
"""
|
|
|
|
|
|
|
|
# load expressions from configuration file
|
|
|
|
with open(app.config.warnings_filter_config) as f:
|
|
|
|
expressions = list()
|
|
|
|
for line in f.readlines():
|
2023-07-01 22:16:50 +02:00
|
|
|
if line.strip() and not line.startswith("#"):
|
|
|
|
expressions.append(Expression(line.rstrip()))
|
|
|
|
|
|
|
|
app.env.warnings_filter_expressions = expressions
|
2021-04-05 23:49:45 +02:00
|
|
|
|
|
|
|
# install warnings filter to all the Sphinx logger handlers
|
|
|
|
filter = WarningsFilter(expressions, app.config.warnings_filter_silent)
|
|
|
|
logger = logging.getLogger(NAMESPACE)
|
|
|
|
for handler in logger.handlers:
|
|
|
|
handler.filters.insert(0, filter)
|
|
|
|
|
|
|
|
|
2023-07-01 22:16:50 +02:00
|
|
|
def finished(app: Sphinx, exception: Optional[Exception]):
|
|
|
|
"""
|
|
|
|
Prints out any patterns that have not matched a log line to allow us to clean up any that are not used.
|
|
|
|
"""
|
|
|
|
if exception:
|
|
|
|
# Early exit if there has been an exception as matching data is only
|
|
|
|
# valid for complete builds
|
|
|
|
return
|
|
|
|
|
|
|
|
expressions = app.env.warnings_filter_expressions
|
|
|
|
|
|
|
|
for expression in expressions:
|
|
|
|
if not expression.matched:
|
|
|
|
logging.warning(f"Unused expression: {expression.pattern}")
|
|
|
|
|
|
|
|
|
2021-04-05 23:49:45 +02:00
|
|
|
def setup(app: Sphinx) -> Dict[str, Any]:
|
|
|
|
app.add_config_value("warnings_filter_config", "", "")
|
|
|
|
app.add_config_value("warnings_filter_silent", True, "")
|
|
|
|
|
|
|
|
app.connect("builder-inited", configure)
|
2023-07-01 22:16:50 +02:00
|
|
|
app.connect("build-finished", finished)
|
2021-04-05 23:49:45 +02:00
|
|
|
|
|
|
|
return {
|
|
|
|
"version": __version__,
|
|
|
|
"parallel_read_safe": True,
|
|
|
|
"parallel_write_safe": True,
|
|
|
|
}
|