django-inotifier - a thin django wrapper around pyinotify

Author: Jay Wineinger <jay.wineinger@gmail.com>

This project provides a django pluggable app (inotifier) which aims to make
the use of pyinotify in a django project as easy as possible. Pyinotify
monitors files or directories for certain events and allows custom processing
when those events occur. The inotifier app provides management commands to
start and stop the pyinotify daemon, which can be configured with a single
required setting.

Users specify a path to monitor, a set of events to watch for, and a class to
process those events when they occur. Some sample event processor classes are
included, including ones that send django signals (also defined in this app),
which other apps can connect to. Event processor classes should conform to the
style directed by the pyinotify project.

Users can also define their own event processor classes which can do anything.
For instance, instead of sending django signals when certain events occur, the
event processor could add tasks to a queue or send a request to a web service.
In this case, the only benefit gained by using this app is the use of
the management commands which are provided for starting and stopping the
pyinotify daemon.

Note: Because inotify is a linux opearting system feature, pyinotify and this
project are only useable and useful on systems running linux.

1) Quickstart

    1.1) Install the inotifier application

    1.2) Add inotifier to INSTALLED_APPS
        -allows manage.py to find the management commands:
            "inotifier_start" - this starts the pyinotify daemon
            "inotifier_start" - this stops the pyinotify daemon

    1.3) Define settings in project settings.py

        1.3.1) INOTIFIER_WATCH_PATHS
            -required
            -An iterable of 3-tuples:
                [('/path/to/monitor',
                  <pyinotify event mask>,
                  '<event processor class>'),
                ]
            -see example in inotifier/settings_example.py

        1.3.2) INOTIFIER_DAEMON_STDOUT
            -optional
            -A string path to a file which will be used as stdout for the
             pyinotify daemon

        1.3.3) INOTIFIER_DAEMON_STDERR 
            -optional
            -A string path to a file which will be used as stderr for the
             pyinotify daemon

        1.3.4) PROJECT_PATH
            -optional
            -The path to the main project directory. Used to generate location
             for the 
             daemon pid file.  If not set, pid file will be put into /tmp.

    1.4) Start pyinotify daemon
        ./manage.py inotifier_start

    1.5) Stop pyinotify daemon
        -Obviously, only do this when you want to stop monitoring
        ./manage.py inotifier_stop

2) Defining your own event processor class

    2.1) Learn about it

        See the documentation for the pyinotify project on how to write an
        event processor.

        See event_processors.py in the inotifier app directory. There are a
        number of simple event processors there, plus a more complex one
        (CreateViaChunksSignaler).
        
        The event processor classes included in this app contain nothing
        specific to this app, besides the django stuff -- they are just event
        processors which will work with pyinotify.

    2.2) Create it

        Put your context processor class somewhere accessible by code in your
        project. The author's convention is to use myapp/event_processors.py.

    2.2) Use it

        Once you have defined your class, simply specify it as the class to
        handle a certain watch location in your INOTIFIER_WATCH_PATHS setting.
        
        For example, assume you added your class to
        myproject/myapp/event_processors.py as MySuperFunEventProcessor().

        If your project is NOT on PYTHONPATH, you would specify the
        <event processor class> as
        'myproject.myapp.event_processors.MySuperFunEventProcessor'.

        If your project IS on PYTHONPATH, then you would omit 'myproject' from
        the beginning and instead use
        'myapp.event_processors.MySuperFunEventProcessor'.
    
3) FAQ

    3.1) Q: How do I use this on <insert non-linux OS>?
         A: You can't.  inotify is a linux specific feature. Thus, pyinotify
            and this project will only work on linux.

4) Signals

    The inotifier app defines a number of django signals which map directly
    to the pyinotify events of the same name.  Each signal will be sent with
    the pyinotify event instance as the 'event' kwarg so that any custom
    processing done in signal handlers have access to all of the event
    information. 

    The provided AllEventsSignaler() and CreateSignaler() event processors
    class will send these signals.  However, should you have need for other
    signals to be sent, simply define them in your own app along with your
    own event processor, and send them from it.

    Note: All signals are defined as:
        <signal> = django.dispatch.Signal(providing_args=["event"])
    where the 'event' argument will be the pyinotify event instance.

    in_access
    in_attrib
    in_close_nowrite
    in_close_write
    in_create
    in_delete
    in_delete_self
    in_ignored
    in_modify
    in_move_self
    in_moved_from
    in_moved_to
    in_open
    in_q_overflow
    in_unmount