MacFSEvents is a Python library that provides thread-safe
directory observation primitives using callbacks. It wraps the Mac OS
FSEvents API in a C-extension.
- Mac OS X 10.5+ (Leopard)
- Python 2.7+
This software was written by Malthe Borch <email@example.com>. The pyfsevents module by Nicolas Dumazet was used for reference.
At this time of writing there are four other libraries that integrate
This library actually builds on the code in MacFSEvents (this project), but currently does not support Python 3 (though this should happen soon). It also includes shell utilities.
These use the PyObjC bridge infrastructure which most applications do not need.
Not thread-safe (API is not designed to support it).
Obsolete bindings to the socket API by John Sutherland.
The MacFSEvents library provides a clean API and has full test coverage.
Note that pyfsevents has bindings to the file descriptor observation primitives. This is not currently implemented by the present library.
Made available as-is under the BSD License.
To observe a directory structure (recursively) under
path, we set
up an observer thread and schedule an event stream:
from fsevents import Observer observer = Observer() observer.start() def callback(FileEvent): ... from fsevents import Stream stream = Stream(callback, path) observer.schedule(stream)
Streams can observe any number of paths; simply pass them as
positional arguments (or using the
stream = Stream(callback, *paths)
To start the observer in its own thread, use the
To start the observer in the current thread, use the
(it will block the thread until stopped from another thread):
The callback function will be called when an event occurs. Depending on the stream, the callback will have different signitures:
- the standard stream (with callback and paths) will call callback with parameters callback(path, mask) where path is the directory where a file changed and mask can be decoded using FS_FLAG* and FS_ITEM* constants . a convenience class Mask has a __str__ function to get a text representation of the flags.
- the stream is created with
ids = Truekeyword parameter. In this case the call is callback(path, mask, id). The id can be used in the
sincekeyword parameter of another stream object to also recieve historic events (that happened before the stream became active)
file_eventsis kwarg set to True, a
FileEventinstance is passed to the callback and has 3 attributes:
nameparameter contains the path at which the event happened (may be a subdirectory) while
maskparameter is the event mask. this mimicks
inotifybehaviour. see also below.
To stop observation, simply unschedule the stream and stop the observer:
While the observer thread will automatically join your main thread at this point, it doesn't hurt to be explicit about this:
We often want to know about events on a file level; to receive file
events instead of path events, pass in
file_events=True to the
def callback(event): ... stream = Stream(callback, path, file_events=True)
The event object mimick the file events of the
extension available in newer linux kernels. It has the following
- The mask field is a bitmask representing the event that occurred.
- The cookie field is a unique identifier linking together two related but separate events. It is used to link together an
- The name field contains the name of the object to which the event occurred. This is the absolute filename.
Note that the logic to implement file events is implemented in Python; a snapshot of the observed file system hierarchies is maintained and used to monitor file events.
|||See FSEventStreamEventFlags for a reference. To check for a particular mask, use the bitwise and operator |