Port inline comments for ignoring checks to sphinx side.

Author: stefmolin

numpydoc/hooks/validate_docstrings.py

@@ -6,7 +6,6 @@
 import os
 import re
 import sys
-import tokenize
 
 try:
     import tomllib
@@ -20,11 +19,6 @@
 
 from .. import docscrape, validate
 from .utils import find_project_root
-from ..utils import get_validation_checks
-
-
-# inline comments that can suppress individual checks per line
-IGNORE_COMMENT_PATTERN = re.compile("(?:.* numpydoc ignore[=|:] ?)(.+)")
 
 
 class AstValidator(validate.Validator):
@@ -171,7 +165,7 @@ def _ignore_issue(self, node: ast.AST, check: str) -> bool:
         Return
         ------
         bool
-            Whether the issue should be exluded from the report.
+            Whether the issue should be excluded from the report.
         """
         if check not in self.config["checks"]:
             return True
@@ -328,7 +322,7 @@ def extract_check_overrides(options, config_items):
         except configparser.NoSectionError:
             pass
 
-    options["checks"] = get_validation_checks(options["checks"])
+    options["checks"] = validate.get_validation_checks(options["checks"])
     options["exclude"] = compile_regex(options["exclude"])
     return options
 
@@ -352,23 +346,10 @@ def process_file(filepath: os.PathLike, config: dict) -> "list[list[str]]":
     with open(filepath) as file:
         module_node = ast.parse(file.read(), filepath)
 
-    with open(filepath) as file:
-        numpydoc_ignore_comments = {}
-        last_declaration = 1
-        declarations = ["def", "class"]
-        for token in tokenize.generate_tokens(file.readline):
-            if token.type == tokenize.NAME and token.string in declarations:
-                last_declaration = token.start[0]
-            if token.type == tokenize.COMMENT:
-                match = re.match(IGNORE_COMMENT_PATTERN, token.string)
-                if match:
-                    rules = match.group(1).split(",")
-                    numpydoc_ignore_comments[last_declaration] = rules
-
     docstring_visitor = DocstringVisitor(
         filepath=str(filepath),
         config=config,
-        numpydoc_ignore_comments=numpydoc_ignore_comments,
+        numpydoc_ignore_comments=validate.extract_ignore_validation_comments(filepath),
     )
     docstring_visitor.visit(module_node)
 

numpydoc/numpydoc.py

@@ -34,8 +34,7 @@
     raise RuntimeError("Sphinx 5 or newer is required")
 
 from .docscrape_sphinx import get_doc_object
-from .utils import get_validation_checks
-from .validate import validate, ERROR_MSGS
+from .validate import validate, ERROR_MSGS, get_validation_checks
 from .xref import DEFAULT_LINKS
 from . import __version__
 

numpydoc/tests/test_utils.py

@@ -1,10 +1,75 @@
 import pytest
 import warnings
-import numpydoc.validate
+
+from numpydoc import validate
 import numpydoc.tests
 
 
-validate_one = numpydoc.validate.validate
+validate_one = validate.validate
+
+ALL_CHECKS = set(validate.ERROR_MSGS.keys())
+
+
+@pytest.mark.parametrize(
+    ["checks", "expected"],
+    [
+        [{"all"}, ALL_CHECKS],
+        [set(), set()],
+        [{"EX01"}, {"EX01"}],
+        [{"EX01", "SA01"}, {"EX01", "SA01"}],
+        [{"all", "EX01", "SA01"}, ALL_CHECKS - {"EX01", "SA01"}],
+        [{"all", "PR01"}, ALL_CHECKS - {"PR01"}],
+    ],
+)
+def test_utils_get_validation_checks(checks, expected):
+    """Ensure check selection is working."""
+    assert validate.get_validation_checks(checks) == expected
+
+
+@pytest.mark.parametrize(
+    "checks",
+    [
+        {"every"},
+        {None},
+        {"SM10"},
+        {"EX01", "SM10"},
+    ],
+)
+def test_get_validation_checks_validity(checks):
+    """Ensure that invalid checks are flagged."""
+    with pytest.raises(ValueError, match="Unrecognized validation code"):
+        _ = validate.get_validation_checks(checks)
+
+
+@pytest.mark.parametrize(
+    ["file_contents", "expected"],
+    [
+        ["class MyClass:\n    pass", {}],
+        ["class MyClass:  # numpydoc ignore=EX01\n    pass", {1: ["EX01"]}],
+        [
+            "class MyClass:  # numpydoc ignore= EX01,SA01\n    pass",
+            {1: ["EX01", "SA01"]},
+        ],
+        [
+            "class MyClass:\n    def my_method():  # numpydoc ignore:EX01\n        pass",
+            {2: ["EX01"]},
+        ],
+        [
+            "class MyClass:\n    def my_method():  # numpydoc ignore: EX01,PR01\n        pass",
+            {2: ["EX01", "PR01"]},
+        ],
+        [
+            "class MyClass:  # numpydoc ignore=GL08\n    def my_method():  # numpydoc ignore:EX01,PR01\n        pass",
+            {1: ["GL08"], 2: ["EX01", "PR01"]},
+        ],
+    ],
+)
+def test_extract_ignore_validation_comments(tmp_path, file_contents, expected):
+    """Test that extraction of validation ignore comments is working."""
+    filepath = tmp_path / "ignore_comments.py"
+    with open(filepath, "w") as file:
+        file.write(file_contents)
+    assert validate.extract_ignore_validation_comments(filepath) == expected
 
 
 class GoodDocStrings:

numpydoc/tests/test_validate.py

@@ -5,13 +5,19 @@
 Call ``validate(object_name_to_validate)`` to get a dictionary
 with all the detected errors.
 """
