Catch and log warnings with context from NumPyDoc

Author: lagru

src/docstub-stubs/_docstrings.pyi

@@ -2,6 +2,7 @@
 
 import logging
 import traceback
+import warnings
 from collections.abc import Generator, Iterable
 from dataclasses import dataclass, field
 from functools import cached_property

src/docstub/_docstrings.py

@@ -2,6 +2,7 @@
 
 import logging
 import traceback
+import warnings
 from dataclasses import dataclass, field
 from functools import cached_property
 
@@ -366,14 +367,20 @@ def __init__(self, docstring, *, matcher=None, reporter=None, stats=None):
         stats : ~.Stats, optional
         """
         self.docstring = docstring
-        self.np_docstring = npds.NumpyDocString(docstring)
         self.matcher = matcher or TypeMatcher()
         self.stats = Stats() if stats is None else stats
 
         if reporter is None:
             reporter = ContextReporter(logger=logger, line=0)
         self.reporter = reporter.copy_with(logger=logger)
 
+        with warnings.catch_warnings(record=True) as records:
+            self.np_docstring = npds.NumpyDocString(docstring)
+        for message in records:
+            short = "Warning in NumPyDoc while parsing docstring"
+            details = message.message.args[0]
+            self.reporter.warn(short, details=details)
+
     @cached_property
     def attributes(self):
         """Return the attributes found in the docstring.

tests/test_docstrings.py

@@ -282,3 +282,23 @@ def test_combined_numpydoc_params(self):
 
         assert "d" not in annotations.parameters
         assert "e" not in annotations.parameters
+
+    @pytest.mark.filterwarnings("default:Unknown section:UserWarning:numpydoc")
+    def test_unknown_section_logged(self, caplog):
+        docstring = dedent(
+            """
+            Parameters
+            ----------
+            a : bool
+
+            To Do
+            -----
+            An unknown section
+            """
+        )
+        annotations = DocstringAnnotations(docstring)
+        assert len(annotations.parameters) == 1
+        assert annotations.parameters["a"].value == "bool"
+
+        assert caplog.messages == ["Warning in NumPyDoc while parsing docstring"]
+        assert caplog.records[0].details == "Unknown section To Do"