watchdog.events

module:

watchdog.events

synopsis:

File system events and event handlers.

author:

yesudeep@google.com (Yesudeep Mangalapilly)

author:

Mickaël Schoentgen <contact@tiger-222.fr>

Event Classes

class watchdog.events.FileSystemEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: object

Represents a file system event that is triggered when a change occurs on the monitored file system.

FileSystemEvent instances are mutable, so avoid using them as dictionary keys or set members: mutating an instance after insertion can silently break lookups.

is_directory: bool = False

True if event was triggered for a directory; False otherwise.

is_synthetic: bool = False

True if event was synthesized; False otherwise. These are events that weren’t actually broadcast by the OS, but are presumed to have happened based on other, actual events.

class watchdog.events.FileSystemMovedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing any kind of file system movement.

class watchdog.events.FileMovedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemMovedEvent

File system event representing file movement on the file system.

class watchdog.events.DirMovedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemMovedEvent

File system event representing directory movement on the file system.

is_directory: bool = True

True if event was triggered for a directory; False otherwise.

class watchdog.events.FileModifiedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing file modification on the file system.

class watchdog.events.DirModifiedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing directory modification on the file system.

is_directory: bool = True

True if event was triggered for a directory; False otherwise.

class watchdog.events.FileCreatedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing file creation on the file system.

class watchdog.events.FileClosedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing file close on the file system.

Emitted only by InotifyObserver on Linux.

class watchdog.events.FileClosedNoWriteEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing an unmodified file close on the file system.

Emitted only by InotifyObserver on Linux.

class watchdog.events.FileOpenedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing file open on the file system.

Emitted only by InotifyObserver on Linux.

class watchdog.events.DirCreatedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing directory creation on the file system.

is_directory: bool = True

True if event was triggered for a directory; False otherwise.

class watchdog.events.FileDeletedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing file deletion on the file system.

class watchdog.events.DirDeletedEvent(src_path: bytes | str, dest_path: bytes | str = '', is_synthetic: bool = False)

Bases: FileSystemEvent

File system event representing directory deletion on the file system.

is_directory: bool = True

True if event was triggered for a directory; False otherwise.

Event Handler Classes

class watchdog.events.FileSystemEventHandler

Bases: object

Base file system event handler that you can override methods from.

dispatch(event: FileSystemEvent) → None

Dispatches events to the appropriate methods.

Parameters:

event (watchdog.events.FileSystemEvent) – The event object representing the file system event.

on_any_event(event: FileSystemEvent) → None

Catch-all event handler.

Parameters:

event (watchdog.events.FileSystemEvent) – The event object representing the file system event.

on_closed(event: FileClosedEvent) → None

Called when a file opened for writing is closed.

Emitted only by InotifyObserver on Linux.

Parameters:

event (watchdog.events.FileClosedEvent) – Event representing file closing.

on_closed_no_write(event: FileClosedNoWriteEvent) → None

Called when a file opened for reading is closed.

Emitted only by InotifyObserver on Linux.

Parameters:

event (watchdog.events.FileClosedNoWriteEvent) – Event representing file closing.

on_created(event: DirCreatedEvent | FileCreatedEvent) → None

Called when a file or directory is created.

Parameters:

event (watchdog.events.DirCreatedEvent or watchdog.events.FileCreatedEvent) – Event representing file/directory creation.

on_deleted(event: DirDeletedEvent | FileDeletedEvent) → None

Called when a file or directory is deleted.

Parameters:

event (watchdog.events.DirDeletedEvent or watchdog.events.FileDeletedEvent) – Event representing file/directory deletion.

on_modified(event: DirModifiedEvent | FileModifiedEvent) → None

Called when a file or directory is modified.

Parameters:

event (watchdog.events.DirModifiedEvent or watchdog.events.FileModifiedEvent) – Event representing file/directory modification.

on_moved(event: DirMovedEvent | FileMovedEvent) → None

Called when a file or a directory is moved or renamed.

