Added "exclude_files" option for pyproject.toml config usage. (#635)

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

Solution to Issue #497

* fix(test_validate_hook.py): Corrected test for exclude_files toml option, which should have 0 findings

* refactor(test_validate_hook.py): Added extra testcase to verify no-matching exclude_files option

* refactor(test_validate_hook.py): Modified toml exclude_files test mark, to correct parameter order

* refactor(test_validate_hook.py): Change string type

* test(test_validate_hook.py): Added correct pyproject.toml and setup.cfg test cases for the `exclude_files` option

* feat(numpydoc.py): Added config option `numpydoc_validation_exclude_files` for Sphinx plugin

Uses very similar regex processing to `numpydoc_validation_exclude` but instead applies to a module check before any numpydoc validation is performed.

* fix(numpydoc.py): Corrected module path check for `numpydoc_validation_exclude_files` option

* refactor(numpydoc.py): Changed `numpydoc_validation_exclue_files` sphinx option to use `inspect`, and simplified path checking using `__file__`

* fix(Modified-`numpydoc_validation_exclude_files`-option-to-only-activate-if-`numpydoc_validation_checks`-is-not-empty): Mimicing same behaviour as `numpydoc_validation_exclude`

* docs(validation.rst,-install.rst): Added docs for new feature `numpydoc_validation_exclude_files` for Sphinx and `exclude_files` for pyproject.toml

* docs(validation.rst,-install.rst): Fixed indentation and linebreaks to properly format

* chore(numpydoc.py): use package-relative filename instead of absolute.

* docs(validation.rst,-install.rst): indicate relative path not absolute path for `exclude_files` options

Author: mattgebert

doc/install.rst

@@ -139,6 +139,18 @@ numpydoc_validation_exclude : set
     validation.
     Only has an effect when docstring validation is activated, i.e.
     ``numpydoc_validation_checks`` is not an empty set.
+numpydoc_validation_exclude_files : set
+    A container of strings using :py:mod:`re` syntax specifying path patterns to
+    ignore for docstring validation, relative to the package root.
+    For example, to skip docstring validation for all objects in
+    ``tests\``::
+
+        numpydoc_validation_exclude_files = {"^tests/.*$"}
+
+    The default is an empty set meaning no paths are excluded from docstring
+    validation.
+    Only has an effect when docstring validation is activated, i.e.
+    ``numpydoc_validation_checks`` is not an empty set.
 numpydoc_validation_overrides : dict
     A dictionary mapping :ref:`validation checks <validation_checks>` to a
     container of strings using :py:mod:`re` syntax specifying patterns to

doc/validation.rst

@@ -36,6 +36,10 @@ 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 (relative to the package root) matching
+  the regular expressions ``^tests/.*$`` or ``^module/gui.*$``. This maps to
+  ``numpydoc_validation_exclude_files`` from the
+  :ref:`Sphinx build configuration <validation_during_sphinx_build>`.
 * ``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 +61,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/numpydoc.py

@@ -18,15 +18,19 @@
 """
 
 import hashlib
+import importlib
 import inspect
 import itertools
 import pydoc
 import re
+import sys
 from collections.abc import Callable
 from copy import deepcopy
+from pathlib import Path
 
 from docutils.nodes import Text, citation, comment, inline, reference, section
 from sphinx.addnodes import desc_content, pending_xref
+from sphinx.application import Sphinx as SphinxApp
 from sphinx.util import logging
 
 from . import __version__
@@ -52,7 +56,7 @@ def _traverse_or_findall(node, condition, **kwargs):
     )
 
 
-def rename_references(app, what, name, obj, options, lines):
+def rename_references(app: SphinxApp, what, name, obj, options, lines):
     # decorate reference numbers so that there are no duplicates
     # these are later undecorated in the doctree, in relabel_references
     references = set()
@@ -114,7 +118,7 @@ def is_docstring_section(node):
     return False
 
 
-def relabel_references(app, doc):
+def relabel_references(app: SphinxApp, doc):
     # Change 'hash-ref' to 'ref' in label text
     for citation_node in _traverse_or_findall(doc, citation):
         if not _is_cite_in_numpydoc_docstring(citation_node):
@@ -141,7 +145,7 @@ def matching_pending_xref(node):
             ref.replace(ref_text, new_text.copy())
 
 
-def clean_backrefs(app, doc, docname):
+def clean_backrefs(app: SphinxApp, doc, docname):
     # only::latex directive has resulted in citation backrefs without reference
     known_ref_ids = set()
     for ref in _traverse_or_findall(doc, reference, descend=True):
@@ -161,7 +165,7 @@ def clean_backrefs(app, doc, docname):
 DEDUPLICATION_TAG = "    !! processed by numpydoc !!"
 
 
-def mangle_docstrings(app, what, name, obj, options, lines):
+def mangle_docstrings(app: SphinxApp, what, name, obj, options, lines):
     if DEDUPLICATION_TAG in lines:
         return
     show_inherited_class_members = app.config.numpydoc_show_inherited_class_members
@@ -190,6 +194,38 @@ def mangle_docstrings(app, what, name, obj, options, lines):
         title_re = re.compile(pattern, re.IGNORECASE | re.DOTALL)
         lines[:] = title_re.sub("", u_NL.join(lines)).split(u_NL)
     else:
+        # Test the obj to find the module path, and skip the check if it's path is matched by
+        # numpydoc_validation_exclude_files
+        if (
+            app.config.numpydoc_validation_exclude_files
+            and app.config.numpydoc_validation_checks
+        ):
+            excluder = app.config.numpydoc_validation_files_excluder
+            module = inspect.getmodule(obj)
+            try:
+                # Get the module relative path from the name
+                if module:
+                    mod_path = Path(module.__file__)
+                    package_rel_path = mod_path.parent.relative_to(
+                        Path(
+                            importlib.import_module(
+                                module.__name__.split(".")[0]
+                            ).__file__
+                        ).parent
+                    ).as_posix()
+                    module_file = mod_path.as_posix().replace(
+                        mod_path.parent.as_posix(), ""
+                    )
+                    path = package_rel_path + module_file
+                else:
+                    path = None
+            except AttributeError as e:
+                path = None
+
+            if path and excluder and excluder.search(path):
+                # Skip validation for this object.
+                return
+
         try:
             doc = get_doc_object(
                 obj, what, u_NL.join(lines), config=cfg, builder=app.builder
@@ -239,7 +275,7 @@ def mangle_docstrings(app, what, name, obj, options, lines):
     lines += ["..", DEDUPLICATION_TAG]
 
 
-def mangle_signature(app, what, name, obj, options, sig, retann):
+def mangle_signature(app: SphinxApp, what, name, obj, options, sig, retann):
     # Do not try to inspect classes that don't define `__init__`
     if inspect.isclass(obj) and (
         not hasattr(obj, "__init__")
@@ -273,7 +309,7 @@ def _clean_text_signature(sig):
     return start_sig + sig + ")"
 
 
-def setup(app, get_doc_object_=get_doc_object):
+def setup(app: SphinxApp, get_doc_object_=get_doc_object):
     if not hasattr(app, "add_config_value"):
         return None  # probably called by nose, better bail out
 
@@ -299,6 +335,7 @@ def setup(app, get_doc_object_=get_doc_object):
     app.add_config_value("numpydoc_xref_ignore", set(), True, types=[set, str])
     app.add_config_value("numpydoc_validation_checks", set(), True)
     app.add_config_value("numpydoc_validation_exclude", set(), False)
+    app.add_config_value("numpydoc_validation_exclude_files", set(), False)
     app.add_config_value("numpydoc_validation_overrides", dict(), False)
 
     # Extra mangling domains
@@ -309,7 +346,7 @@ def setup(app, get_doc_object_=get_doc_object):
     return metadata
 
 
-def update_config(app, config=None):
+def update_config(app: SphinxApp, config=None):
     """Update the configuration with default values."""
     if config is None:  # needed for testing and old Sphinx
         config = app.config
@@ -342,6 +379,21 @@ def update_config(app, config=None):
         )
         config.numpydoc_validation_excluder = exclude_expr
 
+    # Generate the regexp for files to ignore during validation
+    if isinstance(config.numpydoc_validation_exclude_files, str):
+        raise ValueError(
+            f"numpydoc_validation_exclude_files must be a container of strings, "
+            f"e.g. [{config.numpydoc_validation_exclude_files!r}]."
+        )
+
+    config.numpydoc_validation_files_excluder = None
+    if config.numpydoc_validation_exclude_files:
+        exclude_files_expr = re.compile(
+            r"|".join(exp for exp in config.numpydoc_validation_exclude_files)
+        )
+        config.numpydoc_validation_files_excluder = exclude_files_expr
+
+    # Generate the regexp for validation overrides
     for check, patterns in config.numpydoc_validation_overrides.items():
         config.numpydoc_validation_overrides[check] = re.compile(
             r"|".join(exp for exp in patterns)

numpydoc/tests/hooks/test_validate_hook.py

@@ -246,3 +246,69 @@ def test_validate_hook_exclude_option_setup_cfg(example_module, tmp_path, capsys
     return_code = run_hook([example_module], config=tmp_path)
     assert return_code == 1
     assert capsys.readouterr().err.strip() == expected
+
+
+@pytest.mark.parametrize(
+    "regex, expected_code",
+    [(".*(/|\\\\)example.*\.py", 0), (".*/non_existent_match.*\.py", 1)],
+)
+def test_validate_hook_exclude_files_option_pyproject(
+    example_module, regex, expected_code, tmp_path
+):
+    """
+    Test that the hook correctly processes the toml config and either includes
+    or excludes files based on the `exclude_files` option.
+    """
+
+    with open(tmp_path / "pyproject.toml", "w") as config_file:
+        config_file.write(
+            inspect.cleandoc(
+                f"""
+                [tool.numpydoc_validation]
+                checks = [
+                    "all",
+                    "EX01",
+                    "SA01",
+                    "ES01",
+                ]
+                exclude = '\\.__init__$'
+                override_SS05 = [
+                    '^Creates',
+                ]
+                exclude_files = [
+                    '{regex}',
+                ]"""
+            )
+        )
+
+    return_code = run_hook([example_module], config=tmp_path)
+    assert return_code == expected_code  # Should not-report/report findings.
+
+
+@pytest.mark.parametrize(
+    "regex, expected_code",
+    [(".*(/|\\\\)example.*\.py", 0), (".*/non_existent_match.*\.py", 1)],
+)
+def test_validate_hook_exclude_files_option_setup_cfg(
+    example_module, regex, expected_code, tmp_path
+):
+    """
+    Test that the hook correctly processes the setup config and either includes
+    or excludes files based on the `exclude_files` option.
+    """
+
+    with open(tmp_path / "setup.cfg", "w") as config_file:
+        config_file.write(
+            inspect.cleandoc(
+                f"""
+                [tool:numpydoc_validation]
+                checks = all,EX01,SA01,ES01
+                exclude = \\.NewClass$,\\.__init__$
+                override_SS05 = ^Creates
+                exclude_files = {regex}
+                """
+            )
+        )
+
+    return_code = run_hook([example_module], config=tmp_path)
+    assert return_code == expected_code  # Should not-report/report findings.

numpydoc/tests/test_docscrape.py

@@ -1593,6 +1593,7 @@ def __init__(self, a, b):
             # numpydoc.update_config fails if this config option not present
             self.numpydoc_validation_checks = set()
             self.numpydoc_validation_exclude = set()
+            self.numpydoc_validation_exclude_files = set()
             self.numpydoc_validation_overrides = dict()
 
     xref_aliases_complete = deepcopy(DEFAULT_LINKS)