Filters

All classes described here are designed to be used for the watch_filter argument to the watch function and similar.

This argument requires a simple callable which takes two arguments (the Change type and the path as a string) and returns a boolean indicating if the change should be included (True) or ignored (False).

As shown below in Custom Filters, you can either a BaseFilter subclass instance or your own callable.

BaseFilter

Useful base class for creating filters. BaseFilter should be inherited and configured, rather than used directly.

The class supports ignoring files in 3 ways:

ignore_dirs class-attribute

ignore_dirs: Sequence[str] = ()

Full names of directories to ignore, an obvious example would be .git.

ignore_entity_patterns class-attribute

ignore_entity_patterns: Sequence[str] = ()

Patterns of files or directories to ignore, these are compiled into regexes.

"entity" here refers to the specific file or directory - basically the result of path.split(os.sep)[-1], an obvious example would be r'\.py[cod]$'.

ignore_paths class-attribute

ignore_paths: Sequence[Union[str, Path]] = ()

Full paths to ignore, e.g. /home/users/.cache or C:\Users\user\.cache.

__call__

__call__(change: Change, path: str) -> bool

Instances of BaseFilter subclasses can be used as callables.

Parameters:

Name	Type	Description	Default
change	Change	The type of change that occurred, see Change.	required
path	str	the raw path of the file or directory that changed.	required

Returns:

Type	Description
bool	True if the file should be included in changes, False if it should be ignored.

DefaultFilter

DefaultFilter(
    *,
    ignore_dirs: Optional[Sequence[str]] = None,
    ignore_entity_patterns: Optional[Sequence[str]] = None,
    ignore_paths: Optional[
        Sequence[Union[str, Path]]
    ] = None
) -> None

Bases: BaseFilter

The default filter, which ignores files and directories that you might commonly want to ignore.

Parameters:

Name	Type	Description	Default
ignore_dirs	Optional[Sequence[str]]	if not None, overrides the ignore_dirs value set on the class.	None
ignore_entity_patterns	Optional[Sequence[str]]	if not None, overrides the ignore_entity_patterns value set on the class.	None
ignore_paths	Optional[Sequence[Union[str, Path]]]	if not None, overrides the ignore_paths value set on the class.	None

ignore_dirs class-attribute

ignore_dirs: Sequence[str] = (
    "__pycache__",
    ".git",
    ".hg",
    ".svn",
    ".tox",
    ".venv",
    "site-packages",
    ".idea",
    "node_modules",
    ".mypy_cache",
    ".pytest_cache",
    ".hypothesis",
)

Directory names to ignore.

ignore_entity_patterns class-attribute

ignore_entity_patterns: Sequence[str] = (
    "\\.py[cod]$",
    "\\.___jb_...___$",
    "\\.sw.$",
    "~$",
    "^\\.\\#",
    "^\\.DS_Store$",
    "^flycheck_",
)

File/Directory name patterns to ignore.

PythonFilter

PythonFilter(
    *,
    ignore_paths: Optional[
        Sequence[Union[str, Path]]
    ] = None,
    extra_extensions: Sequence[str] = ()
) -> None

Bases: DefaultFilter

A filter for Python files, since this class inherits from DefaultFilter it will ignore files and directories that you might commonly want to ignore as well as filtering out all changes except in Python files (files with extensions ('.py', '.pyx', '.pyd')).

Parameters:

Name	Type	Description	Default
ignore_paths	Optional[Sequence[Union[str, Path]]]	The paths to ignore, see BaseFilter.	None
extra_extensions	Sequence[str]	extra extensions to ignore.	()

ignore_paths and extra_extensions can be passed as arguments partly to support CLI usage where --ignore-paths and --extensions can be passed as arguments.

Custom Filters

Here's an example of a custom filter which extends DefaultFilter to only notice changes to common web files:

from watchfiles import Change, DefaultFilter, watch


class WebFilter(DefaultFilter):
    allowed_extensions = '.html', '.css', '.js'

    def __call__(self, change: Change, path: str) -> bool:
        return (
            super().__call__(change, path) and
            path.endswith(self.allowed_extensions)
        )

for changes in watch('my/web/project', watch_filter=WebFilter()):
    print (changes)

Here's an example of a customer filter which is a simple callable that ignores changes unless they represent a new file being created:

from watchfiles import Change, watch

def only_added(change: Change, path: str) -> bool:
    return change == Change.added

for changes in watch('my/project', watch_filter=only_added):
    print (changes)

For more details, see filters.py.