Parameters:

event (watchdog.events.DirMovedEvent or watchdog.events.FileMovedEvent) – Event representing file/directory movement.

on_opened(event: FileOpenedEvent) → None

Called when a file is opened.

Emitted only by InotifyObserver on Linux.

Parameters:

event (watchdog.events.FileOpenedEvent) – Event representing file opening.

class watchdog.events.PatternMatchingEventHandler(*, patterns: list[str] | None = None, ignore_patterns: list[str] | None = None, ignore_directories: bool = False, case_sensitive: bool = False)

Bases: FileSystemEventHandler

Matches given patterns with file paths associated with occurring events. Uses pathlib’s PurePath.match() method. patterns and ignore_patterns are expected to be a list of strings.

property case_sensitive: bool

(Read-only) True if path names should be matched sensitive to case; False otherwise.

dispatch(event: FileSystemEvent) → None

Dispatches events to the appropriate methods.

Parameters:

event (watchdog.events.FileSystemEvent) – The event object representing the file system event.

property ignore_directories: bool

(Read-only) True if directories should be ignored; False otherwise.

property ignore_patterns: list[str] | None

(Read-only) Patterns to ignore matching event paths.

property patterns: list[str] | None

(Read-only) Patterns to allow matching event paths.

class watchdog.events.RegexMatchingEventHandler(*, regexes: list[str] | None = None, ignore_regexes: list[str] | None = None, ignore_directories: bool = False, case_sensitive: bool = False)

Bases: FileSystemEventHandler

Matches given regexes with file paths associated with occurring events. Uses the re module.

property case_sensitive: bool

(Read-only) True if path names should be matched sensitive to case; False otherwise.

dispatch(event: FileSystemEvent) → None

Dispatches events to the appropriate methods.

Parameters:

event (watchdog.events.FileSystemEvent) – The event object representing the file system event.

property ignore_directories: bool

(Read-only) True if directories should be ignored; False otherwise.

property ignore_regexes: list[Pattern[str]]

(Read-only) Regexes to ignore matching event paths.

property regexes: list[Pattern[str]]

(Read-only) Regexes to allow matching event paths.

class watchdog.events.LoggingEventHandler(*, logger: Logger | None = None)

Bases: FileSystemEventHandler

Logs all the events captured.

on_closed(event: FileClosedEvent) → None

Called when a file opened for writing is closed.

Emitted only by InotifyObserver on Linux.

Parameters:

event (watchdog.events.FileClosedEvent) – Event representing file closing.

on_closed_no_write(event: FileClosedNoWriteEvent) → None

Called when a file opened for reading is closed.

Emitted only by InotifyObserver on Linux.

Parameters:

event (watchdog.events.FileClosedNoWriteEvent) – Event representing file closing.

on_created(event: DirCreatedEvent | FileCreatedEvent) → None

Called when a file or directory is created.

Parameters:

event (watchdog.events.DirCreatedEvent or watchdog.events.FileCreatedEvent) – Event representing file/directory creation.

on_deleted(event: DirDeletedEvent | FileDeletedEvent) → None

Called when a file or directory is deleted.

Parameters:

event (watchdog.events.DirDeletedEvent or watchdog.events.FileDeletedEvent) – Event representing file/directory deletion.

on_modified(event: DirModifiedEvent | FileModifiedEvent) → None

Called when a file or directory is modified.

Parameters:

event (watchdog.events.DirModifiedEvent or watchdog.events.FileModifiedEvent) – Event representing file/directory modification.

on_moved(event: DirMovedEvent | FileMovedEvent) → None

Called when a file or a directory is moved or renamed.

Parameters:

event (watchdog.events.DirMovedEvent or watchdog.events.FileMovedEvent) – Event representing file/directory movement.

on_opened(event: FileOpenedEvent) → None

Called when a file is opened.

Emitted only by InotifyObserver on Linux.

Parameters:

event (watchdog.events.FileOpenedEvent) – Event representing file opening.