Metadata-Version: 1.0
Name: MacFSEvents
Version: 0.1
Summary: Thread-based interface to file system observation primitives.
Home-page: UNKNOWN
Author: Malthe Borch
Author-email: mborch@gmail.com
License: BSD
Description: .. contents::
        
        Overview
        ========
        
        .. role:: mod(emphasis)
        
        :mod:`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)
        
        This software was written by Malthe Borch <mborch@gmail.com>. The
        :mod:`pyfsevents` module by Nicolas Dumazet was used for reference.
        
        Why?
        ----
        
        At this time of writing there are three other libraries that integrate
        with the ``FSEvents`` API:
        
        **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.
        
        These issues have been addressed in :mod:`MacFSEvents`. The library
        provides a clean API and has full test coverage.
        
        Note that :mod:`pyfsevents` has code to support the observation of
        file descriptors. This functionality is on the to-do list.
        
        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(subpath, mask):
        ...
        
        from fsevents import Stream
        stream = Stream(callback, path)
        observer.schedule(stream)
        
        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. The
        ``subpath`` parameter contains the path at which the event happened (may
        be a subdirectory) while ``mask`` parameter is the event mask [#]_.
        
        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()
        
        .. [#] See `FSEventStreamEventFlags <http://developer.apple.com/mac/library/documentation/Darwin/Reference/FSEvents_Ref/FSEvents_h/index.html#//apple_ref/c/tag/FSEventStreamEventFlags>`_ for a reference. To check for a particular mask, use the *bitwise and* operator ``&``.
        
        
        Changelog
        =========
        
        0.1 (2000-11-27)
        ----------------
        
        - Initial public release.
        
Platform: Mac OS X
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 2.5
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Filesystems
