Change notification support for FS.

This module defines a standard interface for FS subclasses that support change notification callbacks. It also offers some WrapFS subclasses that can simulate such an ability on top of an ordinary FS object.

An FS object that wants to be “watchable” must provide the following methods:

  • add_watcher(callback,path="/",events=None,recursive=True)

    Request that the given callback be executed in response to changes to the given path. A specific set of change events can be specified. This method returns a Watcher object.

  • del_watcher(watcher_or_callback)

    Remove the given watcher object, or any watchers associated with the given callback.

If you would prefer to read changes from a filesystem in a blocking fashion rather than using callbacks, you can use the function ‘iter_changes’ to obtain an iterator over the change events.

class fs.watch.ACCESSED(fs, path)

Event fired when a file’s contents are accessed.

class fs.watch.CLOSED(fs, path)

Event fired when the filesystem is closed.

class fs.watch.CREATED(fs, path)

Event fired when a new file or directory is created.

class fs.watch.ERROR(fs, path)

Event fired when some miscellaneous error occurs.

class fs.watch.EVENT(fs, path)

Base class for change notification events.

class fs.watch.MODIFIED(fs, path, data_changed=False, closed=False)

Event fired when a file or directory is modified.

class fs.watch.MOVED_DST(fs, path, source=None)

Event fired when a file or directory is the target of a move.

class fs.watch.MOVED_SRC(fs, path, destination=None)

Event fired when a file or directory is the source of a move.

class fs.watch.OVERFLOW(fs, path)

Event fired when some events could not be processed.

class fs.watch.PollingWatchableFS(wrapped_fs, poll_interval=300)

FS wrapper simulating watcher callbacks by periodic polling.

This FS wrapper augments the functionality of WatchableFS by periodically polling the underlying FS for changes. It is thus capable of detecting changes made to the underlying FS via other interfaces, albeit with a (configurable) delay to account for the polling interval.

class fs.watch.REMOVED(fs, path)

Event fired when a file or directory is removed.

class fs.watch.WatchableFS(*args, **kwds)

FS wrapper simulating watcher callbacks.

This FS wrapper intercepts method calls that modify the underlying FS and generates appropriate notification events. It thus allows watchers to monitor changes made through the underlying FS object, but not changes that might be made through other interfaces to the same filesystem.

class fs.watch.WatchableFSMixin(*args, **kwds)

Mixin class providing watcher management functions.

add_watcher(callback, path='/', events=None, recursive=True)

Add a watcher callback to the FS.


Delete a watcher callback from the FS.

notify_watchers(event_or_class, path=None, *args, **kwds)

Notify watchers of the given event data.

class fs.watch.WatchedFile(file, fs, path, mode=None)

File wrapper for use with WatchableFS.

This file wrapper provides access to a file opened from a WatchableFS instance, and fires MODIFIED events when the file is modified.

class fs.watch.Watcher(fs, callback, path='/', events=None, recursive=True)

Object encapsulating filesystem watch info.

fs.watch.ensure_watchable(fs, wrapper_class=<class 'fs.watch.PollingWatchableFS'>, *args, **kwds)

Ensure that the given fs supports watching, simulating it if necessary.

Given an FS object, this function returns an equivalent FS that has support for watcher callbacks. This may be the original object if it supports them natively, or a wrapper class if they must be simulated.

class fs.watch.iter_changes(fs=None, path='/', events=None, **kwds)

Blocking iterator over the change events produced by an FS.

This class can be used to transform the callback-based watcher mechanism into a blocking stream of events. It operates by having the callbacks push events onto a queue as they come in, then reading them off one at a time.