feat(numpydoc/hooks/validate_docstrings.py): Added a pyproject.toml config option exclude_files that allows regex path exclusions

Solution to Issue #497

Author: mattgebert

doc/validation.rst

@@ -36,6 +36,8 @@ the pre-commit hook as follows:
   expressions ``\.undocumented_method$`` or ``\.__repr__$``. This
   maps to ``numpydoc_validation_exclude`` from the
   :ref:`Sphinx build configuration <validation_during_sphinx_build>`.
+* ``exclude_files``: Exclude file paths matching the regular expressions
+    ``^tests/.*`` or ``^module/gui.*``.
 * ``override_SS05``: Allow docstrings to start with "Process ", "Assess ",
   or "Access ". To override different checks, add a field for each code in
   the form of ``override_<code>`` with a collection of regular expression(s)
@@ -57,6 +59,10 @@ the pre-commit hook as follows:
         '\.undocumented_method$',
         '\.__repr__$',
     ]
+    exclude_files = [ # don't process filepaths that match these regex
+        '^tests/.*',
+        '^module/gui.*',
+    ]
     override_SS05 = [  # override SS05 to allow docstrings starting with these words
         '^Process ',
         '^Assess ',

numpydoc/hooks/validate_docstrings.py

@@ -273,7 +273,12 @@ def parse_config(dir_path: os.PathLike = None) -> dict:
     dict
         Config options for the numpydoc validation hook.
     """
-    options = {"checks": {"all"}, "exclude": set(), "overrides": {}}
+    options = {
+        "checks": {"all"},
+        "exclude": set(),
+        "overrides": {},
+        "exclude_files": set(),
+    }
     dir_path = Path(dir_path).expanduser().resolve()
 
     toml_path = dir_path / "pyproject.toml"
@@ -306,6 +311,13 @@ def extract_check_overrides(options, config_items):
                 else [global_exclusions]
             )
 
+            file_exclusions = config.get("exclude_files", options["exclude_files"])
+            options["exclude_files"] = set(
+                file_exclusions
+                if not isinstance(file_exclusions, str)
+                else [file_exclusions]
+            )
+
             extract_check_overrides(options, config.items())
 
     elif cfg_path.is_file():
@@ -332,6 +344,16 @@ def extract_check_overrides(options, config_items):
             except configparser.NoOptionError:
                 pass
 
+            try:
+                options["exclude_files"] = set(
+                    config.get(numpydoc_validation_config_section, "exclude_files")
+                    .rstrip(",")
+                    .split(",")
+                    or options["exclude_files"]
+                )
+            except configparser.NoOptionError:
+                pass
+
             extract_check_overrides(
                 options, config.items(numpydoc_validation_config_section)
             )
@@ -341,6 +363,7 @@ def extract_check_overrides(options, config_items):
 
     options["checks"] = validate.get_validation_checks(options["checks"])
     options["exclude"] = compile_regex(options["exclude"])
+    options["exclude_files"] = compile_regex(options["exclude_files"])
     return options
 
 
@@ -395,9 +418,12 @@ def run_hook(
     project_root, _ = find_project_root(files)
     config_options = parse_config(config or project_root)
     config_options["checks"] -= set(ignore or [])
+    exclude_re = config_options["exclude_files"]
 
     findings = False
     for file in files:
+        if exclude_re and exclude_re.match(file):
+            continue
         if file_issues := process_file(file, config_options):
             findings = True
 

numpydoc/tests/hooks/test_validate_hook.py

@@ -139,6 +139,45 @@ def test_validate_hook_with_toml_config(example_module, tmp_path, capsys):
     assert capsys.readouterr().err.strip() == expected
 
 
+def test_validate_hook_with_toml_config_exclude_files(example_module, tmp_path, capsys):
+    """
+    Test that a file is correctly processed in the absence of config files
+    with command line ignore options.
+    """
+
+    with open(tmp_path / "pyproject.toml", "w") as config_file:
+        config_file.write(
+            inspect.cleandoc(
+                """
+                [tool.numpydoc_validation]
+                checks = [
+                    "all",
+                    "EX01",
+                    "SA01",
+                    "ES01",
+                ]
+                exclude = '\\.__init__$'
+                override_SS05 = [
+                    '^Creates',
+                ]
+
+                exclude_files = [
+                    '.*/example.*\.py',
+                ]
+                """
+            )
+        )
+
+    expected = inspect.cleandoc(
+        """
+        """
+    )
+
+    return_code = run_hook([example_module], config=tmp_path)
+    assert return_code == 1
+    assert capsys.readouterr().err.strip() == expected
+
+
 def test_validate_hook_with_setup_cfg(example_module, tmp_path, capsys):
     """
     Test that a file is correctly processed with the config coming from