+
+from copy import deepcopy
+from typing import Set
 import ast
 import collections
 import importlib
 import inspect
+import os
 import pydoc
 import re
 import textwrap
+import tokenize
+
 from .docscrape import get_doc_object
 
 
@@ -101,6 +107,72 @@
 # Ignore these when evaluating end-of-line-"." checks
 IGNORE_STARTS = (" ", "* ", "- ")
 
+# inline comments that can suppress individual checks per line
+IGNORE_COMMENT_PATTERN = re.compile("(?:.* numpydoc ignore[=|:] ?)(.+)")
+
+
+def extract_ignore_validation_comments(filepath: os.PathLike) -> dict[int, list[str]]:
+    """
+    Extract inline comments indicating certain validation checks should be ignored.
+
+    Parameters
+    ----------
+    filepath : os.PathLike
+        Path to the file being inspected.
+
+    Returns
+    -------
+    dict[int, list[str]]
+        Mapping of line number to a list of checks to ignore.
+    """
+    with open(filepath) as file:
+        numpydoc_ignore_comments = {}
+        last_declaration = 1
+        declarations = ["def", "class"]
+        for token in tokenize.generate_tokens(file.readline):
+            if token.type == tokenize.NAME and token.string in declarations:
+                last_declaration = token.start[0]
+            if token.type == tokenize.COMMENT:
+                match = re.match(IGNORE_COMMENT_PATTERN, token.string)
+                if match:
+                    rules = match.group(1).split(",")
+                    numpydoc_ignore_comments[last_declaration] = rules
+    return numpydoc_ignore_comments
+
+
+def get_validation_checks(validation_checks: Set[str]) -> Set[str]:
+    """
+    Get the set of validation checks to report on.
+
+    Parameters
+    ----------
+    validation_checks : set[str]
+        A set of validation checks to report on. If the set is ``{"all"}``,
+        all checks will be reported. If the set contains just specific checks,
+        only those will be reported on. If the set contains both ``"all"`` and
+        specific checks, all checks except those included in the set will be
+        reported on.
+
+    Returns
+    -------
+    set[str]
+        The set of validation checks to report on.
+    """
+    valid_error_codes = set(ERROR_MSGS.keys())
+    if "all" in validation_checks:
+        block = deepcopy(validation_checks)
+        validation_checks = valid_error_codes - block
+
+    # Ensure that the validation check set contains only valid error codes
+    invalid_error_codes = validation_checks - valid_error_codes
+    if invalid_error_codes:
+        raise ValueError(
+            f"Unrecognized validation code(s) in numpydoc_validation_checks "
+            f"config value: {invalid_error_codes}"
+        )
+
+    return validation_checks
+
 
 def error(code, **kwargs):
     """
@@ -506,9 +578,15 @@ def validate(obj_name, validator_cls=None, **validator_kwargs):
     else:
         doc = validator_cls(obj_name=obj_name, **validator_kwargs)
 
+    # module docstring will be lineno 0, which we change to 1 for readability of the output
+    ignore_validation_comments = extract_ignore_validation_comments(
+        doc.source_file_name
+    ).get(doc.source_file_def_line or 1, [])
+
     errs = []
     if not doc.raw_doc:
-        errs.append(error("GL08"))
+        if "GL08" not in ignore_validation_comments:
+            errs.append(error("GL08"))
         return {
             "type": doc.type,
             "docstring": doc.clean_doc,
@@ -630,6 +708,9 @@ def validate(obj_name, validator_cls=None, **validator_kwargs):
 
     if not doc.examples:
         errs.append(error("EX01"))
+
+    errs = [err for err in errs if err[0] not in ignore_validation_comments]
+
     return {
         "type": doc.type,
         "docstring": doc.clean_doc,