watchdog.observers.api

Immutables

class watchdog.observers.api.ObservedWatch(path: str | Path, *, recursive: bool, event_filter: list[type[FileSystemEvent]] | None = None, follow_symlink: bool = False)

Bases: object

An scheduled watch.

Parameters:

• path (str or pathlib.Path) – Path string.

• recursive (bool) – True if watch is recursive; False otherwise.

• event_filter (Iterable[watchdog.events.FileSystemEvent] | None) – Optional collection of watchdog.events.FileSystemEvent to watch.

• follow_symlink (bool) – True if symlinks are followed; False otherwise.

property event_filter: frozenset[type[FileSystemEvent]] | None

Collection of event types watched for the path

property follow_symlink: bool

Determines whether symlink are followed.

property is_recursive: bool

Determines whether subdirectories are watched for the path.

property key: tuple[str, bool, frozenset[type[FileSystemEvent]] | None, bool]

A tuple key identifying the watch (path, recursive, event_filter, follow_symlink).

property path: str

The path that this watch monitors.

Collections

class watchdog.observers.api.EventQueue(maxsize: int = 0)

Bases: SkipRepeatsQueue

Thread-safe event queue based on a special queue that skips adding the same event (watchdog.events.FileSystemEvent) multiple times consecutively. Thus avoiding dispatching multiple event handling calls when multiple identical events are produced quicker than an observer can consume them.

Parameters:

maxsize (int) – Maximum number of items allowed in the queue. If <= 0, the queue size is infinite.

Classes

class watchdog.observers.api.EventEmitter(event_queue: EventQueue, watch: ObservedWatch, *, timeout: float = 1.0, event_filter: list[type[FileSystemEvent]] | None = None)

Bases: BaseThread

Producer thread base class subclassed by event emitters that generate events and populate a queue with them.

Parameters:

• event_queue (EventQueue) – The event queue to populate with generated events.

• watch (ObservedWatch) – The watch to observe and produce events for.

• timeout (float) – Timeout (in seconds) between successive attempts at reading events.

• event_filter (Iterable[watchdog.events.FileSystemEvent] | None) – Collection of event types to emit, or None for no filtering (default).

queue_event(event: FileSystemEvent) → None

Queues a single event.

Parameters:

event (An instance of watchdog.events.FileSystemEvent or a subclass.) – Event to be queued.

queue_events(timeout: float) → None

Override this method to populate the event queue with events per interval period.

Parameters:

timeout (float) – Timeout (in seconds) between successive attempts at reading events.

run() → None

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

property timeout: float

Blocking timeout for reading events.

property watch: ObservedWatch

The watch associated with this emitter.

class watchdog.observers.api.EventDispatcher(*, timeout: float = 1.0)

Bases: BaseThread

Consumer thread base class subclassed by event observer threads that dispatch events from an event queue to appropriate event handlers.

Parameters:

timeout (float) – Timeout value (in seconds) passed to emitters constructions in the child class BaseObserver.

dispatch_events(event_queue: EventQueue) → None

Override this method to consume events from an event queue, blocking on the queue for the specified timeout before raising queue.Empty.

Parameters:

event_queue (EventQueue) – Event queue to populate with one set of events.

Raises:

queue.Empty

property event_queue: EventQueue

The event queue which is populated with file system events by emitters and from which events are dispatched by a dispatcher thread.

run() → None

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

stop() → None

Signals the thread to stop.

stop_event = <object object>

Event inserted into the queue to signal a requested stop.

property timeout: float

Timeout value to construct emitters with.

class watchdog.observers.api.BaseObserver(emitter_class: type[EventEmitter], *, timeout: float = 1.0)

Bases: EventDispatcher

Base observer.

Parameters:

• emitter_class (type[EventEmitter]) – The class of the emitter to use (e.g., a subclass of EventEmitter).

• timeout (float) – The timeout (in seconds) for the observer to wait on events.

add_handler_for_watch(event_handler: FileSystemEventHandler, watch: ObservedWatch) → None

Adds a handler for the given watch.

Parameters:

• event_handler (watchdog.events.FileSystemEventHandler or a subclass) – An event handler instance that has appropriate event handling methods which will be called by the observer in response to file system events.

• watch (An instance of ObservedWatch or a subclass of ObservedWatch) – The watch to add a handler for.

dispatch_events(event_queue: EventQueue) → None

Override this method to consume events from an event queue, blocking on the queue for the specified timeout before raising queue.Empty.

Parameters:

event_queue (EventQueue) – Event queue to populate with one set of events.

Raises:

queue.Empty

property emitters: set[EventEmitter]

Returns event emitter created by this observer.

on_thread_stop() → None

Override this method instead of stop(). stop() calls this method.

This method is called immediately after the thread is signaled to stop.

remove_handler_for_watch(event_handler: FileSystemEventHandler, watch: ObservedWatch) → None

Removes a handler for the given watch.

Parameters:

• event_handler (watchdog.events.FileSystemEventHandler or a subclass) – An event handler instance that has appropriate event handling methods which will be called by the observer in response to file system events.

• watch (An instance of ObservedWatch or a subclass of ObservedWatch) – The watch to remove a handler for.

schedule(event_handler: FileSystemEventHandler, path: str | Path, *, recursive: bool = False, event_filter: list[type[FileSystemEvent]] | None = None, follow_symlink: bool = False) → ObservedWatch

Schedules watching a path and calls appropriate methods specified in the given event handler in response to file system events.

Parameters:

• event_handler (watchdog.events.FileSystemEventHandler or a subclass) – An event handler instance that has appropriate event handling methods which will be called by the observer in response to file system events.

• path (str or pathlib.Path) – Directory path that will be monitored.

• recursive (bool) – True if events will be emitted for sub-directories traversed recursively; False otherwise.

• event_filter (Iterable[watchdog.events.FileSystemEvent] | None) – Collection of event types to emit, or None for no filtering (default).

• follow_symlink (bool) – True if symlinks should be followed; False otherwise.

Returns:

An ObservedWatch object instance representing a watch.

start() → None

Start the thread’s activity.

It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

This method will raise a RuntimeError if called more than once on the same thread object.

unschedule(watch: ObservedWatch) → None

Unschedules a watch.

Parameters:

watch (An instance of ObservedWatch or a subclass of ObservedWatch) – The watch to unschedule.

unschedule_all() → None

Unschedules all watches and detaches all associated event handlers.