add: excludes option for path glob patterns (#393)

Signed-off-by: Stephen Whitlock <stephen@jshwisolutions.com>

README.rst

@@ -80,40 +80,42 @@ Commandline
 .. code-block:: console
 
     usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a] [-k] [-T]
-                  [-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN]
+                  [-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
                   [path [path ...]]
 
     Check signature params for proper documentation
 
     positional arguments:
-      path                                 directories or files to check
+      path                                  directories or files to check
 
     optional arguments:
-      -h, --help                           show this help message and exit
-      -V, --version                        show program's version number and exit
-      -l, --list-checks                    display a list of all checks and their messages
-      -c, --check-class                    check class docstrings
-      -C, --check-class-constructor        check __init__ methods. Note: mutually incompatible
-                                           with -c
-      -D, --check-dunders                  check dunder methods
-      -m, --check-protected-class-methods  check public methods belonging to protected classes
-      -N, --check-nested                   check nested functions and classes
-      -o, --check-overridden               check overridden methods
-      -p, --check-protected                check protected functions and classes
-      -P, --check-property-returns         check property return values
-      -i, --ignore-no-params               ignore docstrings where parameters are not
-                                           documented
-      -a, --ignore-args                    ignore args prefixed with an asterisk
-      -k, --ignore-kwargs                  ignore kwargs prefixed with two asterisks
-      -T, --ignore-typechecker             ignore checking return values
-      -I, --include-ignored                check files even if they match a gitignore pattern
-      -n, --no-ansi                        disable ansi output
-      -v, --verbose                        increase output verbosity
-      -s STR, --string STR                 string to parse instead of files
-      -d LIST, --disable LIST              comma separated list of rules to disable
-      -t LIST, --target LIST               comma separated list of rules to target
-      -e PATTERN, --exclude PATTERN        regular expression of files or dirs to exclude from
-                                           checks
+      -h, --help                            show this help message and exit
+      -V, --version                         show program's version number and exit
+      -l, --list-checks                     display a list of all checks and their messages
+      -c, --check-class                     check class docstrings
+      -C, --check-class-constructor         check __init__ methods. Note: mutually incompatible
+                                            with -c
+      -D, --check-dunders                   check dunder methods
+      -m, --check-protected-class-methods   check public methods belonging to protected classes
+      -N, --check-nested                    check nested functions and classes
+      -o, --check-overridden                check overridden methods
+      -p, --check-protected                 check protected functions and classes
+      -P, --check-property-returns          check property return values
+      -i, --ignore-no-params                ignore docstrings where parameters are not
+                                            documented
+      -a, --ignore-args                     ignore args prefixed with an asterisk
+      -k, --ignore-kwargs                   ignore kwargs prefixed with two asterisks
+      -T, --ignore-typechecker              ignore checking return values
+      -I, --include-ignored                 check files even if they match a gitignore pattern
+      -n, --no-ansi                         disable ansi output
+      -v, --verbose                         increase output verbosity
+      -s STR, --string STR                  string to parse instead of files
+      -d LIST, --disable LIST               comma separated list of rules to disable
+      -t LIST, --target LIST                comma separated list of rules to target
+      -e PATTERN, --exclude PATTERN         regular expression of files or dirs to exclude from
+                                            checks
+      -E PATH [PATH ...], --excludes PATH [PATH ...]
+                                            path glob patterns to exclude from checks
 
 Options can also be configured with the pyproject.toml file
 

changelog/393.add.md

@@ -0,0 +1 @@
+excludes option for path glob patterns

docsig/_config.py

@@ -157,6 +157,13 @@ def _add_arguments(self) -> None:
             metavar="PATTERN",
             help="regular expression of files or dirs to exclude from checks",
         )
+        self.add_argument(
+            "-E",
+            "--excludes",
+            nargs="+",
+            metavar="PATH",
+            help="path glob patterns to exclude from checks",
+        )
 
         # deprecated
         self.add_argument(

docsig/_core.py

@@ -331,6 +331,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     target: _Messages | None = None,
     disable: _Messages | None = None,
     exclude: str | None = None,
+    excludes: list[str] | None = None,
 ) -> int:
     """Package's core functionality.
 
@@ -367,6 +368,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
     :param disable: List of errors to disable.
     :param exclude: Regular expression of files and dirs to exclude from
         checks.
+    :param excludes: Files or dirs to exclude from checks.
     :return: Exit status for whether test failed or not.
     """
     if list_checks:
@@ -381,6 +383,7 @@ def docsig(  # pylint: disable=too-many-locals,too-many-arguments
         paths = _Paths(
             *tuple(_Path(i) for i in path),
             patterns=patterns,
+            excludes=excludes or [],
             include_ignored=include_ignored,
             verbose=verbose,
         )

docsig/_files.py

@@ -12,6 +12,7 @@
 
 from pathspec import PathSpec as _PathSpec
 from pathspec.patterns import GitWildMatchPattern as _GitWildMatchPattern
+from wcmatch.pathlib import Path as _WcPath
 
 from ._utils import vprint as _vprint
 
@@ -62,12 +63,18 @@ def __init__(self) -> None:
         super().__init__(map(_GitWildMatchPattern, patterns))
 
 
+def _glob(path: _Path, pattern: str) -> bool:
+    # pylint: disable=no-member
+    return _WcPath(str(path)).globmatch(pattern)  # type: ignore
+
+
 class Paths(_t.List[_Path]):  # pylint: disable=too-many-instance-attributes
     """Collect a list of valid paths.
 
     :param paths: Path(s) to parse ``Module``(s) from.
     :param patterns: List pf regular expression of files and dirs to
         exclude from checks.
+    :param excludes: Files or dirs to exclude from checks.
     :param include_ignored: Check files even if they match a gitignore
         pattern.
     :param verbose: increase output verbosity.
@@ -77,20 +84,23 @@ def __init__(  # pylint: disable=too-many-arguments
         self,
         *paths: _Path,
         patterns: list[str],
+        excludes: list[str],
         include_ignored: bool = False,
         verbose: bool = False,
     ) -> None:
         super().__init__()
         self._patterns = patterns
+        self._excludes = excludes
         self._include_ignored = include_ignored
         self._verbose = verbose
         self._gitignore = _Gitignore()
         for path in paths:
             self._populate(path)
 
         for path in list(self):
-            if str(path) != "." and any(
-                _re.match(i, str(path)) for i in self._patterns
+            if str(path) != "." and (
+                any(_re.match(i, str(path)) for i in self._patterns)
+                or any(_glob(path, i) for i in self._excludes)
             ):
                 _vprint(
                     FILE_INFO.format(

docsig/_main.py

@@ -44,4 +44,5 @@ def main() -> str | int:
         target=p.args.target,
         disable=p.args.disable,
         exclude=p.args.exclude,
+        excludes=p.args.excludes,
     )

pyproject.toml

@@ -140,6 +140,7 @@ arcon = ">=0.4.0"
 astroid = "^3.0.1"
 pathspec = "^0.12.1"
 python = "^3.8.1"
+wcmatch = "^8.5.2"
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.4.2"

tests/__init__.py

@@ -59,6 +59,13 @@ def __call__(self, content: str, path: Path = ..., /) -> Path:
 echo "Hello World!"
 """
 TREE = {
+    "file1.txt": [],
+    "file2.txt": [],
+    "file3.txt": [],
+    "file4.txt": [],
+    "file5.txt": [],
+    "file10.txt": [],
+    "file[1].txt": [],
     ".pyaud_cache": {
         "7.5.1": {
             "CACHEDIR.TAG": [WILL_ERROR],