Merge pull request #191 from facelessuser/feature/excludes

Add exclude option

Author: facelessuser

.coveragerc

@@ -5,3 +5,6 @@ omit=
 [report]
 omit=
     wcmatch/pep562.py
+exclude_lines =
+    pragma: no cover
+    @overload

docs/src/markdown/about/changelog.md

@@ -4,6 +4,9 @@
 
 - **NEW**: Drop support for Python 3.6.
 - **NEW**: Switch to Hatch backend instead of Setuptools.
+- **NEW**: Add new `exclude` option to `fnmatch`, `pathlib`, and `glob` methods that allows exclusion patterns to be
+  specified directly without needing to enable `NEGATE` and prepend patterns with `!`. `exclude` accepts a separate
+  pattern or pattern list. `exclude` should not be used in conjunction with `NEGATE`. One or the other should be used.
 
 ## 8.3
 

docs/src/markdown/fnmatch.md

@@ -54,11 +54,12 @@ be no limit.
 #### `fnmatch.fnmatch` {: #fnmatch}
 
 ```py3
-def fnmatch(filename, patterns, *, flags=0, limit=1000)
+def fnmatch(filename, patterns, *, flags=0, limit=1000, exclude=None)
 ```
 
 `fnmatch` takes a file name, a pattern (or list of patterns), and flags.  It also allows configuring the [max pattern
-limit](#multi-pattern-limits). It will return a boolean indicating whether the file name was matched by the pattern(s).
+limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes a pattern or
+a list of patterns. It will return a boolean indicating whether the file name was matched by the pattern(s).
 
 ```pycon3
 >>> from wcmatch import fnmatch
@@ -74,10 +75,21 @@ When applying multiple patterns, a file matches if it matches any of the pattern
 True
 ```
 
-Exclusion patterns are allowed as well. When exclusion patterns are used in conjunction with inclusion patterns, a file
-will be considered matched if one of the inclusion patterns match **and** none of the exclusion patterns match. If an
-exclusion pattern is given without any inclusion patterns, the pattern will match nothing. Exclusion patterns are meant
-to filter other patterns, not match anything by themselves.
+Exclusions can be used by taking advantage of the `exclude` parameter. It takes a single exclude pattern or a list of
+patterns. Files that match the exclude pattern will not be matched.
+
+```pycon3
+>>> from wcmatch import fnmatch
+>>> fnmatch.fnmatch('test.py', '*', exclude='*.py')
+False
+>>> fnmatch.fnmatch('test.txt', '*', exclude='*.py')
+True
+```
+
+Inline exclusion patterns are allowed as well. When exclusion patterns are used in conjunction with inclusion patterns,
+a file will be considered matched if one of the inclusion patterns match **and** none of the exclusion patterns match.
+If an exclusion pattern is given without any inclusion patterns, the pattern will match nothing. Exclusion patterns are
+meant to filter other patterns, not match anything by themselves.
 
 ```pycon3
 >>> from wcmatch import fnmatch
@@ -107,14 +119,18 @@ True
 !!! new "New 6.0"
     `limit` was added in 6.0.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `fnmatch.filter` {: #filter}
 
 ```py3
-def filter(filenames, patterns, *, flags=0, limit=1000):
+def filter(filenames, patterns, *, flags=0, limit=1000, exclude=None):
 ```
 
 `filter` takes a list of filenames, a pattern (or list of patterns), and flags. It also allows configuring the [max 
-pattern limit](#multi-pattern-limits). It returns a list of all files that matched the pattern(s). The same logic used for
+pattern limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes a
+pattern or a list of patterns.It returns a list of all files that matched the pattern(s). The same logic used for
 [`fnmatch`](#fnmatch) is used for `filter`, albeit more efficient for processing multiple files.
 
 ```pycon3
@@ -126,16 +142,20 @@ pattern limit](#multi-pattern-limits). It returns a list of all files that match
 !!! new "New 6.0"
     `limit` was added in 6.0.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `fnmatch.translate` {: #translate}
 
 ```py3
-def translate(patterns, *, flags=0, limit=1000):
+def translate(patterns, *, flags=0, limit=1000, exclude=None):
 ```
 
 `translate` takes a file pattern (or list of patterns) and flags. It also allows configuring the [max pattern
-limit](#multi-pattern-limits). It returns two lists: one for inclusion patterns and one for exclusion patterns. The
-lists contain the regular expressions used for matching the given patterns. It should be noted that a file is considered
-matched if it matches at least one inclusion pattern and matches **none** of the exclusion patterns.
+limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes a pattern or
+a list of patterns. It returns two lists: one for inclusion patterns and one for exclusion patterns. The lists contain
+the regular expressions used for matching the given patterns. It should be noted that a file is considered matched if it
+matches at least one inclusion pattern and matches **none** of the exclusion patterns.
 
 ```pycon3
 >>> from wcmatch import fnmatch
@@ -165,6 +185,9 @@ we wrap the entire group to be captured: `#!py3 '+(a)'` --> `#!py3 r'((a)+)'`.
 !!! new "New 7.1"
     Translate patterns now provide capturing groups for [`EXTMATCH`](#extmatch) groups.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `fnmatch.escape` {: #escape}
 
 ```py3
@@ -246,6 +269,12 @@ Assuming the `SPLIT` flag, this means using it in a pattern such as `inclusion|!
 If it is desired, you can force exclusion patterns, when no inclusion pattern is provided, to assume all files match
 unless the file matches the excluded pattern. This is done with the [`NEGATEALL`](#negateall) flag.
 
+`NEGATE` enables [`DOTMATCH`](#dotglob) in all exclude patterns, this cannot be disabled. This will not affect the
+inclusion patterns.
+
+If `NEGATE` is set and exclusion patterns are passed via a matching function's `exclude` parameter, `NEGATE` will be
+ignored and the `exclude` patterns will be used instead. Either `exclude` or `NEGATE` should be used, not both.
+
 #### `fnmatch.NEGATEALL, fnmatch.A` {: #negateall}
 
 `NEGATEALL` can force exclusion patterns, when no inclusion pattern is provided, to assume all files match unless the

docs/src/markdown/glob.md

@@ -167,12 +167,13 @@ no limit.
 #### `glob.glob` {: #glob}
 
 ```py3
-def glob(patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000):
+def glob(patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000, exclude=None):
 ```
 
 `glob` takes a pattern (or list of patterns), flags, and an optional root directory (string or path-like object) and/or
-directory file descriptor. It also allows configuring the [max pattern limit](#multi-pattern-limits). When executed it
-will crawl the file system returning matching files.
+directory file descriptor. It also allows configuring the [max pattern limit](#multi-pattern-limits). Exclusion patterns
+can be specified via the `exclude` parameter which takes a pattern or a list of patterns.When executed it will crawl the
+file system returning matching files.
 
 !!! warning "Path-like Input Support"
     Path-like object input support is only available in Python 3.6+ as the path-like protocol was added in Python 3.6.
@@ -299,10 +300,13 @@ Additionally, you can use `dir_fd` and specify a root directory with a directory
 !!! new "New 8.2"
     `dir_fd` parameter was added in 8.2.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `glob.iglob` {: #iglob}
 
 ```py3
-def iglob(patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000):
+def iglob(patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000, exclude=None):
 ```
 
 `iglob` is just like [`glob`](#glob) except it returns an iterator.
@@ -322,15 +326,19 @@ def iglob(patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000):
 !!! new "New 8.2"
     `dir_fd` parameter was added in 8.2.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `glob.globmatch` {: #globmatch}
 
 ```py3
-def globmatch(filename, patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000):
+def globmatch(filename, patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000, exclude=None):
 ```
 
 `globmatch` takes a file name (string or path-like object), a pattern (or list of patterns), flags, and an optional root
-directory and/or file descriptor.  It also allows configuring the [max pattern limit](#multi-pattern-limits). It will
-return a boolean indicating whether the file path was matched by the pattern(s).
+directory and/or file descriptor.  It also allows configuring the [max pattern limit](#multi-pattern-limits). Exclusion
+patterns can be specified via the `exclude` parameter which takes a pattern or a list of patterns. It will return a
+boolean indicating whether the file path was matched by the pattern(s).
 
 ```pycon3
 >>> from wcmatch import glob
@@ -457,16 +465,20 @@ True
 !!! new "New 8.2"
     `dir_fd` parameter was added in 8.2.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `glob.globfilter` {: #globfilter}
 
 ```py3
-def globfilter(filenames, patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000):
+def globfilter(filenames, patterns, *, flags=0, root_dir=None, dir_fd=None, limit=1000, method=None):
 ```
 
 `globfilter` takes a list of file paths (strings or path-like objects), a pattern (or list of patterns), flags, and an
-optional root directory and/or directory file descriptor. It also allows configuring the
-[max pattern limit](#multi-pattern-limits). It returns a list of all files paths that matched the pattern(s). The same
-logic used for [`globmatch`](#globmatch) is used for `globfilter`, albeit more efficient for processing multiple files.
+optional root directory and/or directory file descriptor. It also allows configuring the 
+[max pattern limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes
+a pattern or a list of patterns.It returns a list of all files paths that matched the pattern(s). The same logic used
+for [`globmatch`](#globmatch) is used for `globfilter`, albeit more efficient for processing multiple files.
 
 !!! warning "Path-like Input Support"
     Path-like object input support is only available in Python 3.6+ as the path-like protocol was added in Python 3.6.
@@ -492,16 +504,20 @@ be matched by `GLOBSTAR`. See [`globmatch`](#globmatch) for examples.
 !!! new "New 8.2"
     `dir_fd` parameter was added in 8.2.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `glob.translate` {: #translate}
 
 ```py3
-def translate(patterns, *, flags=0, limit=1000):
+def translate(patterns, *, flags=0, limit=1000, exclude=None):
 ```
 
 `translate` takes a file pattern (or list of patterns) and flags. It also allows configuring the [max pattern
-limit](#multi-pattern-limits). It returns two lists: one for inclusion patterns and one for exclusion patterns. The
-lists contain the regular expressions used for matching the given patterns. It should be noted that a file is considered
-matched if it matches at least one inclusion pattern and matches **none** of the exclusion patterns.
+limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes a pattern or
+a list of patterns. It returns two lists: one for inclusion patterns and one for exclusion patterns. The lists contain
+the regular expressions used for matching the given patterns. It should be noted that a file is considered matched if it
+matches at least one inclusion pattern and matches **none** of the exclusion patterns.
 
 ```pycon3
 >>> from wcmatch import glob
@@ -531,6 +547,9 @@ we wrap the entire group to be captured: `#!py3 '+(a)'` --> `#!py3 r'((a)+)'`.
 !!! new "New 7.1"
     Translate patterns now provide capturing groups for [`EXTGLOB`](#extglob) groups.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `glob.escape` {: #escape}
 
 ```py3
@@ -759,6 +778,9 @@ unless the file matches the excluded pattern. This is done with the [`NEGATEALL`
 `NEGATE` enables [`DOTGLOB`](#dotglob) in all exclude patterns, this cannot be disabled. This will not affect the
 inclusion patterns.
 
+If `NEGATE` is set and exclusion patterns are passed via a matching or glob function's `exclude` parameter, `NEGATE`
+will be ignored and the `exclude` patterns will be used instead. Either `exclude` or `NEGATE` should be used, not both.
+
 #### `glob.NEGATEALL, glob.A` {: #negateall}
 
 `NEGATEALL` can force exclusion patterns, when no inclusion pattern is provided, to assume all files match unless the

docs/src/markdown/pathlib.md

@@ -240,11 +240,12 @@ PosixPath('/usr/local/bin')
 #### `PurePath.match` {: #match}
 
 ```py3
-def match(self, patterns, *, flags=0, limit=1000):
+def match(self, patterns, *, flags=0, limit=1000, exclude=None):
 ```
 
 `match` takes a pattern (or list of patterns), and flags.  It also allows configuring the [max pattern
-limit](#multi-pattern-limits). It will return a boolean indicating whether the object's file path was matched by the
+limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes a pattern or
+a list of patterns. It will return a boolean indicating whether the object's file path was matched by the
 pattern(s).
 
 `match` mimics Python's `pathlib` version of `match`. Python's `match` uses a right to left evaluation. Wildcard Match
@@ -279,15 +280,18 @@ True
 !!! new "New 6.0"
     `limit` was added in 6.0.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `PurePath.globmatch` {: #globmatch}
 
 ```py3
-def globmatch(self, patterns, *, flags=0, limit=1000):
+def globmatch(self, patterns, *, flags=0, limit=1000, exclude=None):
 ```
 
 `globmatch` takes a pattern (or list of patterns), and flags.  It also allows configuring the [max pattern
-limit](#multi-pattern-limits).It will return a boolean indicating whether the objects file path was matched by the
-pattern(s).
+limit](#multi-pattern-limits). Exclusion patterns can be specified via the `exclude` parameter which takes a pattern or
+a list of patterns. It will return a boolean indicating whether the objects file path was matched by the pattern(s).
 
 `globmatch` is similar to [`match`](#match) except it does not use the same recursive logic that
 [`match`](#match) does. In all other respects, it behaves the same.
@@ -310,17 +314,20 @@ True
 !!! new "New 6.0"
     `limit` was added in 6.0.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `Path.glob` {: #glob}
 
 ```py3
-def glob(self, patterns, *, flags=0, limit=1000):
+def glob(self, patterns, *, flags=0, limit=1000, exclude=None):
 ```
 
 `glob` takes a pattern (or list of patterns) and flags. It also allows configuring the [max pattern
 limit](#multi-pattern-limits). It will crawl the file system, relative to the current [`Path`](#path) object,
 returning a generator of [`Path`](#path) objects. If a file/folder matches any regular, inclusion pattern, it is
-considered a match.  If a file matches *any* exclusion pattern (when enabling the [`NEGATE`](#negate) flag), then
-it will not be returned.
+considered a match.  If a file matches *any* exclusion pattern (specified via `exclude` or using negation patterns when
+enabling the [`NEGATE`](#negate) flag), then it will not be returned.
 
 This method calls our own [`iglob`](./glob.md#iglob) implementation, and as such, should behave in the same manner
 in respect to features, the one exception being that instead of returning path strings in the generator, it will return
@@ -340,17 +347,20 @@ working directory.
 !!! new "New 6.0"
     `limit` was added in 6.0.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 #### `Path.rglob` {: #rglob}
 
 ```py3
-def rglob(self, patterns, *, flags=0, path_limit=1000):
+def rglob(self, patterns, *, flags=0, path_limit=1000, exclude=None):
 ```
 
 `rglob` takes a pattern (or list of patterns) and flags. It also allows configuring the [max pattern
 limit](#multi-pattern-limits). It will crawl the file system, relative to the current [`Path`](#path) object,
 returning a generator of [`Path`](#path) objects. If a file/folder matches any regular patterns, it is considered
-a match.  If a file matches *any* exclusion pattern (when enabling the [`NEGATE`](#negate) flag), then it will be
-not be returned.
+a match.  If a file matches *any* exclusion pattern (specified via `exclude` or using negation patterns when enabling
+the [`NEGATE`](#negate) flag), then it will be not be returned.
 
 `rglob` mimics Python's [`pathlib`][pathlib] version of `rglob` in that it uses a recursive logic. What this means is
 that when you are matching a path in the form `some/path/name`, the patterns `name`, `path/name` and `some/path/name`
@@ -370,6 +380,9 @@ the same.
 !!! new "New 6.0"
     `limit` was added in 6.0.
 
+!!! new "New 8.4"
+    `exclude` parameter was added.
+
 ## Flags
 
 #### `pathlib.CASE, pathlib.C` {: #case}
@@ -401,6 +414,9 @@ unless the file matches the excluded pattern. This is done with the [`NEGATEALL`
 `NEGATE` enables [`DOTGLOB`](#dotglob) in all exclude patterns, this cannot be disabled. This will not affect the
 inclusion patterns.
 
+If `NEGATE` is set and exclusion patterns are passed via a matching or glob function's `exclude` parameter, `NEGATE`
+will be ignored and the `exclude` patterns will be used instead. Either `exclude` or `NEGATE` should be used, not both.
+
 #### `pathlib.NEGATEALL, pathlib.A` {: #negateall}
 
 `NEGATEALL` can force exclusion patterns, when no inclusion pattern is provided, to assume all files match unless the