Skip to main content

Thread-based interface to file system observation primitives.

Project description

Overview

MacFSEvents is a Python library that provides thread-safe directory observation primitives using callbacks. It wraps the Mac OS X FSEvents API in a C-extension.

Requirements:

  • Mac OS X 10.5+ (Leopard)

  • Python 2.7+

This software was written by Malthe Borch <mborch@gmail.com>. The pyfsevents module by Nicolas Dumazet was used for reference.

Why?

At this time of writing there are four other libraries that integrate with the FSEvents API:

watchdog:

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.

pyobjc-framework-FSEvents

These use the PyObjC bridge infrastructure which most applications do not need.

pyfsevents

Not thread-safe (API is not designed to support it).

fsevents

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.

License

Made available as-is under the BSD License.

Usage

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 * operator):

stream = Stream(callback, *paths)

To start the observer in its own thread, use the start method:

observer.starts()

To start the observer in the current thread, use the run method (it will block the thread until stopped from another thread):

observer.run()

The callback function will be called when an event occurs. A FileEvent instance is passed to the callback and has 3 attributes: mask, cookie and name. name parameter contains the path at which the event happened (may be a subdirectory) while mask parameter is the event mask [1].

To stop observation, simply unschedule the stream and stop the observer:

observer.unschedule(stream)
observer.stop()

While the observer thread will automatically join your main thread at this point, it doesn’t hurt to be explicit about this:

observer.join()

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 stream constructor:

def callback(event):
    ...

stream = Stream(callback, path, file_events=True)

The event object mimick the file events of the inotify kernel extension available in newer linux kernels. It has the following attributes:

mask

The mask field is a bitmask representing the event that occurred.

cookie

The cookie field is a unique identifier linking together two related but separate events. It is used to link together an IN_MOVED_FROM and an IN_MOVED_TO event.

name

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.

Changelog

0.4 (2014-10-23)

  • Do not use ‘Distribute’. It’s been deprecated

0.3 (2013-01-21)

  • Added compatibility with Python 3. Note that Python 2.7 or better is now required.

  • Fixed test suite on with 10.8. The event masks reported on this platform are non-trivial which is a change from previous versions.

0.2.8 (2012-06-09)

Bugfixes:

  • Fix recursive snapshot. [thomasst]

  • Use os.lstat instead of os.stat to correctly detect symlinks. [thomasst]

0.2.7 (2012-05-29)

  • Added support for IN_ATTRIB. [thomasst]

0.2.6 (2012-03-17)

  • Fixed compilation problem on newer platforms. [nsfmc]

0.2.5 (2012-02-01)

  • Ignore files that don’t exist while recursing. [bobveznat]

0.2.4 (2010-12-06)

  • Prevent crashes on recursive folder delete and multiple folder add. [totolici].

0.2.3 (2010-07-27)

  • Fixed broken release.

0.2.2 (2010-07-26)

  • Python 2.4 compatibility [howitz]

  • Fixed an issue where the addition of a new directory would crash the program when using file event monitoring [andymacp].

0.2.1 (2010-04-27)

  • Fixed an import issue [andymacp].

0.2 (2010-04-26)

  • Fixed issue where existing directories would be reported along with a newly created one [marcboeker].

  • Added support for file event monitoring.

  • Fixed reference counting bug which could result in a segmentation fault.

0.1 (2009-11-27)

  • Initial public release.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

MacFSEvents-0.4.tar.gz (11.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page