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